Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


Inherits From: NSObject

Conforms To: NSCoding, NSCopying, NSMutableCopying NSObject (NSObject)

Declared In: Foundation/NSDictionary.h

Class Description

The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. You use this class when you need a convenient and efficient way to retrieve data associated with an arbitrary key.

A key-value pair within an NSDictionary is called an entry. Each entry consists of an string object that represents the key and another object (of any class) that is that key's value. You establish the entries when the NSDictionary is created, and thereafter the entries can't be modified. (The complementary class NSMutableDictionary defines objects that manage modifiable collections of entries. See the NSMutableDictionary class specification for more information.)

Internally, an NSDictionary uses a hash table to organize its storage and to provide rapid access to a value given the corresponding key. However, the methods defined for this class insulate you from the complexities of working with hash tables, hashing functions, or the hashed value of keys. These methods take key values directly, not their hashed form.

Generally, you instantiate an NSDictionary by sending one of the dictionary... messages to the class object. These methods return an NSDictionary containing the associations specified as arguments to the method. Each key argument is copied and the copy is added to the NSDictionary. Each corresponding value object receives a retain message to ensure that it won't be deallocated prematurely.

NSDictionary's three primitive methodscount and objectForKey: and keyEnumeratorprovide the basis for all the other methods in its interface. The count method returns the number of entries in the object, objectForKey: returns the value associated with the given key, and keyEnumerator returns an object that lets you step through entries in the dictionary.

The other methods declared here operate by invoking one or more of these primitives. The non-primitive methods provide convenient ways of accessing multiple entries at once. The description... methods and the writeToFile:atomically: method cause an NSDictionary to generate a description of itself and store it in a string object or a file.


NSSet implements the encodeWithCoder: method, which raises NSInternalInconsistencyException if the number of objects enumerated for encoding turns out to be unequal to the number of objects in the set.

Creating and Initializing an NSDictionary

Accessing Keys and Values

Counting Entries

Comparing Dictionaries

Storing Dictionaries