BitField

public class 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

Since:

2.0

Constructors

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

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.

public BitField(long mask)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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