Package org.cicirello.search.representations

Class BitVector.BitIterator

  • Enclosing class:
    BitVector
    public final class BitVector.BitIterator
extends Object

    The BitIterator class enables iterating over the bits of a BitVector. In particular, it enables iterating over fixed length blocks within the BitVector. BitIterators are created via the BitVector.bitIterator(int) method or the BitVector.bitIterator() method.

    An example usage of the BitIterator class is as follows. In this example, we are iterating over the bits of a random BitVector of 128 bits, 4 bits at a time, using the nextBitBlock() method.

    
 BitVector b = new BitVector(128, true);
 BitVector.BitIterator iter = b.bitIterator(4);
 while (iter.hasNext()) {
      int fourBits = iter.nextBitBlock();
      ....
 }

    The BitIterator class also includes a nextBit() method that gets the next single bit (returned as an int) regardless of the block length used when the BitIterator was initiated. This example shows how to iterate over individual bits.

    
 int k = ...; // doesn't matter what is passed as block length
 BitVector b = new BitVector(128, true);
 BitVector.BitIterator iter = b.bitIterator(k);
 while (iter.hasNext()) {
      int singleBit = iter.nextBit();
      ....
 }

    You can even use a combination of calls to the nextBitBlock() method and the nextBit() method. In this example, we alternate getting blocks of 4 bits with getting a single bit.

    
 BitVector b = new BitVector(128, true);
 BitVector.BitIterator iter = b.bitIterator(4);
 while (iter.hasNext()) {
      int fourBits = iter.nextBitBlock();
      ....
      if (iter.hasNext()) {
           int singleBit = iter.nextBit();
           ....
      }
 }

    There is also a nextBitBlock(int) method, which enables overriding the default block size for some calls. The class supports usages involving combinations of calls to nextBitBlock(), nextBitBlock(int), and nextBit(). This next example initiates a BitIterator with a default block size of 4, and then gets the default of 4 bits, followed by a block of 7 bits, followed by a single bit, and then the default of 4 bits again.

    
 BitVector b = new BitVector(128, true);
 BitVector.BitIterator iter = b.bitIterator(4);
 if (iter.hasNext()) {
      // the default block size was set to 4 above
      int fourBits = iter.nextBitBlock();
      ....
 }
 if (iter.hasNext()) {
      // override the default block size to get 7 bits
      int sevenBits = iter.nextBitBlock(7);
      ....
 }
 if (iter.hasNext()) {
      // get a single bit
      int singleBit = iter.nextBit();
      ....
 }
 if (iter.hasNext()) {
      // get the default block size again
      int fourBits = iter.nextBitBlock();
      ....
 }

    • Method Detail

      • hasNext

        public boolean hasNext()
        Verifies if there are more bits to get, and it is safe to call nextBitBlock().
        Returns:
        true if there are more bits, and false otherwise. If this method returns false, then calls to nextBitBlock() will throw an exception.

      • numRemainingBits

        public int numRemainingBits()
        Gets the number of bits remaining in the iterator.
        Returns:
        the number of bits not yet iterated over.

      • nextBitBlock

        public int nextBitBlock()
        Gets the next block of bits from the BitVector.
        Returns:
        the next block of bits, which will be in the least significant places of the returned int value.
        Throws:
        IllegalStateException - if there are no more blocks to get

      • nextBitBlock

        public int nextBitBlock​(int k)
        Gets the next block of bits from the BitVector.
        Parameters:
        k - The block size, which overrides the default block size that was used when the BitIterator was initiated for this call only. For example, if k is 3, then this call will return an int containing the next 3 bits from the BitVector in the least significant 3 places. The value of k must be 0 < k ≤ 32.
        Returns:
        the next block of bits, which will be in the least significant places of the returned int value.
        Throws:
        IllegalArgumentException - if k ≤ 0 or if k > 32
        IllegalStateException - if there are no more blocks to get

      • nextLargeBitBlock

        public int[] nextLargeBitBlock​(int k)
        Gets the next block of bits from the BitVector.
        Parameters:
        k - The block size, which overrides the default block size that was used when the BitIterator was initiated for this call only. Unlike the nextBitBlock() methods, this method is not limited in block size, other than by the number of remaining bits.
        Returns:
        the next block of bits, as an array of ints, with the first 32 bits of the block filled from least significant to most significant bit of a[0], where a is the array that is returned, and the next 32 bits filled similarly into a[1], etc.
        Throws:
        IllegalArgumentException - if there are fewer than k bits remaining.

      • skip

        public void skip​(int k)
        Skips this BitIterator past a segment of bits.
        Parameters:
        k - The number of bits to skip.
        Throws:
        IllegalArgumentException - if there are fewer than k bits remaining.

      • nextBit

        public int nextBit()
        Gets the next bit from the BitVector. Unlike the nextBitBlock() method, this method just gets 1 bit at a time, rather than a block of bits.
        Returns:
        the next bit, which will be in the least significant place of the returned int value.
        Throws:
        IllegalStateException - if there are no more bits to get