Module tech.bitey.bufferstuff
Package tech.bitey.bufferstuff

Class BufferBitSet

java.lang.Object
tech.bitey.bufferstuff.BufferBitSet
All Implemented Interfaces:
Cloneable
public class BufferBitSet extends Object implements Cloneable
Similar to BitSet, but backed by a ByteBuffer. Differences with BitSet include:

BufferBitSet

  • ... is not Serializable.
  • ... does not hide the backing buffer, and offers copy-free methods for wrapping an existing buffer.
  • ... allows for specifying whether or not the buffer can be resized (replaced with a larger buffer)
This bitset implementation is not thread safe, and concurrent writes or external modifications to the backing buffer could put it into a bad state.

The resizable flag controls whether or not the bitset can grow to accommodate setting bits beyond the current buffer's limit (by replacing the current buffer with a larger one).

All ByteBuffers allocated by this class are procured via BufferUtils.allocate(int). The allocated buffers will be direct if the tech.bitey.allocateDirect system property is set to "true".

Author:
biteytech@protonmail.com, adapted from BitSet
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final BufferBitSet
    EMPTY_BITSET
    An empty, non-resizable BufferBitSet

  • Constructor Summary

    Constructors
    Constructor
    Description
    BufferBitSet()
    Creates an empty, resizable BufferBitSet
    BufferBitSet(boolean resizable)
    Creates an empty BufferBitSet with the specified resize behavior.
    BufferBitSet(ByteBuffer buffer)
    Creates a BufferBitSet which wraps the provided buffer.
    BufferBitSet(ByteBuffer buffer, boolean resizable)
    Creates a BufferBitSet which wraps the provided buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    and(BufferBitSet set)
    Performs a logical AND of this target bitset with the argument bitset.
    void
    andNot(BufferBitSet set)
    Clears all of the bits in this bitset whose corresponding bit is set in the specified bitset.
    int
    cardinality()
    Returns the number of bits set to true in this BufferBitSet.
    int
    cardinality(int fromIndex, int toIndex)
    Returns the number of bits set to true within the given range.
    void
    clear(int bitIndex)
    Sets the bit specified by the index to false.
    void
    clear(int fromIndex, int toIndex)
    Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to false.
    Object
    clone()
    Cloning this bitset produces a new bitset that is equal to it.
    BufferBitSet
    copy()
    Identical to clone(), except returns a BufferBitSet instead of Object.
    boolean
    equals(Object obj)
    Compares this object against the specified object.
    void
    flip(int bitIndex)
    Sets the bit at the specified index to the complement of its current value.
    void
    flip(int fromIndex, int toIndex)
    Sets each bit from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to the complement of its current value.
    boolean
    get(int bitIndex)
    Returns the value of the bit with the specified index.
    BufferBitSet
    get(int fromIndex, int toIndex)
    Returns a new BufferBitSet composed of bits from this bitset from fromIndex (inclusive) to toIndex (exclusive).
    ByteBuffer
    getBuffer()
    Returns the ByteBuffer backing this BufferBitSet.
    int
    hashCode()
    Returns the hashcode value for this bitset.
    boolean
    isEmpty()
    Returns true if this BufferBitSet contains no bits that are set to true.
    boolean
    isResizable()
    Returns true if this bitset's buffer can be resized (replaced with a larger buffer).
    int
    lastSetBit()
    Returns the index of the highest set bit in the bitset, or -1 if the bitset contains no set bits.
    static BufferBitSet
    mapFrom(FileChannel channel)
    Memory-maps a bitset from the specified FileChannel.
    int
    nextClearBit(int fromIndex)
    Returns the index of the first bit that is set to false that occurs on or after the specified starting index.
    int
    nextSetBit(int fromIndex)
    Returns the index of the first bit that is set to true that occurs on or after the specified starting index.
    void
    or(BufferBitSet set)
    Performs a logical OR of this bitset with the bitset argument.
    int
    previousClearBit(int fromIndex)
    Returns the index of the nearest bit that is set to false that occurs on or before the specified starting index.
    int
    previousSetBit(int fromIndex)
    Returns the index of the nearest bit that is set to true that occurs on or before the specified starting index.
    static BufferBitSet
    random(int n, int size)
    Returns a new BufferBitSet with n bits set randomly in the range zero to size (exclusive).
    static BufferBitSet
    random(int n, int size, Random random)
    Returns a new BufferBitSet with n bits set randomly in the range zero to size (exclusive).
    static BufferBitSet
    readFrom(ReadableByteChannel channel)
    Read a bitset from the specified ReadableByteChannel.
    BufferBitSet
    resizable(boolean resizable)
    Returns a new BufferBitSet with the specified resizability.
    void
    set(int bitIndex)
    Sets the bit at the specified index to true.
    void
    set(int bitIndex, boolean value)
    Sets the bit at the specified index to the specified value.
    void
    set(int fromIndex, int toIndex)
    Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to true.
    void
    set(int fromIndex, int toIndex, boolean value)
    Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to the specified value.
    BufferBitSet
    shiftRight(int offset)
    Returns a copy of this bitset with each bit shifted right by offset.
    int
    size()
    Returns the number of bits of space actually in use by this BufferBitSet to represent bit values.
    BitSet
    toBitSet()
    Returns a new BitSet containing all of the bits in this BufferBitSet.
    byte[]
    toByteArray()
    Returns a new byte array containing all the bits in this bit set.
    String
    toString()
    Returns a string representation of this BufferBitSet equivalent to the representation of a SortedSet containing the indices of the bits which are set in this bitset.
    static BufferBitSet
    valueOf(byte[] bytes)
    Returns a new resizable bitset containing all of the bits in the given byte array.
    static BufferBitSet
    valueOf(BitSet bs)
    Returns a new resizable BufferBitSet containing all of the bits in the given BitSet.
    void
    writeTo(WritableByteChannel channel)
    Write this bitset to the specified WritableByteChannel.
    void
    writeTo(WritableByteChannel channel, int fromIndex, int toIndex)
    Write a range from this bitset to the specified WritableByteChannel.
    void
    xor(BufferBitSet set)
    Performs a logical XOR of this bitset with the bitset argument.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • BufferBitSet

      public BufferBitSet()
      Creates an empty, resizable BufferBitSet

    • BufferBitSet

      public BufferBitSet(boolean resizable)
      Creates an empty BufferBitSet with the specified resize behavior.
      Parameters:
      resizable - - specifies whether or not the buffer can be resized (replaced with a larger buffer)

    • BufferBitSet

      public BufferBitSet(ByteBuffer buffer)
      Creates a BufferBitSet which wraps the provided buffer. This bitset will only make use of the space demarked by Buffer.position() and Buffer.limit(). The provided buffer object will not itself be modified, though the buffer's content can be via writes to this bitset.

      The resulting bitset is not resizable.

      Parameters:
      buffer - - the ByteBuffer to be wrapped by this bitset. Writes to this bitset will modify the buffer's content.
      Throws:
      NullPointerException - if the provided buffer is null

    • BufferBitSet

      public BufferBitSet(ByteBuffer buffer, boolean resizable)
      Creates a BufferBitSet which wraps the provided buffer. This bitset will only make use of the space demarked by Buffer.position() and Buffer.limit(). The provided buffer object will not itself be modified, though the buffer's content can be via writes to this bitset.
      Parameters:
      buffer - - the ByteBuffer to be wrapped by this bitset. Writes to this bitset will modify the buffer's content.
      resizable - - specifies whether or not the buffer can be resized (replaced with a larger buffer)

  • Method Details

    • getBuffer

      public ByteBuffer getBuffer()
      Returns the ByteBuffer backing this BufferBitSet.
      Returns:
      the ByteBuffer backing this BufferBitSet.

    • isResizable

      public boolean isResizable()
      Returns true if this bitset's buffer can be resized (replaced with a larger buffer).
      Returns:
      true if this bitset's buffer can be resized.

    • valueOf

      public static BufferBitSet valueOf(byte[] bytes)
      Returns a new resizable bitset containing all of the bits in the given byte array.

      More precisely,
      BufferBitSet.valueOf(bytes).get(n) == ((bytes[n/8] & (1<<(n%8))) != 0)
      for all n < 8 * bytes.length.

      The provided array is wrapped, it is not copied. Writes to this bitset can modify the array.

      Parameters:
      bytes - - a byte array containing a sequence of bits to be used as the initial bits of the new bit set
      Returns:
      a new resizable bitset containing all of the bits in the given byte array.

    • valueOf

      public static BufferBitSet valueOf(BitSet bs)
      Returns a new resizable BufferBitSet containing all of the bits in the given BitSet.
      Parameters:
      bs - - the bitset to copy
      Returns:
      a new resizable BufferBitSet containing all of the bits in the given java.util.BitSet.

    • resizable

      public BufferBitSet resizable(boolean resizable)
      Returns a new BufferBitSet with the specified resizability. The buffer object itself will be duplicated, but will share the underlying space.
      Parameters:
      resizable - - specifies whether or not the buffer can be resized (replaced with a larger buffer)
      Returns:
      a new bitset with the specified resize behavior

    • random

      public static BufferBitSet random(int n, int size)
      Returns a new BufferBitSet with n bits set randomly in the range zero to size (exclusive).
      Parameters:
      n - - the number of bits to set
      size - - bits are set within the range zero to size (exclusive)
      Returns:
      a new bitset with n bits set randomly in the range zero to size (exclusive)
      Throws:
      IllegalArgumentException - if size < 0
      IllegalArgumentException - if n < 0 || n > size

    • random

      public static BufferBitSet random(int n, int size, Random random)
      Returns a new BufferBitSet with n bits set randomly in the range zero to size (exclusive).
      Parameters:
      n - - the number of bits to set
      size - - bits are set within the range zero to size (exclusive)
      random - - the random number generator
      Returns:
      a new bitset with n bits set randomly in the range zero to size (exclusive)
      Throws:
      IllegalArgumentException - if size < 0
      IllegalArgumentException - if n < 0 || n > size

    • toByteArray

      public byte[] toByteArray()
      Returns a new byte array containing all the bits in this bit set.
      Returns:
      a new byte array containing all the bits in this bit set.

    • toBitSet

      public BitSet toBitSet()
      Returns a new BitSet containing all of the bits in this BufferBitSet.
      Returns:
      a new BitSet containing all of the bits in this BufferBitSet.

    • writeTo

      public void writeTo(WritableByteChannel channel) throws IOException
      Write this bitset to the specified WritableByteChannel. Equivalent to writeTo(channel, 0, length())
      Parameters:
      channel - - the channel to write to
      Throws:
      IOException - if some I/O error occurs

    • writeTo

      public void writeTo(WritableByteChannel channel, int fromIndex, int toIndex) throws IOException
      Write a range from this bitset to the specified WritableByteChannel. This method will write a 5-byte header followed by the bytes which store the bits in the specified range.
      Parameters:
      channel - - the channel to write to
      fromIndex - - index of the first bit to write
      toIndex - - index after the last bit to write
      Throws:
      IOException - if some I/O error occurs
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • readFrom

      public static BufferBitSet readFrom(ReadableByteChannel channel) throws IOException
      Read a bitset from the specified ReadableByteChannel. The bitset must have previously been written with one of the writeTo methods.
      Parameters:
      channel - - the channel to read from
      Returns:
      a non-resizable bitset copied from the specified channel
      Throws:
      IOException - if some I/O error occurs

    • mapFrom

      public static BufferBitSet mapFrom(FileChannel channel) throws IOException
      Memory-maps a bitset from the specified FileChannel. The bitset must have previously been written with one of the writeTo methods. The channel must be writable.

      Sets the channel's position to the byte immediately after the last byte associated with this bitset.

      Parameters:
      channel - - the channel to map from
      Returns:
      a non-resizable bitset memory-mapped from the specified file
      Throws:
      IOException - if some I/O error occurs

    • get

      public boolean get(int bitIndex)
      Returns the value of the bit with the specified index. The value is true if the bit with the index bitIndex is currently set in this bitset; otherwise, the result is false.
      Parameters:
      bitIndex - the bit index
      Returns:
      the value of the bit with the specified index
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • get

      public BufferBitSet get(int fromIndex, int toIndex)
      Returns a new BufferBitSet composed of bits from this bitset from fromIndex (inclusive) to toIndex (exclusive).

      The resulting bitset will always be stored in newly allocated space, and will have the same resizable settings as this bitset.

      Parameters:
      fromIndex - - index of the first bit to include
      toIndex - - index after the last bit to include
      Returns:
      a new bitset from a range of this bitset
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • set

      public void set(int bitIndex)
      Sets the bit at the specified index to true.
      Parameters:
      bitIndex - a bit index
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • set

      public void set(int bitIndex, boolean value)
      Sets the bit at the specified index to the specified value.
      Parameters:
      bitIndex - a bit index
      value - a boolean value to set
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • set

      public void set(int fromIndex, int toIndex)
      Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to true.
      Parameters:
      fromIndex - index of the first bit to be set
      toIndex - index after the last bit to be set
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • set

      public void set(int fromIndex, int toIndex, boolean value)
      Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to the specified value.
      Parameters:
      fromIndex - index of the first bit to be set
      toIndex - index after the last bit to be set
      value - value to set the selected bits to
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • flip

      public void flip(int bitIndex)
      Sets the bit at the specified index to the complement of its current value.
      Parameters:
      bitIndex - the index of the bit to flip
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • flip

      public void flip(int fromIndex, int toIndex)
      Sets each bit from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to the complement of its current value.
      Parameters:
      fromIndex - index of the first bit to flip
      toIndex - index after the last bit to flip
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • clear

      public void clear(int bitIndex)
      Sets the bit specified by the index to false.
      Parameters:
      bitIndex - the index of the bit to be cleared
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • clear

      public void clear(int fromIndex, int toIndex)
      Sets the bits from the specified fromIndex (inclusive) to the specified toIndex (exclusive) to false.
      Parameters:
      fromIndex - index of the first bit to be cleared
      toIndex - index after the last bit to be cleared
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • nextSetBit

      public int nextSetBit(int fromIndex)
      Returns the index of the first bit that is set to true that occurs on or after the specified starting index. If no such bit exists then -1 is returned.
      Parameters:
      fromIndex - the index to start checking from (inclusive)
      Returns:
      the index of the next set bit, or -1 if there is no such bit
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • nextClearBit

      public int nextClearBit(int fromIndex)
      Returns the index of the first bit that is set to false that occurs on or after the specified starting index.
      Parameters:
      fromIndex - the index to start checking from (inclusive)
      Returns:
      the index of the next clear bit
      Throws:
      IndexOutOfBoundsException - if the specified index is negative

    • previousSetBit

      public int previousSetBit(int fromIndex)
      Returns the index of the nearest bit that is set to true that occurs on or before the specified starting index. If no such bit exists, or if -1 is given as the starting index, then -1 is returned.
      Parameters:
      fromIndex - the index to start checking from (inclusive)
      Returns:
      the index of the previous set bit, or -1 if there is no such bit
      Throws:
      IndexOutOfBoundsException - if the specified index is less than -1

    • previousClearBit

      public int previousClearBit(int fromIndex)
      Returns the index of the nearest bit that is set to false that occurs on or before the specified starting index. If no such bit exists, or if -1 is given as the starting index, then -1 is returned.
      Parameters:
      fromIndex - the index to start checking from (inclusive)
      Returns:
      the index of the previous clear bit, or -1 if there is no such bit
      Throws:
      IndexOutOfBoundsException - if the specified index is less than -1

    • lastSetBit

      public int lastSetBit()
      Returns the index of the highest set bit in the bitset, or -1 if the bitset contains no set bits.
      Returns:
      the index of the highest set bit in the bitset, or -1 if the bitset contains no set bits.

    • and

      public void and(BufferBitSet set)
      Performs a logical AND of this target bitset with the argument bitset. This bitset is modified so that each bit in it has the value true if and only if it both initially had the value true and the corresponding bit in the bitset argument also had the value true.
      Parameters:
      set - - a BufferBitSet

    • or

      public void or(BufferBitSet set)
      Performs a logical OR of this bitset with the bitset argument. This bitset is modified so that a bit in it has the value true if and only if it either already had the value true or the corresponding bit in the bitset argument has the value true.
      Parameters:
      set - - a BufferBitSet

    • xor

      public void xor(BufferBitSet set)
      Performs a logical XOR of this bitset with the bitset argument. This bitset is modified so that a bit in it has the value true if and only if one of the following statements holds:
      • The bit initially has the value true, and the corresponding bit in the argument has the value false.
      • The bit initially has the value false, and the corresponding bit in the argument has the value true.
      Parameters:
      set - - a BufferBitSet

    • andNot

      public void andNot(BufferBitSet set)
      Clears all of the bits in this bitset whose corresponding bit is set in the specified bitset.
      Parameters:
      set - - the BufferBitSet with which to mask this bitset

    • shiftRight

      public BufferBitSet shiftRight(int offset)
      Returns a copy of this bitset with each bit shifted right by offset. The resulting bitset will always be stored in newly allocated space, and will have the same resizable setting as this bitset.
      Parameters:
      offset - - number of bits to shift by
      Returns:
      a new bitset with shifted right by offset
      Throws:
      IllegalArgumentException - if offset is negative
      IllegalStateException - if the shifted size exceeds the maximum addressable size (2^31-1)

    • toString

      public String toString()
      Returns a string representation of this BufferBitSet equivalent to the representation of a SortedSet containing the indices of the bits which are set in this bitset.
      Overrides:
      toString in class Object

    • size

      public int size()
      Returns the number of bits of space actually in use by this BufferBitSet to represent bit values. The maximum element that can be set without resizing is size()-1
      Returns:
      the number of bits of space currently in this bit set

    • isEmpty

      public boolean isEmpty()
      Returns true if this BufferBitSet contains no bits that are set to true.
      Returns:
      boolean indicating whether this bitset is empty

    • cardinality

      public int cardinality()
      Returns the number of bits set to true in this BufferBitSet.
      Returns:
      the number of bits set to true in this BufferBitSet

    • cardinality

      public int cardinality(int fromIndex, int toIndex)
      Returns the number of bits set to true within the given range.
      Parameters:
      fromIndex - - index of the first bit in the range
      toIndex - - index after the last bit in the range
      Returns:
      the number of bits set to true within the given range.
      Throws:
      IndexOutOfBoundsException - if fromIndex is negative, or toIndex is negative, or fromIndex is larger than toIndex

    • hashCode

      public int hashCode()
      Returns the hashcode value for this bitset. The hashcode depends only on which bits are set within this BufferBitSet.

      Hashcode is computed using formula from Arrays.hashCode(byte[])

      Overrides:
      hashCode in class Object
      Returns:
      the hashcode value for this bitset

    • equals

      public boolean equals(Object obj)
      Compares this object against the specified object. The result is true if and only if the argument is not null and is a BufferBitset object that has exactly the same set of bits set to true as this bit set. That is, for every nonnegative int index k, 
       ((BitBufferSet) obj).get(k) == this.get(k)
      must be true. The current sizes of the two bit sets are not compared.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with
      Returns:
      true if the objects are the same; false otherwise

    • clone

      public Object clone()
      Cloning this bitset produces a new bitset that is equal to it.
      Overrides:
      clone in class Object
      Returns:
      another bitset that has exactly the same bits set to true as this one

    • copy

      public BufferBitSet copy()
      Identical to clone(), except returns a BufferBitSet instead of Object.
      Returns:
      another bitset that has exactly the same bits set to true as this one