This class
implements an array or list of boolean values
storing them using a very compact representation that requires only
about one bit per value stored. It implements methods for setting,
querying, and flipping the values stored at any given position within
the list, for counting the number of true values
stored in the list, and for finding the next TRue
or false value in the list. It also defines a
number of methods that perform bitwise boolean operations on two
BitSet objects. Despite its name,
BitSet does not implement the
Set interface, and does not even have the behavior
associated with a set; it is a list or vector for
boolean values, but is not related to the
List interface or Vector class.
This class was introduced in Java 1.0, but was substantially enhanced
in Java 1.4; note that many of the methods described below are only
available in Java 1.4 and later.
Create a BitSet with the BitSet(
) constructor. You may optionally specify a size (the
number of bits) for the BitSet, but this merely
provides an optimization since a BitSet will grow
as needed to accomodate any number of boolean
values. BitSet does not define a precise notion of
the size of a "set." The
size( ) method returns the number of boolean
values that can be stored before more internal storage needs to be
allocated. The length( ) method returns one more
than the highest index of a set bit (i.e., a true
value). This means that a BitSet that contains all
false values will have a length(
) of zero. If your code needs to remember the index of the
highest value stored in a BitSet, regardless of
whether that value was TRue or
false, then you should maintain that length
information separately from the BitSet.
Set values in a BitSet with the set(
) method. There are four versions of this method. Two set
the value at a specific index, and two set values for a range of
indexes. Two of the set( ) methods do not take a
value argument to set: they "set"
the specified bit or range of bites, which means they store the value
true. The other two methods take a
boolean argument, allowing you to set the
specified value or range of values to true (a set
bit) or false (a clear bit). There are also two
clear( ) methods that
"clear" (or set to
false) the value at the specified index or range
of indexes. The flip( ) methods flip, or toggle
(change TRue to false and
false to TRue), the value or
values at the specified index or range. The set(
), clear( ), and flip(
) methods, as well as all other BitSet
methods that operate on a range of values specify the range with two
index values. They define the range as the values starting from, and
including, the value stored at the first specified index up to,
but not including, the value stored at the
second specified index. (A number of methods of
String and related classes follow the same
convention for specifying a range of characters.)
To test the value stored at a specified location, use get(
), which returns true if the specified
bit is set, or false if it is not set. There is
also a get( ) method that specifies a range of
bits, and returns their state in the form of a
BitSet: this get( ) method is
analogous to the substring( ) method of a
String. Because a BitSet does
not define a maximum index, it is legal to pass any non-negative
value to get( ). If the index you specify is
greater than or equal to the value returned by length(
), then the returned value will always be
false.
cardinality( ) returns the number of
true values (or of set bits) stored in a
BitSet. isEmpty( ) returns
true if a BitSet has no
true values stored in it (in this case, both
length( ) and cardinality( )
return 0). nextSetBit( ) returns the first index
at or after the specified index at which a true
value is stored (or at which the bit is set). You can use this method
in a loop to iterate through the indexes of true
values. nextClearBit( ) is similar, but searches
the BitSet for false values
(clear bits) intead. The intersects( ) method
returns true if the target
BitSet and the argument BitSet
intersect: that is if there is at least one index at which both
BitSet objects have a true
value.
BitSet defines several methods that perform
bitwise Boolean operations. These methods combine the
BitSet on which they are invoked (called the
"target" BitSet
below) with the BitSet passed as an argument, and
store the result in the target BitSet. If you want
to perform a Boolean operation without altering the original
BitSet, you should first make a copy of the
original with the clone( ) method and invoke the
method on the copy. The and( ) method preforms a
bitwise Boolean AND operation, much like the &
does when applied to integer arguments. A value in the target
BitSet will be true only if it
was originally true and the
value at the same index of argument BitSet is also
TRue. For all false values in
the argument BitSet, and( )
sets the corresponding value in the target BitSet
to false, leaving other values unchanged. The
andNot( ) method combines a Boolean AND operation
with a Boolean NOT operation on the argument
BitSet (it does not alter the contents of that
argument BitSet, hoever). The result is that for
all TRue values in the argument
BitSet, the corresponding values in the target
BitSet are set to false.
The or( ) method performs a bitwise Boolean OR
operation like the | operator: a value in the
BitSet will be set to true if
its original value was TRue
or the corresponding value in the argument
BitSet was true. For all TRue
values in the argument BitSet, the or(
) method sets the corresponding value in the target
BitSet to true, leaving the
other values unchanged. The xor( ) method performs
an "exclusive OR" operation: sets a
value in the target BitSet to
TRue if it was originally true
or if the corresponding value in the argument
BitSet was true. If both values
were false, or if both values were
true, however, it sets the value to
false.
Finally, the toString( ) method returns a
String representation of a
BitSet that consists of a list within curly braces
of the indexes at which TRue values are stored.
The BitSet class is not threadsafe.
public class BitSet implements Cloneable, Serializable {
// Public Constructors
public BitSet( );
public BitSet(int nbits);
// Public Instance Methods
public void and(BitSet set);
1.2 public void andNot(BitSet set);
1.4 public int cardinality( );
1.4 public void clear( );
public void clear(int bitIndex);
1.4 public void clear(int fromIndex, int toIndex);
1.4 public void flip(int bitIndex);
1.4 public void flip(int fromIndex, int toIndex);
public boolean get(int bitIndex);
1.4 public BitSet get(int fromIndex, int toIndex);
1.4 public boolean intersects(BitSet set);
1.4 public boolean isEmpty( ); default:true
1.2 public int length( );
1.4 public int nextClearBit(int fromIndex);
1.4 public int nextSetBit(int fromIndex);
public void or(BitSet set);
public void set(int bitIndex);
1.4 public void set(int bitIndex, boolean value);
1.4 public void set(int fromIndex, int toIndex);
1.4 public void set(int fromIndex, int toIndex, boolean value);
public int size( );
public void xor(BitSet set);
// Public Methods Overriding Object
public Object clone( );
public boolean equals(Object obj);
public int hashCode( );
public String toString( );
}
