Interface Label

  • All Superinterfaces:
    it.unimi.dsi.lang.FlyweightPrototype<Label>
    All Known Implementing Classes:
    AbstractIntLabel, AbstractIntListLabel, AbstractLabel, AbstractLongListLabel, FixedWidthIntLabel, FixedWidthIntListLabel, FixedWidthLongListLabel, 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 type 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, long) and fromBitStream(InputBitStream, long) methods that serialise to a bitstream and deserialise to a bitstream a label, respectively. Since fromBitStream(InputBitStream, long) 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,long) and fromBitStream(InputBitStream,long) 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.

    • 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 by attributeKeys().
      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, long 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, long 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
      • EMPTY_LABEL_BIG_ARRAY

        static final Label[][] EMPTY_LABEL_BIG_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 by attributeKeys().
        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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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, an IllegalArgumentException 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 interface it.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 by ObjectParser 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,
                          long 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. If fixedWidth() is not negative, the value returned must coincide with fixedWidth(). 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,
                        long 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. If fixedWidth() is not negative, the value returned must coincide with fixedWidth(). 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.