# dictnary Specification Sheet

Portable Object Compiler (c) 1997,98. All Rights Reserved.

# 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, notify an error.

### 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.