BitField¶

public class org.apache.commons.lang3.BitField[source]¶

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

Constructors¶

`BitField(int)`	Creates a BitField instance.
`BitField(long)`	Creates a BitField instance.

public BitField(int mask)[source]¶

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.

public BitField(long mask)[source]¶

Creates a BitField instance.

If any bit above bit 31 is set in the mask, the resulting field can only be used with the long holder accessors; the int, short and byte holder accessors throw IllegalStateException for such a field, because those holder types cannot contain the masked bits and would otherwise silently answer wrongly (shift counts are truncated mod 32 and negative holders are sign-extended into bits 32-63).

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.
Since:: 3.21.0

Methods¶

`clear(int)`	Clears the bits.
`clear(long)`	Clears the bits.
`clearByte(byte)`	Clears the bits.
`clearShort(short)`	Clears the bits.
`getRawValue(int)`	Gets the value for the specified BitField, unshifted.
`getRawValue(long)`	Gets the value for the specified BitField, unshifted.
`getShortRawValue(short)`	Gets the value for the specified BitField, unshifted.
`getShortValue(short)`	Gets the value for the specified BitField, appropriately shifted right, as a short.
`getValue(int)`	Gets the value for the specified BitField, appropriately shifted right.
`getValue(long)`	Gets the value for the specified BitField, appropriately shifted right.
`isAllSet(int)`	Tests whether all of the bits are set or not.
`isAllSet(long)`	Tests whether all of the bits are set or not.
`isSet(int)`	Tests whether the field is set or not.
`isSet(long)`	Tests whether the field is set or not.
`set(int)`	Sets the bits.
`set(long)`	Sets the bits.
`setBoolean(int, boolean)`	Sets a boolean BitField.
`setBoolean(long, boolean)`	Sets a boolean BitField.
`setByte(byte)`	Sets the bits.
`setByteBoolean(byte, boolean)`	Sets a boolean BitField.
`setShort(short)`	Sets the bits.
`setShortBoolean(short, boolean)`	Sets a boolean BitField.
`setShortValue(short, short)`	Sets the bits with new values.
`setValue(int, int)`	Sets the bits with new values.
`setValue(long, long)`	Sets the bits with new values.

public int clear(int holder)[source]¶

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).
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long clear(long holder)[source]¶

Clears the bits.

Parameters:: holder – The long data containing the bits we’re interested in.
Returns:: The value of holder with the specified bits cleared (set to 0).
Since:: 3.21.0

public byte clearByte(byte holder)[source]¶

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).
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public short clearShort(short holder)[source]¶

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).
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public int getRawValue(int holder)[source]¶

Gets the value for the specified BitField, unshifted.

Parameters:: holder – The int data containing the bits we’re interested in.
Returns:: The selected bits.
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long getRawValue(long holder)[source]¶

Gets the value for the specified BitField, unshifted.

Parameters:: holder – The long data containing the bits we’re interested in.
Returns:: The selected bits.
Since:: 3.21.0

public short getShortRawValue(short holder)[source]¶

Gets the value for the specified BitField, unshifted.

Parameters:: holder – The short data containing the bits we’re interested in.
Returns:: The selected bits.
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public short getShortValue(short holder)[source]¶

Gets 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)
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public int getValue(int holder)[source]¶

Gets 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)
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long getValue(long holder)[source]¶

Gets the value for the specified BitField, appropriately shifted right.

Many users of a BitField will want to treat the specified bits as an long 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 long data containing the bits we’re interested in.
Returns:: The selected bits, shifted right appropriately.
See also:: #setValue(long,long)
Since:: 3.21.0

public boolean isAllSet(int holder)[source]¶

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 – The int data containing the bits we’re interested in.
Returns:: true if all of the bits are set, else false.
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public boolean isAllSet(long holder)[source]¶

Tests whether all of the bits are set or not.

This is a stricter test than #isSet(long), in that all of the bits in a multi-bit set must be set for this method to return true.

Parameters:: holder – The long data containing the bits we’re interested in.
Returns:: true if all of the bits are set, else false.
Since:: 3.21.0

public boolean isSet(int holder)[source]¶

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 – The int data containing the bits we’re interested in
Returns:: true if any of the bits are set, else false
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public boolean isSet(long holder)[source]¶

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 – The long data containing the bits we’re interested in
Returns:: true if any of the bits are set, else false
Since:: 3.21.0

public int set(int holder)[source]¶

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.
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long set(long holder)[source]¶

Sets the bits.

Parameters:: holder – The long data containing the bits we’re interested in.
Returns:: The value of holder with the specified bits set to 1.
Since:: 3.21.0

public int setBoolean(int holder, boolean flag)[source]¶

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.

Throws:

java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long setBoolean(long holder, boolean flag)[source]¶

Sets a boolean BitField.

Parameters:

holder – The long 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.

Since:

3.21.0

public byte setByte(byte holder)[source]¶

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
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public byte setByteBoolean(byte holder, boolean flag)[source]¶

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.

Throws:

java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public short setShort(short holder)[source]¶

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.
Throws:: java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public short setShortBoolean(short holder, boolean flag)[source]¶

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.

Throws:

java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public short setShortValue(short holder, short value)[source]¶

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

Throws:

java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public int setValue(int holder, int value)[source]¶

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

Throws:

java.lang.IllegalStateException – Thrown if this field’s mask has bits set above bit 31 (only possible via #BitField(long)) and so cannot be represented in this holder type.

public long setValue(long holder, long value)[source]¶

Sets the bits with new values.

Parameters:

holder – The long 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(long)

Since:

3.21.0