Name

Map -- collection of associations from key objects to member objects

Synopsis

//
// Map -- collection of associations from key objects to member objects
//
@deftype Map <KeyedCollection, CREATABLE>
CREATING
- (void)	setKeyType: aDataType;
- (void)	setKeySlot: (int)byteOffset;
USING
-	        getKeyType;
- (int)		getKeySlot;

- (BOOL)	at: aKey insert: anObject;
- (BOOL)	at: aKey insert: anObject setIndex: anIndex;
-		at: aKey replace: anObject;

- (BOOL)	insertGroup: aKey;

-		createIndex: aZone setKey: aKey;
@end

@deftype MapIndex <KeyedIndex>
-		getKey;
-		setKey: aKey;

-		get: (id *)key;
-		next: (id *)key;
-		prev: (id *)key;

-		replaceKey: aKey;
end

Description

Map is a subtype of KeyedCollection in which the key value associated with each member is independent of the member itself. Whenever a new member is added to the collection, a key value to be associated with the member must be supplied also. A Map defines a mapping from key values to member values.

Inherited behavior

For the Map type, key values are independent of the member values with which they are associated. Map defines two additional options to document information about its key values. Map also defines its own messages to distinguish the key value from member value in any operation which involves both.

@deftype Map <KeyedCollection, CREATABLE>

Create-time options

CREATING
- (void)	setKeyType: aDataType;
- (void)	setKeySlot: (int)byteOffset;
USING
-	        getKeyType;
- (int)		getKeySlot;
(..None of these options is currently implemented.)

Map behavior

- (BOOL)	at: aKey insert: anObject;
- (BOOL)	at: aKey insert: anObject setIndex: anIndex;

-		at: aKey replace: anObject;
at:insert: inserts an entry into a Map containing the key and member values given as its arguments. It returns true if the key was not previously contained in the collection. If the key was already present, the action of the message depends on the value in effect for the DuplicatesOption. With default options, the attempt to insert a duplicate key is simply rejected and false is returned.

at:insert:setIndex: is similar to at:insert:, except that the index passed as the final argument is repositioned to the member just inserted. If further operations are required on the entry in a map that was just inserted, an index provides faster repeated access to this entry than a message involving further key comparison, such as at:, would require. (.. This message is not currently implemented.)

at:replace replaces an existing member value associated with a key value by a new value given as its final argument. The message returns the member value which was formerly associated with the key value. The message returns nil if more than one member is present with the same key.

-		createIndex: aZone setKey: aKey;
(.. This message is not currently implemented. It will eventually give a fast way to create an index already positioned at an entry with a particular key value.)

MapIndex behavior

-		getKey;
-		setKey: aKey;
The getKey message returns the key value associated with the current location of the index. It returns nil if the index is not currently positioned at a member. The setKey: messages repositions the index to an entry having a key value that matches its argument. If there is more than one entry matching this key value, the index is positioned to the first entry that matches.

-		get: (id *)key;
-		next: (id *)key;
-		prev: (id *)key;
These messages are similar to those defined by the Index supertype, except that they combine the return of a member value with an output value for an associated key value. In each case, the key value is passed as an (id *) output argument.

-		replaceKey: aKey;
(.. This message is not currently implemented.)

replaceKey: replaces a key value with another key value that still compares equal to a key value already present. It may be used to replace an allocation of one object, already contained in a Map, by a different object allocation. replaceKey: returns nil if no existing key value matches its key value argument; otherwise it returns the key value which was replaced by its argument.

Roger Burkhart <rmb@santafe.edu>
Last modified: