Class BitVector

  • All Implemented Interfaces:
    java.lang.Comparable<BitVector>

    public abstract class BitVector
    extends java.lang.Object
    implements java.lang.Comparable<BitVector>
    The BitVector 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.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • 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
    • Constructor Detail

      • BitVector

        public BitVector()
    • 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 to 1 or false 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 to 1 or false to set it to 0.
        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 or false 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 or false 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 class java.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 class java.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 interface java.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 the other parameter is null; if the size of the other 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 - if amount 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 is 0 or if any of them is null.
      • 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 the text parameter is null; if the bitSize 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 the bitSize 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 the data parameter is null; if the bitSize parameter is zero or negative; if bitSize does not match to the number ob bytes in the data 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 the bitSize 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 the toByteArray 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 the value parameter is null; if the bitSize 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 class java.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.