com.bluegosling.collections.bits

Interface BitSequence

All Superinterfaces:

Iterable<Boolean>

public interface BitSequence
extends Iterable<Boolean>

A sequence of bits. This is very similar to a BitSet except it provides better API for navigating the bits like a stream (of arbitrarily sized chunks) and less API for general bit-fiddling. Unlike BitSet, a BitSequence is immutable.

Since the sequence is immutable, all attempts to remove elements using Iterators will result in an UnsupportedOperationException being thrown.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	BitSequence.BitOrder Indicates how bits are ordered when extracting bits into numeric types.

Method Summary

Modifier and Type	Method and Description
default BitStream	bitStream() Returns a stream, for consuming bits in arbitrary amounts with each fetch.
BitStream	bitStream(int startIndex) Returns a stream, for consuming bits in arbitrary amounts with each fetch.
default PrimitiveIterator.OfLong	bitTupleIterator(int tupleSize) Returns an iterator over arbitrarily-sized chunks in the sequence.
default PrimitiveIterator.OfLong	bitTupleIterator(int tupleSize, BitSequence.BitOrder order) Returns an iterator over arbitrarily-sized chunks in the sequence.
default PrimitiveIterator.OfLong	bitTupleIterator(int tupleSize, int startIndex) Returns an iterator over arbitrarily-sized chunks in the sequence.
PrimitiveIterator.OfLong	bitTupleIterator(int tupleSize, int startIndex, BitSequence.BitOrder order) Returns an iterator over arbitrarily-sized chunks in the sequence.
default LongStream	bitTupleStream(int tupleSize) Creates a LongStream over arbitrarily-sized chunks of bits.
default LongStream	bitTupleStream(int tupleSize, BitSequence.BitOrder bitOrder) Creates a LongStream over arbitrarily-sized chunks of bits.
boolean	equals(Object o) Returns true if the specified object is a BitSequence with the same contents and in the same order as this sequence.
int	hashCode() Returns a hash code for the sequence.
default BooleanIterator	iterator() Returns an iterator over the values in the sequence.
BooleanIterator	iterator(int startIndex) Returns an iterator over the values in the sequence starting at the specified index.
int	length() Gets the length of the sequence.
default BitSequence	subSequence(int start, int end) Returns a view of a portion of this sequence.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

length

int length()

Gets the length of the sequence.

Returns:

the number of bits in this sequence

iterator

default BooleanIterator iterator()

Returns an iterator over the values in the sequence. The return type is more constrained than Iterable.iterator() so that iteration can be done over un-boxed primitives.

Specified by:

iterator in interface Iterable<Boolean>

iterator

BooleanIterator iterator(int startIndex)

Returns an iterator over the values in the sequence starting at the specified index.

Parameters:

startIndex - the starting index (inclusive) for iteration

Returns:

an iterator

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the length of the sequence

bitTupleIterator

default PrimitiveIterator.OfLong bitTupleIterator(int tupleSize,
                                                  BitSequence.BitOrder order)

Returns an iterator over arbitrarily-sized chunks in the sequence. Numeric values are returned that represent the next n bits of the sequence where n is the "tuple size". If the sequence length isn't a multiple of the specified tuple size then the last value returned from the iterator may have 0 bits padded to it. For LSB order, the zero bits are on the more significant end of the value. But for MSB order, the zero bits are on the less significant end, which means the last value is effectively shifted left by the number of bits absent from the sequence.

Parameters:

tupleSize - the number of bits of each chunk

order - the order of bits in the returned value

Returns:

an iterator

Throws:

IllegalArgumentException - if the specified tuple size is less than one or greater than sixty-four.

See Also:

BitStream.next(int, BitSequence.BitOrder)

bitTupleIterator

default PrimitiveIterator.OfLong bitTupleIterator(int tupleSize)

Returns an iterator over arbitrarily-sized chunks in the sequence. This method is equivalent to the following:

bitSequence.bitTupleIterator(tupleSize, BitOrder.LSB);

Parameters:

tupleSize - the number of bits of each chunk

