Module io.jenetics.base
Package io.jenetics.internal.collection

Class BitArray

java.lang.Object
BitArray
All Implemented Interfaces:
Copyable<BitArray>
public final class BitArray extends Object implements Copyable<BitArray>
This class represents a fixed sized array of bit or boolean values, backed by a byte[] array. The order of the bit values is shown if the drawing. 
 
  Byte:       3        2        1        0
              |        |        |        |
  Array: |11110011|10011101|01000000|00101010|
          |                 |        |      |
  Bit:    23                15       7      0
Since:
7.0
Version:
7.0

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    bitCount()
    Return the number of set bits of this bit-array.
    BitArray
    copy()
    Create a new copy of this bit-array.
    boolean
    equals(Object obj)
     
    boolean
    get(int index)
    Return the bit value at the given bit index.
    int
    hashCode()
     
    void
    invert()
    Inverts this bit-array.
    int
    length()
    Return the length of the bit-array.
    static BitArray
    of(byte[] data)
    Create a new bit-array with the given data values and length.
    static BitArray
    of(byte[] data, int length)
    Create a new bit-array with the given data values and length.
    static BitArray
    of(byte[] data, int begin, int end)
    Create a new bit-array with the given data values and begin and end bit indexes.
    static BitArray
    of(CharSequence value)
    Creates a new bit-array from the given string value.
    static BitArray
    of(CharSequence value, int length)
    Creates a new bit-array from the given string value.
    static BitArray
    of(BigInteger value)
    Create a new bit-array from the given BigInteger value.
    static BitArray
    of(BigInteger value, int length)
    Creates a new bit-array from the given value and the given length.
    static BitArray
    ofLength(int length)
    Crate a new bit-array with the given length.
    static BitArray
    ofLength(int length, double p)
    Create a new bit-array which can store at least the number of bits as defined by the given length parameter.
    void
    set(int index)
    Set the bit in the given byte array at the bit position (not the index within the byte array) to true.
    void
    set(int index, boolean value)
    Sets the specified bit value at the given bit index.
    void
    shiftLeft(int n)
    Shifting all bits in this bit array the given n bits to the left.
    void
    shiftRight(int n)
    Shifting all bits in this bit array the given n bits to the right.
    int
    signum()
    Return the signum of the number, represented by this bit-array (-1 for negative, 0 for zero, 1 for positive).
    BigInteger
    toBigInteger()
    Return the value of this bit-array as BigInteger value.
    byte[]
    toByteArray()
    Return the byte[] array, which represents the state of the state of this bit-array.
    String
    toByteString()
    Convert a binary representation of this bit-array to a string.
    String
    toString()
     
    void
    unset(int index)
    Set the bit in the given byte array at the bit position (not the index within the byte array) to false.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • length

      public int length()
      Return the length of the bit-array.
      Returns:
      the length of the bit array

    • bitCount

      public int bitCount()
      Return the number of set bits of this bit-array.
      Returns:
      the number of set bits

    • set

      public void set(int index, boolean value)
      Sets the specified bit value at the given bit index.
      Parameters:
      index - the bit index
      value - the bit value
      Throws:
      IndexOutOfBoundsException - if the index is not within the valid range of [0, length())

    • set

      public void set(int index)
      Set the bit in the given byte array at the bit position (not the index within the byte array) to true.
      Parameters:
      index - the bit index
      Throws:
      IndexOutOfBoundsException - if the index is not within the valid range of [0, length())

    • unset

      public void unset(int index)
      Set the bit in the given byte array at the bit position (not the index within the byte array) to false.
      Parameters:
      index - the bit index
      Throws:
      IndexOutOfBoundsException - if the index is not within the valid range of [0, length())

    • get

      public boolean get(int index)
      Return the bit value at the given bit index.
      Parameters:
      index - the bit index
      Returns:
      the bit value
      Throws:
      IndexOutOfBoundsException - if the index is not within the valid range of [0, length())

    • invert

      public void invert()
      Inverts this bit-array.

    • shiftLeft

      public void shiftLeft(int n)
      Shifting all bits in this bit array the given n bits to the left. The bits on the right side are filled with zeros.
      Parameters:
      n - the number of bits to shift.
      Since:
      7.1

    • shiftRight

      public void shiftRight(int n)
      Shifting all bits in this bit array the given n bits to the right. The bits on the right side are filled with zeros.
      Parameters:
      n - the number of bits to shift.
      Since:
      7.1

    • signum

      public int signum()
      Return the signum of the number, represented by this bit-array (-1 for negative, 0 for zero, 1 for positive). 
      final BitArray bits = ...;
final BigInteger i = bits.toBigInteger();
assert bits.signum() == i.signum();
      Returns:
      the signum of the number, represented by this bit-array (-1 for negative, 0 for zero, 1 for positive)

    • toBigInteger

      public BigInteger toBigInteger()
      Return the value of this bit-array as BigInteger value. This bit-array can be recreated by the returned BigInteger value. But only with the same length() of this bit-array. 
      final var bits = BitArray.of("1111111010100110010110110010011110110101");
