dictnary(3)

Dictionary

Inherits from: Object

Class Description

Dictionaries (instances of the Dictionary class) are key-value tables : to each key object, a value object is associated. The key can then be used to access the corresponding value. There are a few special provisions for tables with String instances as keys.

Method types

Creation
    * new
    * copy
    * deepCopy
    * emptyYourself
    * freeContents
    * freeAll
    * free

Interrogation
    * size
    * isEmpty
    * includesKey:

Comparing
    * hash
    * isEqual:

Indexed Access
    * atKey:
    * atKey:ifAbsent:
    * atKeySTR:
    * atKey:put:
    * atKeySTR:put:
    * eachKey
    * eachValue

Adding and Removing
    * removeKey:
    * removeKey:ifAbsent:

Blocks
    * keysDo:

Printing
    * printOn:

Methods

new
    + new

Returns a new empty dictionary.

copy
    - copy

Returns a new copy of the dictionary.

deepCopy
    - deepCopy

Returns a new copy of the dictionary. The members in the new dictionary are deep copies of the members in the original dictionary.

emptyYourself
    - emptyYourself

Removes all the keys and values of the dictionary (without freeing them). Returns the receiver.

freeContents
    - freeContents

This method is, in the case of the Dictionary class, equivalent to emptyYourself . Note that for the sake of Stepstone ICpak101 compatibility, this method does not free keys and values. Use freeAll for that.

freeAll
    - freeAll

This method frees all the keys and values in the dictionary, without freeing the dictionary itself. Returns the dictionary.

Note: This method is ObjectPak specific.

free
    - free

Frees the dictionary, but not its contents. Returns nil . Do :
    aDic = [[aDic freeAll] free];

if you want to free the dictionary and its contents.

size
    - ( unsigned ) size

Returns the number of key-value associations in the dictionary.

isEmpty
    - ( BOOL ) isEmpty

Whether the number of associations in the dictionary is equal to zero.

includesKey:
    - ( BOOL ) includesKey : aKey

Returns YES if there is an association with key matching aKey .

hash
    - ( unsigned ) hash

Returns a hash value based on the receiver's address and the results of sending the hash message to the contents.

isEqual:
    - ( BOOL ) isEqual : aDic

Returns YES if aDic is a dictionary, and if its keys and values respond affirmatively to the message isEqual: when compared to the corresponding objects of the receiver's contents.

atKey:
    - atKey : aKey

Returns the value of the association matching aKey . Returns nil if the association is not found.

atKey:ifAbsent:
    - atKey : aKey ifAbsent : exceptionBlock

Returns the value of the association matching aKey . Evaluates exceptionBlock and returns its return value, if the association is not found.

atKeySTR:
    - atKeySTR :(STR) strKey

Returns the value of the association matching strKey . Returns nil if the association is not found.

atKey:put:
    - atKey : aKey put : anObject

Associates aKey to anObject . Adds the objects to the dictionary. If aKey was already in the dictionary, makes anObject the value for this key and returns the old value. Otherwise returns nil .

atKeySTR:put:
    - atKeySTR :(STR) strKey put : anObject

Associates strKey to anObject . Adds the objects to the dictionary. If strKey was already in the dictionary, makes anObject the value for this key and returns the old value. Otherwise returns nil .

eachKey
    - eachKey

Returns a sequence of the key objects in the dictionary.
    keys = [aDic eachKey];
    while ((aKey = [aSeq next])) {
    /* do something */
    }
    keys = [keys free];

See also: eachValue

eachValue
    - eachValue

Returns a sequence of the value objects in the dictionary.
    keys = [aDic eachKey];
    values = [aDic eachValue];
    while ((aKey = [aSeq next])) {
    aValue = [values next];
    /* do something */
    }
    keys = [keys free];
    values = [values free];

See also: eachKey

removeKey:
    - removeKey : key

Remove key from the receiver and return value for given key . If key is not in the receiver, signals the NotFound exception.

removeKey:ifAbsent:
    - removeKey : key ifAbsent : aBlock

Remove key (and its associated value) from the receiver. If key is not in the receiver, answers the result of evaluating aBlock . Otherwise, answers the value externally named by key .

keysDo:
    - keysDo : aBlock

The keysDo: message iterates through all the Dictionary elements, running a one-argument block of code specified by the aBlock argument with the argument set to the key of each assocation.

printOn:
    - printOn :(IOD) aFile

Prints a comma separated list of the key-value pairs by sending each individual object a printOn: message. Returns the receiver.