net.rim.device.api.util
Class IntMultiMap

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

All Implemented Interfaces:

Persistable

public class IntMultiMap
extends Object
implements Persistable

Provides a one to many mapping between an integer key and some values.

Constructor Summary

IntMultiMap()
Constructs a new IntMultiMap instance.

IntMultiMap(int initialCapacity, boolean allowDuplicates)
Constructs a new IntMultiMap instance with the provided capacity.

Method Summary
void	add(int key, Object value) Maps value to key.
void	clear() Removes all keys and values.
boolean	containsKey(int key) Determines if key is mapped.
boolean	containsValue(int key, Object value) Determines if value is mapped to key.
Enumeration	elements() Retrieves an enumeration of the values in this map.
Enumeration	elements(int key) Retrieves an enumeration of values for a key.
protected int	findKey(int key) Returns > 0 if key is found, or < 0 if key is not found.
boolean	isEmpty() Determines if this map is empty.
IntEnumeration	keys() Retrieves an enumeration of the keys in this map.
boolean	removeKey(int key) Removes values by key.
boolean	removeValue(int key, Object value) Removes value by key from map.
boolean	removeValue(Object value) Removes value from map.
int	size() Retrieves the number of keys in this map.
int	size(int key) Retrieves number of values for a key.
void	trim() Releases any extra memory.
protected void	verifySorted() Sorts the array of values.

Methods inherited from class java.lang.Object

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

Constructor Detail

IntMultiMap

public IntMultiMap(int initialCapacity,
                   boolean allowDuplicates)

Constructs a new IntMultiMap instance with the provided capacity.

Parameters:

initialCapacity - Starting capacity for this map.

allowDuplicates - If true, then duplicate key-value mappings are allowed, otherwise duplicates are ignored. It is more efficient to allow duplicate mappings, if possible. Two key-value mappings, say i and j are considered duplicate iff key[i] == key[j] && value[i].equals( value[j] )

IntMultiMap

public IntMultiMap()

Constructs a new IntMultiMap instance.

This method creates a new multi map with an initial capacity of 16, and ignores duplicate key-value mappings.

Method Detail

isEmpty

public boolean isEmpty()

Determines if this map is empty.

Returns:

True if this map has no entries; otherwise, false.

clear

public void clear()

Removes all keys and values.

trim

public void trim()

Releases any extra memory.

Invoke this method to trim off any underlying storage allocated by not used by this multimap.

add

public void add(int key,
                Object value)

Maps value to key.

Parameters:

key - Key to associate with value; if this key already exists in the map, the provided value is added to its association list.

value - Value to associate with key.

verifySorted

protected void verifySorted()

Sorts the array of values.

Since:

BlackBerry API 3.6.0

findKey

protected int findKey(int key)

Returns > 0 if key is found, or < 0 if key is not found.

removeKey

public boolean removeKey(int key)

Removes values by key.

Parameters:

key - Key for value(s) to remove.

Returns:

True if key was removed; otherwise, false.

removeValue

public boolean removeValue(int key,
                           Object value)

Removes value by key from map.

If the value to remove is the last one associated with the key, then this method removes the key as well. Otherwise, this method removes only the value from the map; the key and its associations with other values remains.

Parameters:

key - Key associated with value.

value - Value to remove.

Returns:

True if value was removed; otherwise, false.

removeValue

public boolean removeValue(Object value)

Removes value from map.

Invoke this method to remove a value from this map when you don't know its associated key. If you do know the key associated with this value, then you should invoke the more efficient IntMultiMap.removeValue(int,Object).

If the value to remove is the last one associated with its key, then this method removes the key as well. Otherwise, this method removes only the value from the map; the key and its associations with other values remains.

Parameters:

value - Value to remove.

Returns:

True if value was removed; otherwise, false.

containsKey

public boolean containsKey(int key)

Determines if key is mapped.

Parameters:

key - Key to check.

Returns:

True if key has at least one associated value; otherwise, false.

containsValue

public boolean containsValue(int key,
                             Object value)

Determines if value is mapped to key.

Parameters:

key - Key to check.

value - Value to check.

Returns:

True if value is mapped to key; otherwise, false.

keys

public IntEnumeration keys()

Retrieves an enumeration of the keys in this map.

Returns:

Enumeration of the keys in this map.

See Also:

IntEnumeration, IntMultiMap.elements(int)

elements

public Enumeration elements(int key)

Retrieves an enumeration of values for a key.

Parameters:

key - Key associated with values.

Returns:

Enumeration of the values associated with provided key.

See Also:

Enumeration

elements

public Enumeration elements()

Retrieves an enumeration of the values in this map.

Returns:

Enumeration of the values in this map.

See Also:

Enumeration, IntMultiMap.keys()

size

public int size()

Retrieves the number of keys in this map.

Note that this method gives you the number of keys contained in the map, not the number of values in the map (which could be larger).

Returns:

Number of keys in this map.

size

public int size(int key)

Retrieves number of values for a key.

Parameters:

key - Key in question.

Returns:

Number of values associated with provided key.