Class BitField


  • public class BitField
    extends java.lang.Object
    Supports operations on bit-mapped fields. Instances of this class can be used to store a flag or data within an int, short or byte.

    Each BitField is constructed with a mask value, which indicates the bits that will be used to store and retrieve the data for that field. For instance, the mask 0xFF indicates the least-significant byte should be used to store the data.

    As an example, consider a car painting machine that accepts paint instructions as integers. Bit fields can be used to encode this:

    
     // blue, green and red are 1 byte values (0-255) stored in the three least
     // significant bytes
     BitField blue = new BitField(0xFF);
    
     BitField green = new BitField(0xFF00);
    
     BitField red = new BitField(0xFF0000);
    
     // anyColor is a flag triggered if any color is used
     BitField anyColor = new BitField(0xFFFFFF);
    
     // isMetallic is a single bit flag
     BitField isMetallic = new BitField(0x1000000);
     

    Using these BitField instances, a paint instruction can be encoded into an integer:

     int paintInstruction = 0;
     paintInstruction = red.setValue(paintInstruction, 35);
     paintInstruction = green.setValue(paintInstruction, 100);
     paintInstruction = blue.setValue(paintInstruction, 255);
     

    Flags and data can be retrieved from the integer:

     // Prints true if red, green or blue is non-zero
     System.out.println(anyColor.isSet(paintInstruction)); // prints true
     // Prints value of red, green and blue
     System.out.println(red.getValue(paintInstruction)); // prints 35
     System.out.println(green.getValue(paintInstruction)); // prints 100
     System.out.println(blue.getValue(paintInstruction)); // prints 255
     // Prints true if isMetallic was set
     System.out.println(isMetallic.isSet(paintInstruction)); // prints false
     
    Since:
    2.0
    • Constructor Summary

      Constructors 
      Constructor Description
      BitField​(int mask)
      Creates a BitField instance.
      BitField​(long mask)
      Creates a BitField instance.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int clear​(int holder)
      Clears the bits.
      long clear​(long holder)
      Clears the bits.
      byte clearByte​(byte holder)
      Clears the bits.
      short clearShort​(short holder)
      Clears the bits.
      int getRawValue​(int holder)
      Gets the value for the specified BitField, unshifted.
      long getRawValue​(long holder)
      Gets the value for the specified BitField, unshifted.
      short getShortRawValue​(short holder)
      Gets the value for the specified BitField, unshifted.
      short getShortValue​(short holder)
      Gets the value for the specified BitField, appropriately shifted right, as a short.
      int getValue​(int holder)
      Gets the value for the specified BitField, appropriately shifted right.
      long getValue​(long holder)
      Gets the value for the specified BitField, appropriately shifted right.
      boolean isAllSet​(int holder)
      Tests whether all of the bits are set or not.
      boolean isAllSet​(long holder)
      Tests whether all of the bits are set or not.
      boolean isSet​(int holder)
      Tests whether the field is set or not.
      boolean isSet​(long holder)
      Tests whether the field is set or not.
      int set​(int holder)
      Sets the bits.
      long set​(long holder)
      Sets the bits.
      int setBoolean​(int holder, boolean flag)
      Sets a boolean BitField.
      long setBoolean​(long holder, boolean flag)
      Sets a boolean BitField.
      byte setByte​(byte holder)
      Sets the bits.
      byte setByteBoolean​(byte holder, boolean flag)
      Sets a boolean BitField.
      short setShort​(short holder)
      Sets the bits.
      short setShortBoolean​(short holder, boolean flag)
      Sets a boolean BitField.
      short setShortValue​(short holder, short value)
      Sets the bits with new values.
      int setValue​(int holder, int value)
      Sets the bits with new values.
      long setValue​(long holder, long value)
      Sets the bits with new values.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • BitField

        public BitField​(int mask)
        Creates a BitField instance.
        Parameters:
        mask - The mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
      • BitField

        public BitField​(long mask)
        Creates a BitField instance.

        If any bit above bit 31 is set in the mask, the resulting field can only be used with the long holder accessors; the int, short and byte holder accessors throw IllegalStateException for such a field, because those holder types cannot contain the masked bits and would otherwise silently answer wrongly (shift counts are truncated mod 32 and negative holders are sign-extended into bits 32-63).

        Parameters:
        mask - The mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
        Since:
        3.21.0
    • Method Detail

      • clear

        public int clear​(int holder)
        Clears the bits.
        Parameters:
        holder - The int data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits cleared (set to 0).
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • clear

        public long clear​(long holder)
        Clears the bits.
        Parameters:
        holder - The long data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits cleared (set to 0).
        Since:
        3.21.0
      • clearByte

        public byte clearByte​(byte holder)
        Clears the bits.
        Parameters:
        holder - The byte data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits cleared (set to 0).
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • clearShort

        public short clearShort​(short holder)
        Clears the bits.
        Parameters:
        holder - The short data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits cleared (set to 0).
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • getRawValue

        public int getRawValue​(int holder)
        Gets the value for the specified BitField, unshifted.
        Parameters:
        holder - The int data containing the bits we're interested in.
        Returns:
        The selected bits.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • getRawValue

        public long getRawValue​(long holder)
        Gets the value for the specified BitField, unshifted.
        Parameters:
        holder - The long data containing the bits we're interested in.
        Returns:
        The selected bits.
        Since:
        3.21.0
      • getShortRawValue

        public short getShortRawValue​(short holder)
        Gets the value for the specified BitField, unshifted.
        Parameters:
        holder - The short data containing the bits we're interested in.
        Returns:
        The selected bits.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • getShortValue

        public short getShortValue​(short holder)
        Gets the value for the specified BitField, appropriately shifted right, as a short.

        Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and so shifted left so many bits).

        Parameters:
        holder - The short data containing the bits we're interested in.
        Returns:
        The selected bits, shifted right appropriately.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
        See Also:
        setShortValue(short,short)
      • getValue

        public int getValue​(int holder)
        Gets the value for the specified BitField, appropriately shifted right.

        Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and so shifted left so many bits).

        Parameters:
        holder - The int data containing the bits we're interested in.
        Returns:
        The selected bits, shifted right appropriately.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
        See Also:
        setValue(int,int)
      • getValue

        public long getValue​(long holder)
        Gets the value for the specified BitField, appropriately shifted right.

        Many users of a BitField will want to treat the specified bits as an long value, and will not want to be aware that the value is stored as a BitField (and so shifted left so many bits).

        Parameters:
        holder - The long data containing the bits we're interested in.
        Returns:
        The selected bits, shifted right appropriately.
        Since:
        3.21.0
        See Also:
        setValue(long,long)
      • isAllSet

        public boolean isAllSet​(int holder)
        Tests whether all of the bits are set or not.

        This is a stricter test than isSet(int), in that all of the bits in a multi-bit set must be set for this method to return true.

        Parameters:
        holder - The int data containing the bits we're interested in.
        Returns:
        true if all of the bits are set, else false.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • isAllSet

        public boolean isAllSet​(long holder)
        Tests whether all of the bits are set or not.

        This is a stricter test than isSet(long), in that all of the bits in a multi-bit set must be set for this method to return true.

        Parameters:
        holder - The long data containing the bits we're interested in.
        Returns:
        true if all of the bits are set, else false.
        Since:
        3.21.0
      • isSet

        public boolean isSet​(int holder)
        Tests whether the field is set or not.

        This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to determine whether any of its bits are set.

        Parameters:
        holder - The int data containing the bits we're interested in
        Returns:
        true if any of the bits are set, else false
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • isSet

        public boolean isSet​(long holder)
        Tests whether the field is set or not.

        This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to determine whether any of its bits are set.

        Parameters:
        holder - The long data containing the bits we're interested in
        Returns:
        true if any of the bits are set, else false
        Since:
        3.21.0
      • set

        public int set​(int holder)
        Sets the bits.
        Parameters:
        holder - The int data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits set to 1.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • set

        public long set​(long holder)
        Sets the bits.
        Parameters:
        holder - The long data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits set to 1.
        Since:
        3.21.0
      • setBoolean

        public int setBoolean​(int holder,
                              boolean flag)
        Sets a boolean BitField.
        Parameters:
        holder - The int data containing the bits we're interested in.
        flag - indicating whether to set or clear the bits.
        Returns:
        The value of holder with the specified bits set or cleared.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • setBoolean

        public long setBoolean​(long holder,
                               boolean flag)
        Sets a boolean BitField.
        Parameters:
        holder - The long data containing the bits we're interested in.
        flag - indicating whether to set or clear the bits.
        Returns:
        The value of holder with the specified bits set or cleared.
        Since:
        3.21.0
      • setByte

        public byte setByte​(byte holder)
        Sets the bits.
        Parameters:
        holder - The byte data containing the bits we're interested in
        Returns:
        The value of holder with the specified bits set to 1
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • setByteBoolean

        public byte setByteBoolean​(byte holder,
                                   boolean flag)
        Sets a boolean BitField.
        Parameters:
        holder - The byte data containing the bits we're interested in.
        flag - indicating whether to set or clear the bits.
        Returns:
        The value of holder with the specified bits set or cleared.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • setShort

        public short setShort​(short holder)
        Sets the bits.
        Parameters:
        holder - The short data containing the bits we're interested in.
        Returns:
        The value of holder with the specified bits set to 1.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • setShortBoolean

        public short setShortBoolean​(short holder,
                                     boolean flag)
        Sets a boolean BitField.
        Parameters:
        holder - The short data containing the bits we're interested in.
        flag - indicating whether to set or clear the bits.
        Returns:
        The value of holder with the specified bits set or cleared.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
      • setShortValue

        public short setShortValue​(short holder,
                                   short value)
        Sets the bits with new values.
        Parameters:
        holder - The short data containing the bits we're interested in
        value - The new value for the specified bits
        Returns:
        The value of holder with the bits from the value parameter replacing the old bits
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
        See Also:
        getShortValue(short)
      • setValue

        public int setValue​(int holder,
                            int value)
        Sets the bits with new values.
        Parameters:
        holder - The int data containing the bits we're interested in.
        value - The new value for the specified bits.
        Returns:
        The value of holder with the bits from the value parameter replacing the old bits.
        Throws:
        java.lang.IllegalStateException - Thrown if this field's mask has bits set above bit 31 (only possible via BitField(long)) and so cannot be represented in this holder type.
        See Also:
        getValue(int)
      • setValue

        public long setValue​(long holder,
                             long value)
        Sets the bits with new values.
        Parameters:
        holder - The long data containing the bits we're interested in.
        value - The new value for the specified bits.
        Returns:
        The value of holder with the bits from the value parameter replacing the old bits.
        Since:
        3.21.0
        See Also:
        getValue(long)