net.rim.device.api.util
Class BitSet

java.lang.Object
  net.rim.device.api.util.BitSet

public class BitSet
extends Object

Maintains a collection of bits.

Behaviour
For efficiency purposes, this set maintains an internal cache of the number of bits that are set. Any normal operation affecting a bit's state updates this cache value to keep it current.

However, some operations ignore the value of this cache, specifically, operations which could set bits beyond your declared size of the set. Typically, this occurs if you NOT the contents of a set: since the set is actually stored as a collection of 32 bit ints, any bits beyond your size mod 32 will be affected by a NOT operation, and this will automatically increase the size of the bitset (as bits beyond the current size will now be set). This can also happen if you OR or AND your set with another, larger set: if bits in your set beyond its size are set on, then the size of your set (and the number of set bits) must increase accordingly.

Alternatively, you can save this time by using the fast set and clear methods, which ignore the cache; however, the cache then becomes unsuable and calls to BitSet.getNumSet() must dive into the bit set itself (and reset the cache) rather than simply retrieving the value out of the cache.

Constructor Summary

BitSet()
Constructs a new BitSet instance with enough room for 128 bits.

BitSet(int size)
Constructs a new BitSet instance of provided size.

BitSet(BitSet srcBitSet)
Constructs a new BitSet instance using another as a template.

Method Summary
void	and(BitSet mask) Performs bitwise AND on this set with provided mask.
void	clear(int index) Clears bit by index.
boolean	equals(Object obj) Compares this bit set to provided object.
void	fastClear(int index) Clears bit by index, ignoring cache.
void	fastSet(int index) Sets bit by index, ignoring cache.
int	getFirstSet() Retrieves first set bit in this set.
int	getLastSet() Retrieves last set bit in this set.
int	getNextSet(int index) Retrieves the first bit set starting forward from provided position.
int	getNumSet() Retrieves number of set bits.
int	getPreviousSet(int index) Retrieves the first bit set starting backwards from provided position.
boolean	isSet(int index) Determines bit state by index.
void	not() Performs logical NOT on this set.
void	or(BitSet mask) Performs binary OR on this set with provided mask.
void	reset() Clears all bits.
void	set(int index) Sets bit by index.
void	xor(BitSet mask) Performs binary XOR on this set with provided mask.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BitSet

public BitSet()

Constructs a new BitSet instance with enough room for 128 bits.

BitSet

public BitSet(int size)

Constructs a new BitSet instance of provided size.

Parameters:

size - Number of bits this set must accomodate.

BitSet

public BitSet(BitSet srcBitSet)

Constructs a new BitSet instance using another as a template.

This builds a bit set using another's size and contents as initial values.

Parameters:

srcBitSet - Source bit set.

Method Detail

fastSet

public void fastSet(int index)

Sets bit by index, ignoring cache.

This method doesn't bother to keep the cache of the number of set bits up to date.

Parameters:

index - Position of bit to set.

set

public void set(int index)

Sets bit by index.

Unless the cache of number of set bits has been made unusable, this method keeps it up to date. If the cache is unusable, this method doesn't bother fixing it.

Parameters:

index - Position of bit to set.

fastClear

public void fastClear(int index)

Clears bit by index, ignoring cache.

This method doesn't bother to keep the cache of the number of set bits up to date.

Parameters:

index - Position of bit to clear.

clear

public void clear(int index)

Clears bit by index.

Unless the cache of number of set bits has been made unusable, this method keeps it up to date. If the cache is unusable, this method doesn't bother fixing it.

Parameters:

index - Position of bit to clear.

reset

public void reset()

Clears all bits.

isSet

public boolean isSet(int index)

Determines bit state by index.

Parameters:

index - Position of bit to test.

Returns:

True if bit is set; otherwise, false.

getNumSet

public int getNumSet()

Retrieves number of set bits.

If the cache of number of set bits is usable, this method returns its value; otherwise, this method walks through the set to determine the state of each bit in turn. In the latter case, this method also resets the cache, making it usable again.

Returns:

Number of set bits.

equals

public boolean equals(Object obj)

Compares this bit set to provided object.

Note that this method does require that both objects be bit sets for equality; however, the two bit sets do not need to be of equal length. This method tests for equality only in the positions that both sets provide. Thus if this set is only four bits long, while the obj parameter is a set that's 20 bits long, this method tests only the first four bits of both sets for equality.

Overrides:

equals in class Object

Parameters:

obj - Object to compare with this bit set.

Returns:

True only if the following conditions are met: (1) the compared object is a bit set, (2) the corresponding bits in both sets have identical states.

See Also:

Boolean.hashCode(), Hashtable

getNextSet

public int getNextSet(int index)

Retrieves the first bit set starting forward from provided position.

This method starts at the provided position and checks forward towards the end of the bit set.

Parameters:

index - First bit to check.

Returns:

Index of first set bit found, or -1 if none found before end of set is reached.

getPreviousSet

public int getPreviousSet(int index)

Retrieves the first bit set starting backwards from provided position.

This method starts at the provided position and checks backwards towards the start of the bit set.

Parameters:

index - First bit to check.

Returns:

Index of first set bit found, or -1 if none found before start of set is reached.

getFirstSet

public int getFirstSet()

Retrieves first set bit in this set.

Returns:

Index of first set bit in this set, or -1 if none found.

getLastSet

public int getLastSet()

Retrieves last set bit in this set.

Returns:

Index of last set bit in this set, or -1 if none found.

and

public void and(BitSet mask)

Performs bitwise AND on this set with provided mask.

Parameters:

mask - Bit mask to use; if the mask is shorter than this set, then invoking this method has the effect of clearing those "extra" bits in this set.

or

public void or(BitSet mask)

Performs binary OR on this set with provided mask.

Parameters:

mask - Bit mask to use; if the mask is longer than this set, then this method first pads this set with zeros to make it the same length as the mask, and then applies the mask.

not

public void not()

Performs logical NOT on this set.

xor

public void xor(BitSet mask)

Performs binary XOR on this set with provided mask.

Parameters:

mask - Bit mask to use; if the mask is longer than this set, then this method first pads this set with zeros to make it the same length as the mask, and then applies the mask.