OLMultiMap Class Reference
[Containers]

A map that allows many values to be associated with equivilent keys. More...

#import <ObjectiveLib/Map.h>

Inheritance diagram for OLMultiMap:

Inheritance graph
[legend]
List of all members.

Public Member Functions

(void) - assignKey:value:
 Assign a value to a key.
(id) - insert:
 Insert a key-value pair into the map.
(OLAssociativeIterator *) - insertAt:value:
 Insert a key-value pair into the map.
(void) - insertFrom:to:
 Insert a range of key-value pairs into the map.
(BOOL) - isEqual:
 Test whether another map is equal to this one.
(id) - valueForKey:
 Find the value of a given key.

Static Public Member Functions

(id) + multiMap
 Create and return a new map.
(id) + multiMapFrom:to:
 Create and return a new map.
(id) + multiMapWithCompare:
 Create and return a new map.
(id) + multiMapWithMap:
 Create and return a new map.

Detailed Description

A map that allows many values to be associated with equivilent keys.

Multimap is identical to map expect that as many instances of any given key may be inserted as desired.

See also:
OLMap, OLAssociativeIterator


Member Function Documentation

- (void) assignKey: (id)  key
value: (id)  value 

Assign a value to a key.

This message always inserts the key-value pair (key, value).

Parameters:
key the key to insert
value the key's value

Reimplemented from OLMap.

- (id) insert: (OLPair *)  keyValue  

Insert a key-value pair into the map.

The pair is inserted and an instance of OLAssociativeIterator is returned indicating the position of keyValue in the set. The object to which the iterator points is an instance of OLPair. The first element of the pair is the key and the second element of the pair is the key's value.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
keyValue the element to insert
Returns:
an instance of OLAssociativeIterator pointing to the newly inserted object

Reimplemented from OLMap.

- (OLAssociativeIterator*) insertAt: (OLAssociativeIterator *)  where
value: (OLPair *)  keyVal 

Insert a key-value pair into the map.

The keyVal is inserted and the position indicated by where is used as a hint about where in the map the keyVal should be placed. There is no guarantee that the keyVal will ultimately placed anywhere close to where. Note that the insertion may fail if the key is already in the map. An iterator is returned that points to object. The object to which the iterator points is an instance of OLPair. The first element of the pair is the key and the second element of the pair is the key's value.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
where a hint as to where in the map the keyVal should be located
keyVal the key-value pair to insert
Returns:
the iterator indicating where keyVal is now located in the map

Reimplemented from OLMap.

- (void) insertFrom: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Insert a range of key-value pairs into the map.

An attempt is made to insert all pairs in the range [first, last), however there is no guarantee that any of the elements in the range will actually be inserted if they already exist in the map.

Precondition:
All elements in the range [first, last) must be instances of OLPair where the first element of the pair is the key and the second element is the key's value.
Parameters:
first the first in the range of pairs to insert
last one position beyond the last in the range of pairs to insert

Reimplemented from OLMap.

- (BOOL) isEqual: (id)  object  

Test whether another map is equal to this one.

Two maps are considered equal if they contain the same number of objects and the and the value of each key is equal to the value of the corresponding key in the other map.

Note:
When two maps each contain a range of equal keys, the values that correspond to those keys do not have to appear in the same order. They just have to exist.
Parameters:
object the object to test
Returns:
YES if object is equal to this map, NO otherwise

Reimplemented from OLMap.

+ (id) multiMap  

Create and return a new map.

An instance of OLLess is used to compare keys for sorting.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Returns:
a new map

+ (id) multiMapFrom: (OLForwardIterator *)  first
to: (OLForwardIterator *)  last 

Create and return a new map.

The map is initialized with the contents of the range [first, last). An instance of OLLess is used to compare keys for sorting.

Precondition:
Each element in the range [first, last) must be an instance of OLPair. The first element of the pair is the key and the second element is the key's value.
Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
first the first in the range of elements to insert
last one beyond the last in the range of elements to insert
Returns:
a new map

+ (id) multiMapWithCompare: (OLStreamableFunctor< OLBoolBinaryFunction > *)  comp  

Create and return a new map.

The map is empty and the comparison function comp is used to sort keys.

Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Parameters:
comp the comparison function used to sort keys
Returns:
a new map

+ (id) multiMapWithMap: (OLMap *)  right  

Create and return a new map.

The map is initialized with the contents of right.

Note:
The map right may be either an instance of OLMap or an instance of OLMultiMap.

If OpenStep is present the returned object will be autoreleased before being returned.

Parameters:
right the map to copy
Returns:
a new map

- (id) valueForKey: (id)  key  

Find the value of a given key.

Since a multimap can have any number of values associated with equivilent keys, this message does nothing. The value nil is always returned.

Parameters:
key the key for which to search
Returns:
nil

Reimplemented from OLMap.


The documentation for this class was generated from the following file:
ObjectiveLibGenerated Sun Apr 22 15:13:37 2007, © 2004-2007 Will Mason
SourceForge.net Logo