final var bint = bits.toBigInteger();
assert BitArray.of(bint, bits.length()).equals(bits);
      Returns:
      a new BigInteger object, which represents the integer value of this bit-array
      See Also:

    • toByteArray

      public byte[] toByteArray()
      Return the byte[] array, which represents the state of the state of this bit-array. 
      final BitArray bits = ...;
final byte[] bytes = bits.toByteArray();
assert bits.equals(BitArray.of(bytes, bits.length()));
      Returns:
      the bit-array data as byte[] array

    • copy

      public BitArray copy()
      Create a new copy of this bit-array.
      Specified by:
      copy in interface Copyable<BitArray>
      Returns:
      a new copy of this bit-array

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toByteString

      public String toByteString()
      Convert a binary representation of this bit-array to a string. The string has the following format: 
        Byte:       3        2        1        0
              |        |        |        |
  Array: "11110011|10011101|01000000|00101010"
          |                 |        |      |
  Bit:    23                15       7      0
      Returns:
      the binary representation of this bit array.

    • of

      public static BitArray of(BigInteger value, int length)
      Creates a new bit-array from the given value and the given length. It is guaranteed that the created bit-array will represent the given BigInteger, as long as the length is big enough to store the whole value. If the length is shorter than required, the higher order bits will be truncated. 
      final var length = 2048;
final var bint = BigInteger.probablePrime(length, new Random());
final var bits = BitArray.of(bint, length + 1);
assert bits3.toBigInteger().equals(bint);
      Parameters:
      value - the integer value
      length - the length of the created bit-array
      Returns:
      a newly created bit-array which represent the given value
      Throws:
      NullPointerException - if the given value is null
      NegativeArraySizeException - if the length is negative
      See Also:

    • of

      public static BitArray of(BigInteger value)
      Create a new bit-array from the given BigInteger value.
      Parameters:
      value - the integer value
      Returns:
      a newly created bit-array which represent the given value
      Throws:
      NullPointerException - if the given value is null
      See Also:

    • of

      public static BitArray of(CharSequence value, int length)
      Creates a new bit-array from the given string value. The given length might be bigger and smaller than the length of the given value string. The higher order bits of the created bit-array are trimmed or filled with zero if the length is smaller or bigger than the given string.
      Parameters:
      value - the given input string, consisting only of '0's and '1's
      length - the length of the created bit-array
      Returns:
      a new bit-array from the given input value
      Throws:
      IllegalArgumentException - if the given input value is empty
      See Also:

    • of

      public static BitArray of(CharSequence value)
      Creates a new bit-array from the given string value. The string, created by the toString() method, will be equals to the given input value. 
      final var string = "11111110101001100101101100100111101101011101";
final var bits = BitArray.of(string);
assert bits.toString().equals(string);
      Parameters:
      value - the given input string, consisting only of '0's and '1's
      Returns:
      a new bit-array from the given input value
      Throws:
      IllegalArgumentException - if the given input value is empty
      See Also:

    • of

      public static BitArray of(byte[] data, int begin, int end)
      Create a new bit-array with the given data values and begin and end bit indexes. The given data is copied.
      Parameters:
      data - the byte[] array which contains the bit data
      begin - the start bit index (inclusively)
      end - the end bit index (exclusively)
      Returns:
      a newly created bit-array
      Throws:
      NullPointerException - if the given data array is null
      IllegalArgumentException - if the begin and end indexes are not within the valid range

    • of

      public static BitArray of(byte[] data, int length)
      Create a new bit-array with the given data values and length. The given data is copied.
      Parameters:
      data - the byte[] array which contains the bit data
      length - the bit length
      Returns:
      a newly created bit-array
      Throws:
      NullPointerException - if the given data array is null
      IllegalArgumentException - if the length is greater than data.length*Byte.SIZE

    • of

      public static BitArray of(byte[] data)
      Create a new bit-array with the given data values and length. The given data is copied.
      Parameters:
      data - the byte[] array which contains the bit data
      Returns:
      a newly created bit-array
      Throws:
      NullPointerException - if the given data array is null

    • ofLength

      public static BitArray ofLength(int length)
      Crate a new bit-array with the given length. All bits are set to '0'.
      Parameters:
      length - the length of the bit-array
      Returns:
      a newly created bit-array with the given length
      Throws:
      IllegalArgumentException - if the given length is smaller then one

    • ofLength

      public static BitArray ofLength(int length, double p)
      Create a new bit-array which can store at least the number of bits as defined by the given length parameter. The returned byte array is initialized with ones according to the given ones probability p.
      Parameters:
      length - the number of bits, the returned bit-array can store.
      p - the ones probability of the returned byte array.
      Returns:
      the new byte array.s
      Throws:
      IllegalArgumentException - if p is not a valid probability.