Interface Label
-
- All Superinterfaces:
it.unimi.dsi.lang.FlyweightPrototype<Label>
- All Known Implementing Classes:
AbstractIntLabel
,AbstractIntListLabel
,AbstractLabel
,FixedWidthIntLabel
,FixedWidthIntListLabel
,GammaCodedIntLabel
public interface Label extends it.unimi.dsi.lang.FlyweightPrototype<Label>
A set of attributes that can be used to decorate a node or an arc of a graph. Attributes appear in the form of <key,value> pairs, where keys are of typeString
. Among attributes, one (called the well-known attribute), has a special status: its key can be obtained by using thewellKnownAttributeKey()
method.Values associated to attributes can be anything: the value can be obtained (in the form of an object) with
get(String)
. If the value is of primitive type, the alternative type-specific method (e.g.,getInt(String)
, orgetChar(String)
) can be called, with the proviso that such methods may throw anIllegalArgumentException
if the attribute type can not be converted to the one specified without loss of information.The value of the well-known attribute can be obtained with
get()
, or with the appropriate type-specific version of the method.Serialisation
Implementations must provide
toBitStream(OutputBitStream, int)
andfromBitStream(InputBitStream, int)
methods that serialise to a bitstream and deserialise to a bitstream a label, respectively. SincefromBitStream(InputBitStream, int)
has no length information, the label format must be self-delimiting. This can be obtained with a fixed length scheme (see, e.g.,FixedWidthIntLabel
), or using self-delimiting codes (see, e.g.,GammaCodedIntLabel
).The methods
toBitStream(OutputBitStream,int)
andfromBitStream(InputBitStream,int)
are given as an additional information the number of source node of the arc over which this label is put. They may use this information to decide how the label should be stored (typically, to do a more clever compression job).The advantage of fixed-width labels (i.e., those for which
fixedWidth()
does not return -1) is that when loading aBitStreamArcLabelledImmutableGraph
with an offset step larger than 1 the position in the bitstream for the labels of a node can be calculated more quickly, as the computation just requires the outdegree of the nodes, whereas in general one has to skip in-between labels with an explicit deserialisation.String-based constructors
By convention, all concrete classes implementing this interface must follow the
ObjectParser
conventions: in particular, they must provide a constructor accepting strings (either in fixed or variable number) where the first string is the key. The constructor must perform data validation and build an instance with a default value (e.g., 0 for numerical labels). The constructor is used, for instance, byBitStreamArcLabelledImmutableGraph
to instantiate a label prototype. Finally, the methodtoSpec()
must return a string that is accepted byObjectParser
.
-
-
Field Summary
Fields Modifier and Type Field Description static Label[]
EMPTY_LABEL_ARRAY
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.String[]
attributeKeys()
All attribute keys (in arbitrary order).java.lang.Class<?>[]
attributeTypes()
The types of all attributes in the same order as they are returned byattributeKeys()
.Label
copy()
Returns a copy of this label.int
fixedWidth()
Returns the fixed length of this label, in bits, if this label has fixed width.int
fromBitStream(it.unimi.dsi.io.InputBitStream inputBitStream, int source)
Fills this label with data from the given input bit stream, knowing the source node of the arc.java.lang.Object
get()
The value associated to the well-known attribute.java.lang.Object
get(java.lang.String key)
The value associated to the attribute with given key.boolean
getBoolean()
The value associated to the well-known attribute, provided that the latter has a type that fits a boolean.boolean
getBoolean(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a boolean.byte
getByte()
The value associated to the well-known attribute, provided that the latter has a type that fits a byte.byte
getByte(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a byte.char
getChar()
The value associated to the well-known attribute, provided that the latter has a type that fits a char.char
getChar(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a char.double
getDouble()
The value associated to the well-known attribute, provided that the latter has a type that fits a double.double
getDouble(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a double.float
getFloat()
The value associated to the well-known attribute, provided that the latter has a type that fits a float.float
getFloat(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a float.int
getInt()
The value associated to the well-known attribute, provided that the latter has a type that fits a int.int
getInt(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a int.long
getLong()
The value associated to the well-known attribute, provided that the latter has a type that fits a long.long
getLong(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a long.short
getShort()
The value associated to the well-known attribute, provided that the latter has a type that fits a short.short
getShort(java.lang.String key)
The value associated to the attribute with given key, provided that the latter has a type that fits a short.int
toBitStream(it.unimi.dsi.io.OutputBitStream outputBitStream, int source)
Writes out this label to the given input bit stream, in self-delimiting form, knowing the source node of the arc.java.lang.String
toSpec()
Returns a string representing the specification of this label.java.lang.String
wellKnownAttributeKey()
Returns the well-known attribute key.
-
-
-
Field Detail
-
EMPTY_LABEL_ARRAY
static final Label[] EMPTY_LABEL_ARRAY
-
-
Method Detail
-
wellKnownAttributeKey
java.lang.String wellKnownAttributeKey()
Returns the well-known attribute key.- Returns:
- the well-known attribute key.
-
attributeKeys
java.lang.String[] attributeKeys()
All attribute keys (in arbitrary order).- Returns:
- the keys of all attributes.
-
attributeTypes
java.lang.Class<?>[] attributeTypes()
The types of all attributes in the same order as they are returned byattributeKeys()
.- Returns:
- the type of all attributes.
-
get
java.lang.Object get(java.lang.String key) throws java.util.NoSuchElementException
The value associated to the attribute with given key.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.util.NoSuchElementException
- if the attribute key is not one of the attributes of this label.
-
getByte
byte getByte(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a byte. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getShort
short getShort(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a short. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getInt
int getInt(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a int. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getLong
long getLong(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a long. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getFloat
float getFloat(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a float. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getDouble
double getDouble(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a double. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getChar
char getChar(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a char. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getBoolean
boolean getBoolean(java.lang.String key) throws java.lang.IllegalArgumentException
The value associated to the attribute with given key, provided that the latter has a type that fits a boolean. Otherwise, anIllegalArgumentException
is thrown.- Parameters:
key
- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
get
java.lang.Object get() throws java.util.NoSuchElementException
The value associated to the well-known attribute.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.util.NoSuchElementException
-
getByte
byte getByte() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a byte. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getShort
short getShort() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a short. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getInt
int getInt() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a int. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getLong
long getLong() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a long. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getFloat
float getFloat() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a float.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getDouble
double getDouble() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a double. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getChar
char getChar() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a char. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
getBoolean
boolean getBoolean() throws java.lang.IllegalArgumentException
The value associated to the well-known attribute, provided that the latter has a type that fits a boolean. Otherwise, anIllegalArgumentException
is thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
java.lang.IllegalArgumentException
- if the attribute key is not known, or it has the wrong type.
-
copy
Label copy()
Returns a copy of this label.- Specified by:
copy
in interfaceit.unimi.dsi.lang.FlyweightPrototype<Label>
- Returns:
- a new label that copies this one.
-
toSpec
java.lang.String toSpec()
Returns a string representing the specification of this label.Each label class can be instantiated in several ways (e.g.,
FixedWidthIntLabel
requires a name for the well-known attribute and a number of bits). This method must return a representation that can be used byObjectParser
to instantiate the class, and consequently there must exist a matching constructor whose arguments are strings.There is an equation that must be always satisfied:
ObjectParser.fromSpec(x.toSpec()).toSpec().equals(x.toSpec())
- Returns:
- a string representing the specification of this label.
- See Also:
ObjectParser.fromSpec(String, Class)
-
fromBitStream
int fromBitStream(it.unimi.dsi.io.InputBitStream inputBitStream, int source) throws java.io.IOException, java.lang.UnsupportedOperationException
Fills this label with data from the given input bit stream, knowing the source node of the arc. IffixedWidth()
is not negative, the value returned must coincide withfixedWidth()
. This method is optional.- Parameters:
inputBitStream
- an input bit stream offering a label.source
- the source node.- Returns:
- the number of bits read to fill this label.
- Throws:
java.io.IOException
java.lang.UnsupportedOperationException
-
toBitStream
int toBitStream(it.unimi.dsi.io.OutputBitStream outputBitStream, int source) throws java.io.IOException, java.lang.UnsupportedOperationException
Writes out this label to the given input bit stream, in self-delimiting form, knowing the source node of the arc. IffixedWidth()
is not negative, the value returned must coincide withfixedWidth()
. This method is optional.- Parameters:
outputBitStream
- an output bit stream where the label will be written.source
- the source node.- Returns:
- the number of bits written.
- Throws:
java.io.IOException
java.lang.UnsupportedOperationException
-
fixedWidth
int fixedWidth()
Returns the fixed length of this label, in bits, if this label has fixed width.- Returns:
- the fixed length of this label, or -1 if this label has not fixed width.
-
-