View source for Objective-C Dictionary Objects

Objective-C Dictionary Object classes allow data to be stored and managed in the form of key-value pairs where both the key and the value are objects. In this chapter of [[Objective-C 2.0 Essentials]] we will look at how to create, initialize and work with dictionary objects in Objective-C.

== What are Dictionary Objects? ==

In the previous chapter we looked at using array objects to store collections of objects. Dictionary objects perform a similar purpose except each object stored in the dictionary has associated with it a unique key (to be precise, the key is unique to the particular dictionary object). The unique key can be of any object type though to be useful they are typically string objects.

Objective-C dictionary objects are created using the NSDictionary and NSMutableDictionary classes. NSDictionary based objects are immutable (in other words once they have been created and initialized their contents cannot be modified). Mutable dictionaries are instantiated from the NSMutableDictionary class and may be modified after creation and initialization.

== Creating Dictionary Objects ==

An empty, immutable dictionary object may be created as follows:

<pre>
NSDictionary *bookListing = [NSDictionary dictionary];
</pre>

Similarly, an empty mutable dictionary may be created as follows:

<pre>
NSMutableDictionary *bookListing = [NSMutableDictionary dictionary];
</pre>

== Initializing and Adding Entries to a Dictionary Object ==

Each key-value pair contained within a dictionary is referred to as an entry. Once a relationship between a key and a value has been estabilshed that relationship cannot subsequently be modified.

New entries are added to a dictionary using the ''''setObject'' instance method. This methods takes as its arguments an object and a corresponding key:

<pre>
NSMutableDictionary *bookListing = [NSMutableDictionary dictionary];

[bookListing setObject: @"Wind in the Willows"  forKey: @"100-432112"];
[bookListing setObject: @"Tale of Two Cities " forKey:  @"200-532874"];
[bookListing setObject: @"Sense and Sensibility" forKey:  @"202-546549"];
[bookListing setObject: @"Shutter Island" forKey: @"104-109834"];
</pre>

In the above example, the bookListing dictionary is initialized with four book names with corresponding reference codes to act as keys. 

It is also possible to create and initialize a dictionary with a number of key-value pairs using the ''dictionaryWithObjectsAndKeys'' class method. For example, an alternative to the above code is as follows:

<pre>
NSDictionary *bookListing = [NSDictionary dictionaryWithObjectsAndKeys: @"Wind in the Willows", @"100-432112", @"Tale of Two Cities ", @"200-532874", @"Sense and Sensibility", @"202-546549", @"Shutter Island", @"104-109834", nil];
</pre>

Dictionaries may also be initialized using keys and values contained in arrays using the :

<pre>        
NSArray *objectsArray = [NSArray arrayWithObjects: @"Wind in the Willows", @"Tale of Two Cities ", @"Sense and Sensibility", @"Shutter Island", nil];
NSArray *keysArray = [NSArray arrayWithObjects: @"100-432112", @"200-532874", @"202-546549", @"104-109834", nil];

NSDictionary *bookListing = [[NSDictionary alloc] initWithObjects: objectsArray forKeys: keysArray];
</pre>

== Getting an Entry Count ==

A count of the number of entries in a dictionary can be obtained using the ''count'' instance methods:

<pre>
NSMutableDictionary *bookListing = [NSMutableDictionary dictionary];

int count;

[bookListing setObject: @"Wind in the Willows"  forKey: @"100-432112"];
[bookListing setObject: @"Tale of Two Cities " forKey:  @"200-532874"];
[bookListing setObject: @"Sense and Sensibility" forKey:  @"202-546549"];
[bookListing setObject: @"Shutter Island" forKey: @"104-109834"];

NSLog (@"Number of books in dictionary = %i", [bookListing count]);
</pre>


== Accessing Dictionary Entries ==

Dictionary entries are accessed by reference the key corresponding to the required entry via the ''objectForKey'' method. For example:

<pre>
NSLog ( @"100-432112 = %@", [bookListing objectForKey: @"100-432112"]);
NSLog ( @"200-532874 = %@", [bookListing objectForKey: @"200-532874"]);
NSLog ( @"202-546549 = %@", [bookListing objectForKey: @"202-546549"]);
NSLog ( @"104-109834 = %@", [bookListing objectForKey: @"104-109834"]);
</pre>

When combined with the previous code and executed, we would expect to see the following output:

<pre>
100-432112 = Wind in the Willows
200-532874 = Tale of Two Cities 
202-546549 = Sense and Sensibility
104-109834 = Shutter Island
</pre>

== Removing Entries from a Dictionary Object ===

Specific dictionary entries may be removed by referencing the key as an argument to the ''removeObjectForKey'' method. For example, to remove the book entry for "Shutter Island" we would write the following code:

<pre>
[bookListing removeObjectForKey: @"104-109834"];
</pre>

All entries in a dictionary may be removed using the ''removeAllObjects'' instance method:

<pre>
[bookListing removeAllObjects];
</pre>