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.
      • 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
      • 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