# Class BS

java.lang.Object
javajs.util.BS

All Implemented Interfaces:
  `Cloneable, JSONEncodable`

Direct Known Subclasses:
  `BondSet`

public class BS extends Object implements Cloneable, JSONEncodable
a fast 32-bit BitSet optimized for Java2Script -- about 25 times faster than java.util.BitSet

Since:
  JDK1.0
Author:
  Bob Hanson hansonr@stolaf.edu Additions by Bob Hanson to allow for JavaScript mix of int/long Note that Firefox (Sept 2012) does not really treat "Int32Array" as such, because any element can be pushed into being a 64-bit number, which really isn't because the last 8 bits are not usable. This class implements a vector of bits that grows as needed. Each component of the bit set has a `boolean` value. The bits of a `BitSet` are indexed by nonnegative integers. Individual indexed bits can be examined, set, or cleared. One `BitSet` may be used to modify the contents of another `BitSet` through logical AND, logical inclusive OR, and logical exclusive OR operations.

  By default, all bits in the set initially have the value `false`.

  Every bit set has a current size, which is the number of bits of space currently in use by the bit set. Note that the size is related to the implementation of a bit set, so it may change with implementation. The length of a bit set relates to logical length of a bit set and is defined independently of implementation.

  Unless otherwise noted, passing a null parameter to any of the methods in a `BitSet` will result in a `NullPointerException`.

  A `BitSet` is not safe for multithreaded use without external synchronization., Arthur van Hoff, Michael McCloskey, Martin Buchholz

## Constructor Summary

Constructors
Constructor
Description
`BS()`
Creates a new bit set.

## Method Summary

Modifier and Type
Method
Description
`void`
`and(BS set)`
Performs a logical AND of this target bit set with the argument bit set.
`void`
`andNot(BS 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 `BitSet`.
`int`
`cardinalityN(int max)`
`void`
`clear(int bitIndex)`
Sets the bit specified by the index to `false`.
`void`
`clearAll()`
Sets all of the bits in this BitSet to `false`.
`void`
`clearBits(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.
`static BS`
`copy(BS bitsetToCopy)`
fast copy
`boolean`
`equals(Object obj)`
Compares this object against the specified object.
`static String`
`escape(BS bs, char chOpen, char chClose)`
`boolean`
`get(int bitIndex)`
Returns the value of the bit with the specified index.
`int`
`hashCode()`
Returns a hash code value for this bit set.
`boolean`
`intersects(BS set)`
Returns true if the specified `BitSet` has any bits set to `true` that are also set to `true` in this `BitSet`.
`boolean`
`isEmpty()`
Returns true 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.
`static BS`
`newN(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`.
`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(BS set)`
Performs a logical OR of this bit set with the bit set argument.
`void`
`set(int bitIndex)`
Sets the bit at the specified index to `true`.
`void`
`setBits(int fromIndex, int toIndex)`
Sets the bits from the specified `fromIndex` (inclusive) to the specified `toIndex` (exclusive) to `true`.
`void`
`setBitTo(int bitIndex, boolean value)`
Sets the bit at the specified index to the specified value.
`int`
`size()`
Returns the number of bits of space actually in use by this `BitSet` to represent bit values.
`String`
`toJSON()`
`String`
`toString()`
Returns a string representation of this bit set.
`static BS`
`unescape(String str)`
`void`
`xor(BS set)`
Performs a logical XOR of this bit set with the bit set argument.

### Methods inherited from class Object

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

## Constructor Details

### BS

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

## Method Details

### newN

public static BS newN(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
Returns:
  bs
Throws:
  `NegativeArraySizeException` - if the specified initial size is negative

### 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
Since:
  JDK1.0

### setBitTo

public void setBitTo(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
Since:
  1.4

### setBits

public void setBits(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`
Since:
  1.4

### 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
Since:
  JDK1.0

### clearBits

public void clearBits(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`
Since:
  1.4

### clearAll

public void clearAll()
Sets all of the bits in this BitSet to `false`.

Since:
  1.4

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

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

### 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
Since:
  1.4

### 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`
Since:
  1.2

### isEmpty

public boolean isEmpty()
Returns true if this `BitSet` contains no bits that are set to `true`.

Returns:
  boolean indicating whether this `BitSet` is empty
Since:
  1.4

### intersects

public boolean intersects(BS 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`
Since:
  1.4

### 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`
Since:
  1.4

### and

public void and(BS 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

### or

public void or(BS 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

### xor

public void xor(BS 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

### andNot

public void andNot(BS 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`
Since:
  1.2

### hashCode

public int hashCode()
Returns a hash code value for this bit set. The hash code depends only on which bits have been set within this `BitSet`. The algorithm used to compute it may be described as follows.

Suppose the bits in the `BitSet` were to be stored in an array of `long` integers called, say, `words`, in such a manner that bit `k` is set in the `BitSet` (for nonnegative values of `k`) if and only if the expression

    ((k >> 6) < words.length) && ((words[k >> 6] & (1 << (bit & 0x3F))) != 0)

is true. Then the following definition of the `hashCode` method would be a correct implementation of the actual algorithm:

    public int hashCode() {
     long h = 1234;
     for (int i = words.length; --i >= 0;) {
       h ˆ= words[i] * (i + 1);
     }
     return (int) ((h >> 32) ˆ h);
    }

Note that the hash code values change if the set of bits is altered.

Overrides the `hashCode` method of `Object`.

Overrides:
  `hashCode` in class `Object`
Returns:
  a hash code value for this bit set.

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

### 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 `Bitset` object that has exactly the same set of bits set to `true` as this bit set. That is, for every nonnegative `int` index `k`,

    ((BitSet) 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
See Also:
  - `size()`

### 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()`

### toString

public String toString()
Returns a string representation of this bit set. For every index for which this `BitSet` contains a bit in the set state, the decimal representation of that index is included in the result. Such indices are listed in order from lowest to highest, separated by ", " (a comma and a space) and surrounded by braces, resulting in the usual mathematical notation for a set of integers.

Example:

    BitSet drPepper = new BitSet();

Now `drPepper.toString()` returns "{}".

    drPepper.set(2);

Now `drPepper.toString()` returns "{2}".

    drPepper.set(4);
    drPepper.set(10);

Now `drPepper.toString()` returns "{2, 4, 10}".

Overrides:
  `toString` in class `Object`
Returns:
  a string representation of this bit set

### copy

public static BS copy(BS bitsetToCopy)
fast copy

Parameters:
  `bitsetToCopy` -
Returns:
  bs

### cardinalityN

public int cardinalityN(int max)

Parameters:
  `max` -
Returns:
  n bits below max

### toJSON

public String toJSON()

Specified by:
  `toJSON` in interface `JSONEncodable`

### escape

public static String escape(BS bs, char chOpen, char chClose)

### unescape

public static BS unescape(String str)