Package org.apache.commons.lang3.util

# Class FluentBitSet

java.lang.Object
org.apache.commons.lang3.util.FluentBitSet

All Implemented Interfaces:
  `Serializable`, `Cloneable`

public final class FluentBitSet extends Object implements Cloneable, Serializable
A fluent `BitSet` with additional operations.

Originally from Apache Commons VFS with more added to act as a fluent replacement for `BitSet`.

Since:
  3.13.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FluentBitSet()`
  Creates a new bit set.
  `FluentBitSet(int nbits)`
  Creates a bit set whose initial size is large enough to explicitly represent bits with indices in the range `0` through `nbits-1`.
  `FluentBitSet(BitSet set)`
  Creates a new instance for the given bit set.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FluentBitSet`
  `and(BitSet set)`
  Performs a logical AND of this target bit set with the argument bit set.
  `FluentBitSet`
  `and(FluentBitSet set)`
  Performs a logical AND of this target bit set with the argument bit set.
  `FluentBitSet`
  `andNot(BitSet set)`
  Clears all of the bits in this `BitSet` whose corresponding bit is set in the specified `BitSet`.
  `FluentBitSet`
  `andNot(FluentBitSet set)`
  Clears all of the bits in this `BitSet` whose corresponding bit is set in the specified `BitSet`.
  `BitSet`
  `bitSet()`
  Gets the wrapped bit set.
  `int`
  `cardinality()`
  Returns the number of bits set to `true` in this `BitSet`.
  `FluentBitSet`
  `clear()`
  Sets all of the bits in this BitSet to `false`.
  `FluentBitSet`
  `clear(int bitIndex)`
  Sets the bit specified by the index to `false`.
  `FluentBitSet`
  `clear(int... bitIndexArray)`
  Sets the bits specified by the indexes to `false`.
  `FluentBitSet`
  `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.
  `boolean`
  `equals(Object obj)`
  `FluentBitSet`
  `flip(int bitIndex)`
  Sets the bit at the specified index to the complement of its current value.
  `FluentBitSet`
  `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)`
  Gets the value of the bit with the specified index.
  `FluentBitSet`
  `get(int fromIndex, int toIndex)`
  Gets a new `BitSet` composed of bits from this `BitSet` from `fromIndex` (inclusive) to `toIndex` (exclusive).
  `int`
  `hashCode()`
  `boolean`
  `intersects(BitSet set)`
  Returns true if the specified `BitSet` has any bits set to `true` that are also set to `true` in this `BitSet`.
  `boolean`
  `intersects(FluentBitSet set)`
  Returns true if the specified `BitSet` has any bits set to `true` that are also set to `true` in this `BitSet`.
  `boolean`
  `isEmpty()`
  Tests whether if this `BitSet` contains no bits that are set to `true`.
  `int`
  `length()`
  Returns the "logical size" of this `BitSet`: the index of the highest set bit in the `BitSet` plus one.
  `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.
  `FluentBitSet`
  `or(BitSet set)`
  Performs a logical OR of this bit set with the bit set argument.
  `FluentBitSet`
  `or(FluentBitSet set)`
  Performs a logical OR of this bit set with the bit set argument.
  `FluentBitSet`
  `or(FluentBitSet... set)`
  Performs a logical OR of this bit set with the bit set arguments.
  `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.
  `FluentBitSet`
  `set(int bitIndex)`
  Sets the bit at the specified index to `true`.
  `FluentBitSet`
  `set(int... bitIndexArray)`
  Sets the bit at the specified indexes to `true`.
  `FluentBitSet`
  `set(int bitIndex, boolean value)`
  Sets the bit at the specified index to the specified value.
  `FluentBitSet`
  `set(int fromIndex, int toIndex)`
  Sets the bits from the specified `fromIndex` (inclusive) to the specified `toIndex` (exclusive) to `true`.
  `FluentBitSet`
  `set(int fromIndex, int toIndex, boolean value)`
  Sets the bits from the specified `fromIndex` (inclusive) to the specified `toIndex` (exclusive) to the specified value.
  `FluentBitSet`
  `setInclusive(int fromIndex, int toIndex)`
  Sets the bits from the specified `fromIndex` (inclusive) to the specified `toIndex` (inclusive) to `true`.
  `int`
  `size()`
  Returns the number of bits of space actually in use by this `BitSet` to represent bit values.
  `IntStream`
  `stream()`
  Returns a stream of indices for which this `BitSet` contains a bit in the set state.
  `byte[]`
  `toByteArray()`
  Returns a new byte array containing all the bits in this bit set.
  `long[]`
  `toLongArray()`
  Returns a new byte array containing all the bits in this bit set.
  `String`
  `toString()`
  `FluentBitSet`
  `xor(BitSet set)`
  Performs a logical XOR of this bit set with the bit set argument.
  `FluentBitSet`
  `xor(FluentBitSet set)`
  Performs a logical XOR of this bit set with the bit set argument.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### FluentBitSet

    public FluentBitSet()
    Creates a new bit set. All bits are initially `false`.

  - ### FluentBitSet

    public FluentBitSet(BitSet set)
    Creates a new instance for the given bit set.
    Parameters:
      `set` - The bit set to wrap.

  - ### FluentBitSet

    public FluentBitSet(int nbits)
    Creates a bit set whose initial size is large enough to explicitly represent bits with indices in the range `0` through `nbits-1`. All bits are initially `false`.
    Parameters:
      `nbits` - the initial size of the bit set.
    Throws:
      `NegativeArraySizeException` - if the specified initial size is negative.

- ## Method Details

  - ### and

    public FluentBitSet and(BitSet set)
    Performs a logical AND of this target bit set with the argument bit set. This bit set 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 bit set argument also had the value `true`.
    Parameters:
      `set` - a bit set.
    Returns:
      `this` instance.

  - ### and

    public FluentBitSet and(FluentBitSet set)
    Performs a logical AND of this target bit set with the argument bit set. This bit set 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 bit set argument also had the value `true`.
    Parameters:
      `set` - a bit set.
    Returns:
      `this` instance.

  - ### andNot

    public FluentBitSet andNot(BitSet set)
    Clears all of the bits in this `BitSet` whose corresponding bit is set in the specified `BitSet`.
    Parameters:
      `set` - the `BitSet` with which to mask this `BitSet`.
    Returns:
      `this` instance.

  - ### andNot

    public FluentBitSet andNot(FluentBitSet set)
    Clears all of the bits in this `BitSet` whose corresponding bit is set in the specified `BitSet`.
    Parameters:
      `set` - the `BitSet` with which to mask this `BitSet`.
    Returns:
      `this` instance.

  - ### bitSet

    public BitSet bitSet()
    Gets the wrapped bit set.
    Returns:
      the wrapped bit set.

  - ### cardinality

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

  - ### clear

    public FluentBitSet clear()
    Sets all of the bits in this BitSet to `false`.
    Returns:
      `this` instance.

  - ### clear

    public FluentBitSet clear(int... bitIndexArray)
    Sets the bits specified by the indexes to `false`.
    Parameters:
      `bitIndexArray` - the index of the bit to be cleared.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if the specified index is negative.

  - ### clear

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

  - ### clear

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if `fromIndex` is negative, or `toIndex` is negative, or `fromIndex` is larger than `toIndex`.

  - ### clone

    public Object clone()
    Cloning this `BitSet` produces a new `BitSet` that is equal to it. The clone of the bit set is another bit set that has exactly the same bits set to `true` as this bit set.
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this bit set
    See Also:
      - `size()`

  - ### equals

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

  - ### flip

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if the specified index is negative.

  - ### flip

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if `fromIndex` is negative, or `toIndex` is negative, or `fromIndex` is larger than `toIndex`.

  - ### get

    public boolean get(int bitIndex)
    Gets 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 FluentBitSet get(int fromIndex, int toIndex)
    Gets a new `BitSet` composed of bits from this `BitSet` from `fromIndex` (inclusive) to `toIndex` (exclusive).
    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`.

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### intersects

    public boolean intersects(BitSet set)
    Returns true if the specified `BitSet` has any bits set to `true` that are also set to `true` in this `BitSet`.
    Parameters:
      `set` - `BitSet` to intersect with.
    Returns:
      boolean indicating whether this `BitSet` intersects the specified `BitSet`.

  - ### intersects

    public boolean intersects(FluentBitSet set)
    Returns true if the specified `BitSet` has any bits set to `true` that are also set to `true` in this `BitSet`.
    Parameters:
      `set` - `BitSet` to intersect with.
    Returns:
      boolean indicating whether this `BitSet` intersects the specified `BitSet`.

  - ### isEmpty

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

  - ### length

    public int length()
    Returns the "logical size" of this `BitSet`: the index of the highest set bit in the `BitSet` plus one. Returns zero if the `BitSet` contains no set bits.
    Returns:
      the logical size of this `BitSet`.

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

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

    To iterate over the `true` bits in a `BitSet`, use the following loop:

         for (int i = bs.nextSetBit(0); i >= 0; i = bs.nextSetBit(i+1)) {
             // operate on index i here
             if (i == Integer.MAX_VALUE) {
                 break; // or (i+1) would overflow
             }
         }

    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.

  - ### or

    public FluentBitSet or(BitSet set)
    Performs a logical OR of this bit set with the bit set argument. This bit set 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 bit set argument has the value `true`.
    Parameters:
      `set` - a bit set.
    Returns:
      `this` instance.

  - ### or

    public FluentBitSet or(FluentBitSet... set)
    Performs a logical OR of this bit set with the bit set arguments. This bit set 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 bit set argument has the value `true`.
    Parameters:
      `set` - a bit set.
    Returns:
      `this` instance.

  - ### or

    public FluentBitSet or(FluentBitSet set)
    Performs a logical OR of this bit set with the bit set argument. This bit set 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 bit set argument has the value `true`.
    Parameters:
      `set` - a bit set.
    Returns:
      `this` instance.

  - ### 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`.

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

    To iterate over the `true` bits in a `BitSet`, use the following loop:

         for (int i = bs.length(); (i = bs.previousSetBit(i-1)) >= 0; ) {
             // operate on index i here
         }

    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`

  - ### set

    public FluentBitSet set(int... bitIndexArray)
    Sets the bit at the specified indexes to `true`.
    Parameters:
      `bitIndexArray` - a bit index array.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if the specified index is negative.

  - ### set

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

  - ### set

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if the specified index is negative.

  - ### set

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if `fromIndex` is negative, or `toIndex` is negative, or `fromIndex` is larger than `toIndex`.

  - ### set

    public FluentBitSet 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.
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if `fromIndex` is negative, or `toIndex` is negative, or `fromIndex` is larger than `toIndex`.

  - ### setInclusive

    public FluentBitSet setInclusive(int fromIndex, int toIndex)
    Sets the bits from the specified `fromIndex` (inclusive) to the specified `toIndex` (inclusive) to `true`.
    Parameters:
      `fromIndex` - index of the first bit to be set
      `toIndex` - index of the last bit to be set
    Returns:
      `this` instance.
    Throws:
      `IndexOutOfBoundsException` - if `fromIndex` is negative, or `toIndex` is negative, or `fromIndex` is larger than `toIndex`

  - ### size

    public int size()
    Returns the number of bits of space actually in use by this `BitSet` to represent bit values. The maximum element in the set is the size - 1st element.
    Returns:
      the number of bits currently in this bit set.

  - ### stream

    public IntStream stream()
    Returns a stream of indices for which this `BitSet` contains a bit in the set state. The indices are returned in order, from lowest to highest. The size of the stream is the number of bits in the set state, equal to the value returned by the `cardinality()` method.

    The bit set must remain constant during the execution of the terminal stream operation. Otherwise, the result of the terminal stream operation is undefined.

    Returns:
      a stream of integers representing set indices.
    Since:
      1.8

  - ### toByteArray

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

    More precisely, if:

    1. `byte[] bytes = s.toByteArray();`
    2. then `bytes.length == (s.length()+7)/8` and
    3. `s.get(n) == ((bytes[n/8] & (1<<(n%8))) != 0)`
    4. for all `n < 8 * bytes.length`.
    Returns:
      a byte array containing a little-endian representation of all the bits in this bit set

  - ### toLongArray

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

    More precisely, if:

    1. `long[] longs = s.toLongArray();`
    2. then `longs.length == (s.length()+63)/64` and
    3. `s.get(n) == ((longs[n/64] & (1L<<(n%64))) != 0)`
    4. for all `n < 64 * longs.length`.
    Returns:
      a byte array containing a little-endian representation of all the bits in this bit set

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### xor

    public FluentBitSet xor(BitSet set)
    Performs a logical XOR of this bit set with the bit set argument. This bit set 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 bit set
    Returns:
      `this` instance.

  - ### xor

    public FluentBitSet xor(FluentBitSet set)
    Performs a logical XOR of this bit set with the bit set argument. This bit set 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 bit set
    Returns:
      `this` instance.