Package org.apache.commons.lang3

Class BitField

java.lang.Object
org.apache.commons.lang3.BitField
public class BitField extends 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

    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

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • 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 Details

    • 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)

    • 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)

    • 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)

    • 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

    • 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:

    • 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:

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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:

    • 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: