Package org.apache.commons.lang3

## Class BitField

- java.lang.Object
- - org.apache.commons.lang3.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
`BitField​(int mask)` Creates a BitField instance.

### Method Summary

All Methods Instance Methods Concrete Methods
`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