Class BitVector
- java.lang.Object
-
- ru.ispras.fortress.data.types.bitvector.BitVector
-
- All Implemented Interfaces:
java.lang.Comparable<BitVector>
public abstract class BitVector extends java.lang.Object implements java.lang.Comparable<BitVector>
TheBitVector
class provides an interface for working with bit vectors ("raw" binary data) of arbitrary size. It provides basic methods for accessing and modifying stored bytes.
-
-
Field Summary
Fields Modifier and Type Field Description static int
BITS_IN_BYTE
Number of bits an a byte.static BitVector
FALSE
A constant bit vector that represents the 'false' boolean value (bit size is 1).static BitVector
TRUE
A constant bit vector that represents the 'true' boolean value (bit size is 1).
-
Constructor Summary
Constructors Constructor Description BitVector()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
assign(BitVector src)
Copies data from the specified bit vector to the current bit vector.java.math.BigInteger
bigIntegerValue()
Converts the stored data to a BigInteger value.java.math.BigInteger
bigIntegerValue(boolean signed)
Converts the stored data to a BigInteger value.int
compareTo(BitVector other)
Compares the current bit vector with the specified bit vector.BitVector
copy()
Creates a copy of current bit vector.static BitVector
copyOf(BitVector src)
Creates a copy of the specified bit vector.boolean
equals(java.lang.Object obj)
Checks the equality of bit vectors.BitVector
extend(int amount, boolean signExt)
Returns a copy of the bit vector extended by the specified amount.BitVector
field(int startBitPos, int endBitPos)
Returns a field of the bit vector limited by the specified bounds.BitVector
field(BitVector startBitPos, BitVector endBitPos)
Returns a field of the bit vector limited by the specified bounds.boolean
getBit(int index)
Returns a boolean flag that corresponds to the value of the specified bit.abstract int
getBitSize()
Returns the size of stored data in bits.abstract byte
getByte(int index)
Returns the binary value stored in the specified byte.byte
getByteBitMask(int index)
Returns the mask for the specified byte in the byte array.abstract int
getByteSize()
Returns the size of stored data in bytes (full number including incomplete bytes).int
hashCode()
Returns the hash code value for this bit vector.int
intValue()
Converts the stored data to an integer value.boolean
isAllReset()
Checks whether all bits in the bit vector are reset (equal to 0).boolean
isAllSet()
Checks whether all bits in the bit vector are set (equal to 1).long
longValue()
Converts the stored data to an long value.static BitVector
newEmpty(int bitSize)
Creates an uninitialized bit vector of the specified size.static BitVector
newMapping(BitVector... sources)
Creates a mapping that concatenates several bit vector to allow working with them as if they were a single bit vector.static BitVector
newMapping(BitVector source, int startBitPos, int bitSize)
Creates a bit vector mapping for the current bit vector.BitVector
repeat(int count)
Creates a copy of the current bit vector repeated the specified number of times.void
reset()
Resets (set to zero) all bits in the bit vector.BitVector
resize(int newBitSize, boolean signExt)
Returns a resized copy of the current bit vector.void
setAll()
Sets (sets to one) all bits in the bit vector.void
setBit(int index, boolean value)
Sets or resets the specified bit.abstract void
setByte(int index, byte value)
Sets the value of the specified byte in the data array.java.lang.String
toBinString()
Converts the stored binary data to textual representation.byte[]
toByteArray()
Returns a copy of stored data packed into an array of bytes.java.lang.String
toHexString()
Converts the stored binary data to a hexadecimal string.java.lang.String
toHexString(boolean trailingZeros)
Converts the stored binary data to a hexadecimal string.java.lang.String
toString()
Converts the stored data to a string (binary format).static BitVector
unmodifiable(BitVector source)
Returns an unmodifiable view of the specified bit vector.static BitVector
valueOf(boolean booleanValue)
Returns a bit vector that corresponds to the specified boolean value.static BitVector
valueOf(byte[] data, int bitSize)
Creates a bit vector from a byte array.static BitVector
valueOf(int value, int bitSize)
Creates a bit vector based on a integer value.static BitVector
valueOf(long value, int bitSize)
Creates a bit vector based on a long value.static BitVector
valueOf(java.lang.String bs)
Creates a bit vector based on textual representation of binary data.static BitVector
valueOf(java.lang.String text, int radix, int bitSize)
Creates a bit vector based on textual representation of binary data.static BitVector
valueOf(java.math.BigInteger value, int bitSize)
Creates a bit vector based on a BigInteger value.
-
-
-
Field Detail
-
FALSE
public static final BitVector FALSE
A constant bit vector that represents the 'false' boolean value (bit size is 1).
-
TRUE
public static final BitVector TRUE
A constant bit vector that represents the 'true' boolean value (bit size is 1).
-
BITS_IN_BYTE
public static final int BITS_IN_BYTE
Number of bits an a byte.- See Also:
- Constant Field Values
-
-
Method Detail
-
getBitSize
public abstract int getBitSize()
Returns the size of stored data in bits.- Returns:
- Number of bits.
-
getByteSize
public abstract int getByteSize()
Returns the size of stored data in bytes (full number including incomplete bytes).- Returns:
- Number of bytes (including incomplete bytes).
-
getByte
public abstract byte getByte(int index)
Returns the binary value stored in the specified byte. For incomplete bytes, the return value contains only the bits inside the bounds limited by the bit size.- Parameters:
index
- Index of the target byte.- Returns:
- Binary value stored in the specified byte.
-
setByte
public abstract void setByte(int index, byte value)
Sets the value of the specified byte in the data array. For incomplete bytes, bits that fall beyond the bounds limited by the bit size are ignored. In other words, bits in the target byte that lie beyond the bound retain their values. This requirement is crucial to guarantee correct work of mappings.- Parameters:
index
- Index of the target byte.value
- Binary value to be stored in the specified byte.
-
getBit
public final boolean getBit(int index)
Returns a boolean flag that corresponds to the value of the specified bit.- Parameters:
index
- Bit index.- Returns:
true
if the bit is set to1
orfalse
otherwise.- Throws:
java.lang.IndexOutOfBoundsException
- if the index is out of range.
-
setBit
public final void setBit(int index, boolean value)
Sets or resets the specified bit.- Parameters:
index
- Bit index.value
-true
to set the bit to1
orfalse
to set it to0
.- Throws:
java.lang.IndexOutOfBoundsException
- if the index is out of range.
-
setAll
public final void setAll()
Sets (sets to one) all bits in the bit vector.
-
reset
public final void reset()
Resets (set to zero) all bits in the bit vector.
-
isAllSet
public final boolean isAllSet()
Checks whether all bits in the bit vector are set (equal to 1).- Returns:
true
if all bits are set orfalse
otherwise.
-
isAllReset
public final boolean isAllReset()
Checks whether all bits in the bit vector are reset (equal to 0).- Returns:
true
if all bits are reset orfalse
otherwise.
-
assign
public final void assign(BitVector src)
Copies data from the specified bit vector to the current bit vector. If the bit vector is shorter than the current one, the rest high bytes are filled with zeros. If the source bit vector is longer, the result is truncated (the higher part is skipped).- Parameters:
src
- Source it vector.
-
equals
public final boolean equals(java.lang.Object obj)
Checks the equality of bit vectors. Bit vectors are considered equal if their sizes match and they hold equal data (comparison is performed byte by byte from the high end to the low end).- Overrides:
equals
in classjava.lang.Object
- Parameters:
obj
- A bit vector to be compared with the current bit vector.
-
hashCode
public final int hashCode()
Returns the hash code value for this bit vector. The hash code is calculated based on the stored data bytes.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- The hash code value for bit vector.
-
compareTo
public final int compareTo(BitVector other)
Compares the current bit vector with the specified bit vector. Data is compared starting with the highest byte in the array.- Specified by:
compareTo
in interfacejava.lang.Comparable<BitVector>
- Parameters:
other
- A raw data object.- Returns:
- 0 if data in both object equals, -1 if the data in the current object is less and 1 of it is greater.
- Throws:
java.lang.IllegalArgumentException
- if theother
parameter isnull
; if the size of theother
bit vector is different from the size of the current bit vector.
-
copy
public final BitVector copy()
Creates a copy of current bit vector. Creates a new bit vector of the same size and fills it with data from the current bit vector.- Returns:
- A copy of the current bit vector.
-
repeat
public final BitVector repeat(int count)
Creates a copy of the current bit vector repeated the specified number of times. The size of the resulting bit vector is the size of the current multiplied by the repetition count.- Parameters:
count
- Number of times the bit vector will be repeated.- Returns:
- A copy of the current bit vector repeated the specified number of times.
- Throws:
java.lang.IllegalArgumentException
- if the new size is<= 0
.
-
field
public final BitVector field(BitVector startBitPos, BitVector endBitPos)
Returns a field of the bit vector limited by the specified bounds.- Parameters:
startBitPos
- Bit vector that holds start position in bits.endBitPos
- Bit vector that holds end position in bits.- Returns:
- A field of the bit vector.
-
field
public final BitVector field(int startBitPos, int endBitPos)
Returns a field of the bit vector limited by the specified bounds.- Parameters:
startBitPos
- Start position in bits.endBitPos
- End position in bits.- Returns:
- A field of the bit vector.
-
resize
public BitVector resize(int newBitSize, boolean signExt)
Returns a resized copy of the current bit vector.- Parameters:
newBitSize
- New size in bits.signExt
- Flag that specifies whether sign extension is required.- Returns:
- Resized copy of the bit vector.
- Throws:
java.lang.IllegalArgumentException
- if the new size is<= 0
.
-
extend
public BitVector extend(int amount, boolean signExt)
Returns a copy of the bit vector extended by the specified amount.- Parameters:
amount
- Amount in bits.signExt
- Flag that specifies whether sign extension is required.- Returns:
- Extended copy of the bit vector.
- Throws:
java.lang.IllegalArgumentException
- ifamount
is<= 0
.
-
copyOf
public static BitVector copyOf(BitVector src)
Creates a copy of the specified bit vector. Creates a new bit vector of the same size and fills it with data from the current bit vector.- Parameters:
src
- Source bit vector.- Returns:
- A copy of the specified bit vector.
-
newEmpty
public static BitVector newEmpty(int bitSize)
Creates an uninitialized bit vector of the specified size.- Parameters:
bitSize
- Size of the created bit vector in bits.- Returns:
- A new bit vector.
-
newMapping
public static BitVector newMapping(BitVector source, int startBitPos, int bitSize)
Creates a bit vector mapping for the current bit vector. The mapping provides access to a part of the bit vector as if it was a separate bit vector.- Parameters:
source
- Source bit vector.startBitPos
- The starting position of the mapping.bitSize
- The size of the mapping in bytes.- Returns:
- A bit vector mapping.
-
newMapping
public static BitVector newMapping(BitVector... sources)
Creates a mapping that concatenates several bit vector to allow working with them as if they were a single bit vector.NOTE: The order of the bit vectors passed to the method must be from high to low. In other words, when the order of arguments is like this:
HIGH, ..., LOW [0] [N-1]
the concatenation result is like this:|HIGH|...|LOW| M 0
N
is the number of bit vectors to be concatenated;M
is the total bit size of the concatenation result.- Parameters:
sources
- Source bit vectors.- Returns:
- A bit vector mapping.
- Throws:
java.lang.IllegalArgumentException
- if the number of arguments is0
or if any of them isnull
.
-
unmodifiable
public static BitVector unmodifiable(BitVector source)
Returns an unmodifiable view of the specified bit vector. An attempt to modify the bit vector will result in the UnsupportedOperationException exception.- Parameters:
source
- Source bit vector.- Returns:
- Unmodifiable bit vector.
-
valueOf
public static BitVector valueOf(java.lang.String bs)
Creates a bit vector based on textual representation of binary data. The data size (number of bits) matches the string length.- Parameters:
bs
- Textual representation of binary data.- Returns:
- New bit vector.
-
valueOf
public static BitVector valueOf(boolean booleanValue)
Returns a bit vector that corresponds to the specified boolean value. IMPORTANT: The returned bit vector is an unmodifiable singleton object. The method is implemented this way to avoid unnecessary memory allocations because bit vectors representing boolean values are not normally modified.- Parameters:
booleanValue
- Boolean value.- Returns:
- A constant (!) bit vector for the specified boolean value.
-
valueOf
public static BitVector valueOf(java.lang.String text, int radix, int bitSize)
Creates a bit vector based on textual representation of binary data. The data size is specified by a method parameter. If the length of the string exceeds the specified size, data is truncated (characters signifying higher bits are ignored). If the string length is less than the data size, the higher bits of the data are filled with zeros.- Parameters:
text
- Textual representation of binary data.radix
- Radix to be used during conversion.bitSize
- Size of the resulting bit vector in bits.- Returns:
- New bit vector.
- Throws:
java.lang.IllegalArgumentException
- if thetext
parameter isnull
; if thebitSize
parameter is zero or negative.
-
valueOf
public static BitVector valueOf(long value, int bitSize)
Creates a bit vector based on a long value. The data size is specified by a method parameter. If the bit vector size is less that the long value size (64 bits), the value is truncated (high bits of the value are ignored). If the bit vector size exceeds the long value size, high bits of the bit vector are filled with zeros.- Parameters:
value
- Long value to be converted to a bit vector.bitSize
- Size of the resulting data array (in bits).- Returns:
- New bit vector.
- Throws:
java.lang.IllegalArgumentException
- if thebitSize
parameter is zero or negative.
-
valueOf
public static BitVector valueOf(byte[] data, int bitSize)
Creates a bit vector from a byte array.- Parameters:
data
- An array of bytes.bitSize
- Size of the resulting bit vector in bits.- Returns:
- New bit vector.
- Throws:
java.lang.IllegalArgumentException
- if thedata
parameter isnull
; if thebitSize
parameter is zero or negative; ifbitSize
does not match to the number ob bytes in thedata
array.
-
valueOf
public static BitVector valueOf(int value, int bitSize)
Creates a bit vector based on a integer value. The data size is specified by a method parameter. If the bit vector is less that the integer value size (32 bits), the value is truncated (high bits of the value are ignored). If the bit vector size exceeds the integer value size, high bits of the raw data store are filled with zeros.- Parameters:
value
- Integer value to be converted to a bit array.bitSize
- Size of the resulting data array (in bits).- Returns:
- New bit vector.
- Throws:
java.lang.IllegalArgumentException
- if thebitSize
parameter is zero or negative.
-
valueOf
public static BitVector valueOf(java.math.BigInteger value, int bitSize)
Creates a bit vector based on a BigInteger value. The data size is specified by a method parameter. If the bit vector is less than the size of the data stored in BigInteger ( returned by thetoByteArray
method), the data is truncated (high bits are ignored). If the bit vector size exceeds the data size, the data is sign extended (high bits are filled with zeros for a non-negative value or with ones for a negative value).- Parameters:
value
- BigInteger value to be converted to a bit vector.bitSize
- Size of the resulting bit vector (in bits).- Returns:
- New bit vector.
- Throws:
java.lang.IllegalArgumentException
- if thevalue
parameter isnull
; if thebitSize
parameter is zero or negative.
-
intValue
public final int intValue()
Converts the stored data to an integer value. If the bit vector size exceeds integer size (32 bits), the data is truncated to 32 bits (high bits are cut off). If the bit vector size is smaller than integer size (32 bits), the high bits of the integer are set to 0 (no sign extension happens).- Returns:
- Integer representation of the stored value.
-
longValue
public final long longValue()
Converts the stored data to an long value. If the stored data size exceeds long size (64 bits), the data is truncated to 64 bits (high bits are cut off).- Returns:
- Long representation of the stored value.
-
bigIntegerValue
public final java.math.BigInteger bigIntegerValue()
Converts the stored data to a BigInteger value.- Returns:
- BigInteger representation of the stored value.
-
bigIntegerValue
public final java.math.BigInteger bigIntegerValue(boolean signed)
Converts the stored data to a BigInteger value.- Parameters:
signed
- boolean value indicating should the bit vector be treated as signed integer.- Returns:
- BigInteger representation of the stored value.
-
toBinString
public final java.lang.String toBinString()
Converts the stored binary data to textual representation.- Returns:
- Binary string.
-
toHexString
public final java.lang.String toHexString()
Converts the stored binary data to a hexadecimal string.- Returns:
- Hexadecimal string.
-
toHexString
public final java.lang.String toHexString(boolean trailingZeros)
Converts the stored binary data to a hexadecimal string.- Parameters:
trailingZeros
- Flag that specifies whether trailing zeros should be included.- Returns:
- Hexadecimal string.
-
toString
public final java.lang.String toString()
Converts the stored data to a string (binary format).- Overrides:
toString
in classjava.lang.Object
- Returns:
- Textual representation of the stored data (binary format).
-
toByteArray
public final byte[] toByteArray()
Returns a copy of stored data packed into an array of bytes.- Returns:
- Array of bytes.
-
getByteBitMask
public final byte getByteBitMask(int index)
Returns the mask for the specified byte in the byte array. The mask helps determine what bits in the specified byte contain meaningful information and which bits should be ignored.- Parameters:
index
- Index of the target byte.- Returns:
- Bit mask for the current byte.
-
-