Returns:

an iterator

Throws:

IllegalArgumentException - if the specified tuple size is less than one or greater than sixty-four.

See Also:

bitTupleIterator(int, BitOrder)

bitTupleIterator

PrimitiveIterator.OfLong bitTupleIterator(int tupleSize,
                                          int startIndex,
                                          BitSequence.BitOrder order)

Returns an iterator over arbitrarily-sized chunks in the sequence. The fetching of values will start at the specified index (zero-based) instead of starting with the first bit.

Parameters:

tupleSize - the number of bits of each chunk

startIndex - an offset into the sequence from which the tuples will start

order - the order of bits in the returned value

Returns:

an iterator

Throws:

IllegalArgumentException - if the specified tuple size is less than one or greater than sixty-four.

See Also:

bitTupleIterator(int, BitOrder)

bitTupleIterator

default PrimitiveIterator.OfLong bitTupleIterator(int tupleSize,
                                                  int startIndex)

Returns an iterator over arbitrarily-sized chunks in the sequence. This method is equivalent to the following:

bitSequence.bitTupleIterator(tupleSize, startIndex, BitOrder.LSB);

Parameters:

tupleSize - the number of bits of each chunk

startIndex - an offset into the sequence from which the tuples will start

Returns:

an iterator

Throws:

IllegalArgumentException - if the specified tuple size is less than one or greater than sixty-four.

See Also:

bitTupleIterator(int, int, BitOrder)

subSequence

default BitSequence subSequence(int start,
                                int end)

Returns a view of a portion of this sequence.

Parameters:

start - the starting position of the portion of interest, inclusive

end - the end position of the portion of interest, exclusive

Returns:

a view of a portion of this sequence, as another BitSequence

bitStream

default BitStream bitStream()

Returns a stream, for consuming bits in arbitrary amounts with each fetch.

Returns:

a stream

bitStream

BitStream bitStream(int startIndex)

Returns a stream, for consuming bits in arbitrary amounts with each fetch. The stream will begin with the specified index (zero-based) instead of beginning with the first bit.

Parameters:

startIndex - an offset into the sequence from which the stream will start

Returns:

a stream

bitTupleStream

default LongStream bitTupleStream(int tupleSize)

Creates a LongStream over arbitrarily-sized chunks of bits. This is similar to bitTupleIterator(int) but allowing functional operations on the stream of values.

Parameters:

tupleSize - the number of bits of each chunk

Returns:

a stream of long values, each value being a chunk of bits

bitTupleStream

default LongStream bitTupleStream(int tupleSize,
                                  BitSequence.BitOrder bitOrder)

Creates a LongStream over arbitrarily-sized chunks of bits. This is similar to bitTupleIterator(int, BitOrder) but allowing functional operations on the stream of values.

Parameters:

tupleSize - the number of bits of each chunk

bitOrder - the order of bits in the returned value

Returns:

a stream of long values, each value being a chunk of bits

See Also:

bitTupleIterator(int, BitOrder)

hashCode

int hashCode()

Returns a hash code for the sequence. So different implementations can be compared and stored together in a set, the hash code should conform to the following scheme:

 hash code = length of the sequence XOR hash code of corresponding list of longs
 

The corresponding list of longs means a List of Longs whose length is exactly enough to contain all of the bits in the sequence, whose first element represents the first 64 bits of the sequence (least significant bit first), and whose last element represents the last 1 to 64 bits (least significant bit first) with any superfluous (most significant) bits zeroed out when the sequence length is not a multiple of 64.

The second term in the hash code happens to be the same as calculated by Arrays.hashCode(long[]) with an array whose contents correspond to the bits in the sequence (in the same manner described above).

Overrides:

hashCode in class Object

Returns:

a hash code for the sequence, calculated as described above

equals

boolean equals(Object o)

Returns true if the specified object is a BitSequence with the same contents and in the same order as this sequence.

Overrides:

equals in class Object

Parameters:

o - an object

Returns:

true if the object represents the same sequence of bits; false otherwise