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 and Description
    `BitField(int mask)` Creates a BitField instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 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

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.