Apache Commons Lang 3.20.0 · org.apache.commons.lang3.BitField

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

Modifier and Type	Field and Description
private final int	mask
private final int	shiftCount

Constructor Summary

Access	Constructor and Description
public	BitField(final int the mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on mask) Creates a BitField instance.

Method Summary

Modifier and Type	Method and Description
public int	Returns: the value of holder with the specified bits cleared (set to `0`) clear(final int the int data containing the bits we're interested in holder) Clears the bits.
public byte	Returns: the value of holder with the specified bits cleared (set to `0`) clearByte(final byte the byte data containing the bits we're interested in holder) Clears the bits.
public short	Returns: the value of holder with the specified bits cleared (set to `0`) clearShort(final short the short data containing the bits we're interested in holder) Clears the bits.
public int	Returns: the selected bits getRawValue(final int the int data containing the bits we're interested in holder) Obtains the value for the specified BitField, unshifted.
public short	Returns: the selected bits getShortRawValue(final short the short data containing the bits we're interested in holder) Obtains the value for the specified BitField, unshifted.
public short	Returns: the selected bits, shifted right appropriately getShortValue(final short the short data containing the bits we're interested in holder) Obtains the value for the specified BitField, appropriately shifted right, as a short.
public int	Returns: the selected bits, shifted right appropriately getValue(final int the int data containing the bits we're interested in holder) Obtains the value for the specified BitField, appropriately shifted right.
public boolean	Returns: `true` if all of the bits are set, else `false` isAllSet(final int the int data containing the bits we're interested in holder) Tests whether all of the bits are set or not.
public boolean	Returns: `true` if any of the bits are set, else `false` isSet(final int the int data containing the bits we're interested in holder) Tests whether the field is set or not.
public int	Returns: the value of holder with the specified bits set to `1` set(final int the int data containing the bits we're interested in holder) Sets the bits.
public int	Returns: the value of holder with the specified bits set or cleared setBoolean(final int the int data containing the bits we're interested in holder, final boolean indicating whether to set or clear the bits flag) Sets a boolean BitField.
public byte	Returns: the value of holder with the specified bits set to `1` setByte(final byte the byte data containing the bits we're interested in holder) Sets the bits.
public byte	Returns: the value of holder with the specified bits set or cleared setByteBoolean(final byte the byte data containing the bits we're interested in holder, final boolean indicating whether to set or clear the bits flag) Sets a boolean BitField.
public short	Returns: the value of holder with the specified bits set to `1` setShort(final short the short data containing the bits we're interested in holder) Sets the bits.
public short	Returns: the value of holder with the specified bits set or cleared setShortBoolean(final short the short data containing the bits we're interested in holder, final boolean indicating whether to set or clear the bits flag) Sets a boolean BitField.
public short	Returns: the value of holder with the bits from the value parameter replacing the old bits setShortValue(final short the short data containing the bits we're interested in holder, final short the new value for the specified bits value) Replaces the bits with new values.
public int	Returns: the value of holder with the bits from the value parameter replacing the old bits setValue(final int the int data containing the bits we're interested in holder, final int the new value for the specified bits value) Replaces the bits with new values.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

mask	back to summary
private final int mask

shiftCount	back to summary
private final int shiftCount

Constructor Detail

BitField	back to summary
public BitField(final int mask) Creates a BitField instance. Parameters mask:int the mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on

BitField

back to summary

public BitField(final int mask)

Creates a BitField instance.

Parameters

mask:int: 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

clear back to summary

clear	back to summary
public int clear(final int holder) Clears the bits. Parameters holder:int the int data containing the bits we're interested in Returns:int the value of holder with the specified bits cleared (set to `0`)

public int clear(final int holder)

Clears the bits.

Parameters

holder:int: the int data containing the bits we're interested in

Returns:int

the value of holder with the specified bits cleared (set to 0)

clearByte back to summary

clearByte	back to summary
public byte clearByte(final byte holder) Clears the bits. Parameters holder:byte the byte data containing the bits we're interested in Returns:byte the value of holder with the specified bits cleared (set to `0`)

public byte clearByte(final byte holder)

Clears the bits.

Parameters

holder:byte: the byte data containing the bits we're interested in

Returns:byte

the value of holder with the specified bits cleared (set to 0)

clearShort back to summary

clearShort	back to summary
public short clearShort(final short holder) Clears the bits. Parameters holder:short the short data containing the bits we're interested in Returns:short the value of holder with the specified bits cleared (set to `0`)

public short clearShort(final short holder)

Clears the bits.

Parameters

holder:short: the short data containing the bits we're interested in

Returns:short

the value of holder with the specified bits cleared (set to 0)

getRawValue	back to summary
public int getRawValue(final int holder) Obtains the value for the specified BitField, unshifted. Parameters holder:int the int data containing the bits we're interested in Returns:int the selected bits

getRawValue

back to summary

public int getRawValue(final int holder)

Obtains the value for the specified BitField, unshifted.

Parameters

holder:int: the int data containing the bits we're interested in

Returns:int

the selected bits

getShortRawValue	back to summary
public short getShortRawValue(final short holder) Obtains the value for the specified BitField, unshifted. Parameters holder:short the short data containing the bits we're interested in Returns:short the selected bits

getShortRawValue

back to summary

public short getShortRawValue(final short holder)

Obtains the value for the specified BitField, unshifted.

Parameters

holder:short: the short data containing the bits we're interested in

Returns:short

the selected bits

getShortValue back to summary

getShortValue	back to summary
public short getShortValue(final 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:short the short data containing the bits we're interested in Returns:short the selected bits, shifted right appropriately See Also `setShortValue(short, short)`

public short getShortValue(final 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:short: the short data containing the bits we're interested in

Returns:short

the selected bits, shifted right appropriately

See Also

setShortValue(short, short)

getValue back to summary

getValue	back to summary
public int getValue(final 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:int the int data containing the bits we're interested in Returns:int the selected bits, shifted right appropriately See Also `setValue(int, int)`

public int getValue(final 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:int: the int data containing the bits we're interested in

Returns:int

the selected bits, shifted right appropriately

See Also

setValue(int, int)

isAllSet back to summary

isAllSet	back to summary
public boolean isAllSet(final int holder) Tests 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:int the int data containing the bits we're interested in Returns:boolean `true` if all of the bits are set, else `false`

public boolean isAllSet(final int holder)

Tests 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:int: the int data containing the bits we're interested in

Returns:boolean

true if all of the bits are set, else false

isSet back to summary

isSet	back to summary
public boolean isSet(final int holder) Tests 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:int the int data containing the bits we're interested in Returns:boolean `true` if any of the bits are set, else `false`

public boolean isSet(final int holder)

Tests 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:int: the int data containing the bits we're interested in

Returns:boolean

true if any of the bits are set, else false

set back to summary

set	back to summary
public int set(final int holder) Sets the bits. Parameters holder:int the int data containing the bits we're interested in Returns:int the value of holder with the specified bits set to `1`

public int set(final int holder)

Sets the bits.

Parameters

holder:int: the int data containing the bits we're interested in

Returns:int

the value of holder with the specified bits set to 1

setBoolean	back to summary
public int setBoolean(final int holder, final boolean flag) Sets a boolean BitField. Parameters holder:int the int data containing the bits we're interested in flag:boolean indicating whether to set or clear the bits Returns:int the value of holder with the specified bits set or cleared

setBoolean

back to summary

public int setBoolean(final int holder, final boolean flag)

Sets a boolean BitField.

Parameters

holder:int: the int data containing the bits we're interested in
flag:boolean: indicating whether to set or clear the bits

Returns:int

the value of holder with the specified bits set or cleared

setByte back to summary

setByte	back to summary
public byte setByte(final byte holder) Sets the bits. Parameters holder:byte the byte data containing the bits we're interested in Returns:byte the value of holder with the specified bits set to `1`

public byte setByte(final byte holder)

Sets the bits.

Parameters

holder:byte: the byte data containing the bits we're interested in

Returns:byte

the value of holder with the specified bits set to 1

setByteBoolean	back to summary
public byte setByteBoolean(final byte holder, final boolean flag) Sets a boolean BitField. Parameters holder:byte the byte data containing the bits we're interested in flag:boolean indicating whether to set or clear the bits Returns:byte the value of holder with the specified bits set or cleared

setByteBoolean

back to summary

public byte setByteBoolean(final byte holder, final boolean flag)

Sets a boolean BitField.

Parameters

holder:byte: the byte data containing the bits we're interested in
flag:boolean: indicating whether to set or clear the bits

Returns:byte

the value of holder with the specified bits set or cleared

setShort back to summary

setShort	back to summary
public short setShort(final short holder) Sets the bits. Parameters holder:short the short data containing the bits we're interested in Returns:short the value of holder with the specified bits set to `1`

public short setShort(final short holder)

Sets the bits.

Parameters

holder:short: the short data containing the bits we're interested in

Returns:short

the value of holder with the specified bits set to 1

setShortBoolean	back to summary
public short setShortBoolean(final short holder, final boolean flag) Sets a boolean BitField. Parameters holder:short the short data containing the bits we're interested in flag:boolean indicating whether to set or clear the bits Returns:short the value of holder with the specified bits set or cleared

setShortBoolean

back to summary

public short setShortBoolean(final short holder, final boolean flag)

Sets a boolean BitField.

Parameters

holder:short: the short data containing the bits we're interested in
flag:boolean: indicating whether to set or clear the bits

Returns:short

the value of holder with the specified bits set or cleared

setShortValue back to summary

setShortValue	back to summary
public short setShortValue(final short holder, final short value) Replaces the bits with new values. Parameters holder:short the short data containing the bits we're interested in value:short the new value for the specified bits Returns:short the value of holder with the bits from the value parameter replacing the old bits See Also `getShortValue(short)`

public short setShortValue(final short holder, final short value)

Replaces the bits with new values.

Parameters

holder:short: the short data containing the bits we're interested in
value:short: the new value for the specified bits

Returns:short

the value of holder with the bits from the value parameter replacing the old bits

See Also

getShortValue(short)

setValue back to summary

setValue	back to summary
public int setValue(final int holder, final int value) Replaces the bits with new values. Parameters holder:int the int data containing the bits we're interested in value:int the new value for the specified bits Returns:int the value of holder with the bits from the value parameter replacing the old bits See Also `getValue(int)`

public int setValue(final int holder, final int value)

Replaces the bits with new values.

Parameters

holder:int: the int data containing the bits we're interested in
value:int: the new value for the specified bits

Returns:int

the value of holder with the bits from the value parameter replacing the old bits

See Also

getValue(int)

public Class BitField

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail