NSDictionary

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.

Exceptions

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

• + (id)allocWithZone:(NSZone *)zone Creates and returns an uninitialized NSDictionary in zone.
• + (id)dictionary Creates and returns an empty NSDictionary.
• + (id)dictionaryWithContentsOfFile:(NSString *)path Creates and returns an NSDictionary from the keys and values found in the file specified by path.
• + (id)dictionaryWithObjects:(NSArray *)objects Creates and returns an NSDictionary that associates forKeys:(NSArray *)keys objects from the objects array with keys from the keys array. Keys must be strings. Raises NSInvalidArgumentException if the number of objects is not equal to the number of keys.
• + (id)dictionaryWithObjects:(id *)objects Creates and returns an NSDictionary containing count forKeys:(id *)keys objects from the objects array. The objects are count:(unsigned int)count associated with count keys taken from the keys array.
• + (id)dictionaryWithObjectsAndKeys:(id)firstObject, ... Creates and returns an NSDictionary that associates objects and keys from the argument list. The list must be in form: object1, key1, object2, key2, ..., nil. Raises NSInvalidArgumentException if any of the keys are nil, or if any of the keys are not of the NSString class.
• - (id)initWithContentsOfFile:(NSString *)path Initializes a newly allocated NSDictionary using the keys and values found in filename.
• - (id)initWithDictionary:(NSDictionary *)dictionary Initializes a newly allocated NSDictionary by placing in it the keys and values contained in otherDictionary.
• - (id)initWithObjectsAndKeys:(id)firstObject,... Initializes a newly allocated NSDictionary by placing in it the objects and keys from the argument list. The list must be in form: object1, key1, object2, key2, ..., nil. Raises NSInvalidArgumentException if any of the keys are nil, or if any of the keys are not of the NSString class.
• - (id)initWithObjects:(NSArray *)objects Initializes a newly allocated NSDictionary by associating forKeys:(NSArray *)keys objects from the objects array with keys from the keys array. Keys must be strings. Raises NSInvalidArgumentException if the number of objects is not equal to the number of keys.
• - (id)initWithObjects:(id *)objects Initializes a newly allocated NSDictionary by associating forKeys:(id *)keys count objects from the objects array with an equal count:(unsigned)count number of keys from the keys array. Raises NSInvalidArgumentException if any of the objects or keys are nil.

• - (NSArray *)allKeys Returns an NSArray containing the receiver's keys or an empty array if the receiver has no entries.
• - (NSArray *)allKeysForObject:(id)object Finds all occurrences of the value anObject in the receiver and returns an array with the corresponding keys.
• - (NSArray *)allValues Returns an NSArray containing the dictionary's values, or an empty array if the dictionary has no entries.
• - (NSEnumerator *)keyEnumerator Returns an NSEnumerator that lets you access each of the receiver's keys.
• - (NSEnumerator *)objectEnumerator Returns an NSEnumerator that lets you access each the receiver's values.
• - (id)objectForKey:(id)aKey Returns an entry's value given its key, or nil if no value is associated with aKey.

• - (unsigned)count Returns the number of entries in the receiver.

• - (BOOL)isEqualToDictionary:(NSDictionary *)other Compares the receiver to otherDictionary. If the contents of otherDictionary are equal to the contents of the receiver, this method returns YES. If not, it returns NO.

• - (NSString *)description Returns a string that represents the contents of the receiver.
• - (NSString *)descriptionInStringsFileFormat Returns a string that represents the contents of the receiver. Key-value pairs are represented in a appropriate for use in .strings files
• - (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary Returns a string representation of the NSDictionary object. Included are the key and values that represent the locale data from localeDictionary.
• - (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary indent:(unsigned int)level Returns a string representation of the NSDictionary object. Included are the key and values that represent the locale data from localeDictionary. Elements are indented from the left margin by level + 1 multiples of four spaces, to make the output more readable.
• - (BOOL)writeToFile:(NSString *)path Writes a textual description of the contents of the atomically:(BOOL)useAuxiliaryFile receiver to filename. If useAuxiliaryFile is YES, the data is written to a backup file and then, assuming no errors occur, the backup file is renamed to the intended file name.