Next Page > Hide TOC

NSDictionary

Class at a Glance

An NSDictionary object stores an immutable set of entries.

Principal Attributes

• A count of the number of entries in the dictionary

• The set of keys contained in the dictionary

• The objects that correspond to the keys in the dictionary

Creation

NSDictionary

Creates a new dictionary.

Commonly Used Methods

count

Returns the number of objects currently in the dictionary.

objectForKey

Returns the object that corresponds to the specified key.

keyEnumerator

Returns an enumerator object that lets you access each key in the dictionary.

Overview

The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. Use this class or its subclass NSMutableDictionary when you need a convenient and efficient way to retrieve data associated with an arbitrary key. (For convenience, we use the term dictionary to refer to any instance of one of these classes without specifying its exact class membership.)

The mutable subclass of NSDictionary is NSMutableDictionary.

A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key and a second object that is that key’s value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by equals).

An instance of NSDictionary is an immutable dictionary: you establish its entries when it’s created and cannot modify them afterward. An instance of NSMutableDictionary is a mutable dictionary: you can add or delete entries at any time, and the object automatically allocates memory as needed.

Internally, a dictionary uses a hash table to organize its storage and to provide rapid access to a value given the corresponding key. However, the methods defined insulate you from the complexities of working with hash tables, hashing functions, or the hashed value of keys. The methods described below take keys directly, not their hashed form.

Methods that add entries to dictionaries—whether during construction (for all dictionaries) or modification (for mutable dictionaries)—add each value object to the dictionary directly, but copy each key argument and add the copy to the dictionary.

NSDictionary’s three primitive methods—count, objectForKey, and keyEnumerator—provide the basis for all of the other methods in its interface. The count method returns the number of entries in the dictionary. objectForKey returns the value associated with a given key. keyEnumerator returns an object that lets you iterate through each of the keys in the dictionary.

The other methods declared here operate by invoking one or more of these primitives. The nonprimitive methods provide convenient ways of accessing multiple entries at once.

Tasks

Constructors

• NSDictionary

Counting Entries

• count

Comparing Dictionaries

• isEqualToDictionary

Accessing Keys and Values

• allKeys
• allKeysForObject
• allValues
• keyEnumerator
• objectEnumerator
• objectForKey
• objectsForKeys

Instance Methods

allKeys

Returns a new array containing the receiver’s keys or an empty array if the receiver has no entries.

public NSArray allKeys()

Discussion

The order of the elements in the array isn’t defined.

See Also

• allValues
• allKeysForObject

allKeysForObject

Finds all occurrences of the value anObject in the receiver and returns a new array with the corresponding keys.

public NSArray allKeysForObject(Object anObject)

Discussion

Each object in the receiver is sent an equals message to determine if it’s equal to anObject. If no object matching anObject is found, this method returns an empty array.

See Also

• allKeys
• keyEnumerator

allValues

Returns a new array containing the receiver’s values, or an empty array if the receiver has no entries.

public NSArray allValues()

Discussion

The order of the values in the array isn’t defined.

See Also

• allKeys
• objectEnumerator

count

Returns the number of entries in the receiver.

public int count()

isEqualToDictionary

Compares the receiving dictionary to otherDictionary.

public boolean isEqualToDictionary(NSDictionary otherDictionary)

Discussion

If the contents of otherDictionary are equal to the contents of the receiver, this method returns true. If not, it returns false.

Two dictionaries have equal contents if they each hold the same number of entries and, for a given key, the corresponding value objects in each dictionary satisfy the equals test.

See Also

• equals (NSObject)

keyEnumerator

Returns an enumerator object that lets you access each key in the receiver.

public java.util.Enumeration keyEnumerator()

Discussion

java.util.Enumeration enumerator = myDict.keyEnumerator();

while (enumerator.hasMoreElements()) {{

    Object anObject = enumerator.nextElement();

    /* code to act on each element */

}

When this method is used with mutable subclasses of NSDictionary, your code shouldn’t modify the entries during enumeration. If you intend to modify the entries, use the allKeys method to create a “snapshot” of the dictionary’s keys. Then use this snapshot to traverse the entries, modifying them along the way.

Note that the objectEnumerator method provides a convenient way to access each value in the dictionary.

See Also

• allKeys
• allKeysForObject
• objectEnumerator
• nextElement (NSEnumerator)

objectEnumerator

Returns an enumerator object that lets you access each value in the receiver.

public java.util.Enumeration objectEnumerator()

Discussion

java.util.Enumeration enumerator = myDict.objectEnumerator();

while (enumerator.hasMoreElements()) {{

    Object anObject = enumerator.nextElement();

    /* code to act on each element */

}

When this method is used with mutable subclasses of NSDictionary, your code shouldn’t modify the entries during enumeration. If you intend to modify the entries, use the allValues method to create a “snapshot” of the dictionary’s values. Work from this snapshot to modify the values.

See Also

• keyEnumerator
• nextElement (NSEnumerator)

objectForKey

Returns an entry’s value given its key, or null if no value is associated with aKey.

public Object objectForKey(Object akey)

See Also

• allKeys
• allValues

objectsForKeys

Returns the set of objects from the receiver that corresponds to the specified keys as an NSArray.

public NSArray objectsForKeys(NSArray keys, Object anObject)

Discussion

The objects in the returned array and the keys array have a one-for-one correspondence, so that the nth object in the returned array corresponds to the nth key in keys. If an object isn’t found in the receiver to correspond to a given key, the marker object, specified by anObject, is placed in the corresponding element of the returned array.

Next Page > Hide TOC