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.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int clear​(int holder)
      Clears the bits.
      byte clearByte​(byte holder)
      Clears the bits.
      short clearShort​(short holder)
      Clears the bits.
      int getRawValue​(int holder)
      Obtains the value for the specified BitField, unshifted.
      short getShortRawValue​(short holder)
      Obtains the value for the specified BitField, unshifted.
      short getShortValue​(short holder)
      Obtains the value for the specified BitField, appropriately shifted right, as a short.
      int getValue​(int holder)
      Obtains the value for the specified BitField, appropriately shifted right.
      boolean isAllSet​(int holder)
      Returns whether all of the bits are set or not.
      boolean isSet​(int holder)
      Returns whether the field is set or not.
      int set​(int holder)
      Sets the bits.
      int setBoolean​(int 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)
      Replaces the bits with new values.
      int setValue​(int holder, int value)
      Replaces the bits with new values.
      • Methods inherited from class java.lang.Object

        equals, 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
    • Method Detail

      • getValue

        public int getValue​(int holder)

        Obtains 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
        See Also:
        setValue(int,int)
      • getShortValue

        public short getShortValue​(short holder)

        Obtains 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
        See Also:
        setShortValue(short,short)
      • getRawValue

        public int getRawValue​(int holder)

        Obtains the value for the specified BitField, unshifted.

        Parameters:
        holder - the int data containing the bits we're interested in
        Returns:
        the selected bits
      • getShortRawValue

        public short getShortRawValue​(short holder)

        Obtains the value for the specified BitField, unshifted.

        Parameters:
        holder - the short data containing the bits we're interested in
        Returns:
        the selected bits
      • isSet

        public boolean isSet​(int holder)

        Returns 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
      • isAllSet

        public boolean isAllSet​(int holder)

        Returns 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
      • setValue

        public int setValue​(int holder,
                            int value)

        Replaces 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
        See Also:
        getValue(int)
      • setShortValue

        public short setShortValue​(short holder,
                                   short value)

        Replaces 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
        See Also:
        getShortValue(short)
      • 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)
      • 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)
      • 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)
      • 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
      • 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
      • 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
      • 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
      • 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
      • 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