---
name: "Dictionary"
section: "3"
platform: "linux"
package: "objc-poc"
version: "3.1.3-2"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/Dictionary"
---

# Dictionary(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, 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.