Interface Label
- All Superinterfaces:
it.unimi.dsi.lang.FlyweightPrototype<Label>
- All Known Implementing Classes:
AbstractIntLabel,AbstractIntListLabel,AbstractLabel,FixedWidthIntLabel,FixedWidthIntListLabel,GammaCodedIntLabel
String. Among attributes,
one (called the well-known attribute), has a special status:
its key can be obtained by using the wellKnownAttributeKey() 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), or getChar(String)) can be
called, with the proviso that such methods may throw an IllegalArgumentException
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) and fromBitStream(InputBitStream, int)
methods that serialise to a bitstream and deserialise to a bitstream a label, respectively. Since
fromBitStream(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)
and fromBitStream(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 a BitStreamArcLabelledImmutableGraph 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, by BitStreamArcLabelledImmutableGraph to instantiate a label prototype.
Finally, the method toSpec() must return a string that is accepted by ObjectParser.
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionString[]All attribute keys (in arbitrary order).Class<?>[]The types of all attributes in the same order as they are returned byattributeKeys().copy()Returns a copy of this label.intReturns the fixed length of this label, in bits, if this label has fixed width.intfromBitStream(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.get()The value associated to the well-known attribute.The value associated to the attribute with given key.booleanThe value associated to the well-known attribute, provided that the latter has a type that fits a boolean.booleangetBoolean(String key) The value associated to the attribute with given key, provided that the latter has a type that fits a boolean.bytegetByte()The value associated to the well-known attribute, provided that the latter has a type that fits a byte.byteThe value associated to the attribute with given key, provided that the latter has a type that fits a byte.chargetChar()The value associated to the well-known attribute, provided that the latter has a type that fits a char.charThe value associated to the attribute with given key, provided that the latter has a type that fits a char.doubleThe value associated to the well-known attribute, provided that the latter has a type that fits a double.doubleThe value associated to the attribute with given key, provided that the latter has a type that fits a double.floatgetFloat()The value associated to the well-known attribute, provided that the latter has a type that fits a float.floatThe value associated to the attribute with given key, provided that the latter has a type that fits a float.intgetInt()The value associated to the well-known attribute, provided that the latter has a type that fits a int.intThe value associated to the attribute with given key, provided that the latter has a type that fits a int.longgetLong()The value associated to the well-known attribute, provided that the latter has a type that fits a long.longThe value associated to the attribute with given key, provided that the latter has a type that fits a long.shortgetShort()The value associated to the well-known attribute, provided that the latter has a type that fits a short.shortThe value associated to the attribute with given key, provided that the latter has a type that fits a short.inttoBitStream(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.toSpec()Returns a string representing the specification of this label.Returns the well-known attribute key.
-
Field Details
-
EMPTY_LABEL_ARRAY
-
-
Method Details
-
wellKnownAttributeKey
String wellKnownAttributeKey()Returns the well-known attribute key.- Returns:
- the well-known attribute key.
-
attributeKeys
String[] attributeKeys()All attribute keys (in arbitrary order).- Returns:
- the keys of all attributes.
-
attributeTypes
Class<?>[] attributeTypes()The types of all attributes in the same order as they are returned byattributeKeys().- Returns:
- the type of all attributes.
-
get
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:
NoSuchElementException- if the attribute key is not one of the attributes of this label.
-
getByte
The value associated to the attribute with given key, provided that the latter has a type that fits a byte. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getShort
The value associated to the attribute with given key, provided that the latter has a type that fits a short. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getInt
The value associated to the attribute with given key, provided that the latter has a type that fits a int. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getLong
The value associated to the attribute with given key, provided that the latter has a type that fits a long. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getFloat
The value associated to the attribute with given key, provided that the latter has a type that fits a float. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getDouble
The value associated to the attribute with given key, provided that the latter has a type that fits a double. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getChar
The value associated to the attribute with given key, provided that the latter has a type that fits a char. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getBoolean
The value associated to the attribute with given key, provided that the latter has a type that fits a boolean. Otherwise, anIllegalArgumentExceptionis thrown.- Parameters:
key- the attribute key.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
get
The value associated to the well-known attribute.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
NoSuchElementException
-
getByte
The value associated to the well-known attribute, provided that the latter has a type that fits a byte. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getShort
The value associated to the well-known attribute, provided that the latter has a type that fits a short. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getInt
The value associated to the well-known attribute, provided that the latter has a type that fits a int. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getLong
The value associated to the well-known attribute, provided that the latter has a type that fits a long. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getFloat
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:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getDouble
The value associated to the well-known attribute, provided that the latter has a type that fits a double. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getChar
The value associated to the well-known attribute, provided that the latter has a type that fits a char. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
IllegalArgumentException- if the attribute key is not known, or it has the wrong type.
-
getBoolean
The value associated to the well-known attribute, provided that the latter has a type that fits a boolean. Otherwise, anIllegalArgumentExceptionis thrown.- Returns:
- the attribute value; if the attribute type is primitive, it is wrapped suitably.
- Throws:
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:
copyin interfaceit.unimi.dsi.lang.FlyweightPrototype<Label>- Returns:
- a new label that copies this one.
-
toSpec
String toSpec()Returns a string representing the specification of this label.Each label class can be instantiated in several ways (e.g.,
FixedWidthIntLabelrequires a name for the well-known attribute and a number of bits). This method must return a representation that can be used byObjectParserto 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:
-
fromBitStream
int fromBitStream(it.unimi.dsi.io.InputBitStream inputBitStream, int source) throws IOException, 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:
IOExceptionUnsupportedOperationException
-
toBitStream
int toBitStream(it.unimi.dsi.io.OutputBitStream outputBitStream, int source) throws IOException, 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:
IOExceptionUnsupportedOperationException
-
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.
-