net.rim.device.api.util
Class BitSet

java.lang.Object
  |
  +--net.rim.device.api.util.BitSet
All Implemented Interfaces:
Persistable

public class BitSet
extends Object
implements Persistable

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 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(BitSet srcBitSet)
          Constructs a new BitSet instance using another as a template.
BitSet(int size)
          Constructs a new BitSet instance of provided size.
 
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(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.

BitSet

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

Parameters:
size - Number of bits this set must accomodate.
Method Detail

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

not

public void not()
Performs logical NOT on 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.

reset

public void reset()
Clears all bits.


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.

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.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.