BitField (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3, class: BitField

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:
      - `setShortValue(short,short)`

  - ### 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)`

  - ### 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:
      - `getShortValue(short)`

  - ### 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)`