PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSDictionary


Inherits from:
NSObject
Package:
com.apple.yellow.foundation

Class at a Glance


An NSDictionary object stores an immutable set of entries.

Principal Attributes


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.


Class Description


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.)

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 which 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 afterwards. 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 in this cluster 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 non-primitive methods provide convenient ways of accessing multiple entries at once.




Method Types


Constructors
NSDictionary
Counting entries
count
Accessing keys and values
allKeys
allKeysForObject
allValues
keyEnumerator
objectEnumerator
objectForKey
objectsForKeys


Constructors



NSDictionary

public NSDictionary()

Creates and returns an empty dictionary.

public NSDictionary( Object[] objects, Object[] keys)

Creates a dictionary with entries constructed from the contents of the objects and keys arrays. This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. Each value object is added directly to the dictionary. Each key object is copied, and the copy is added to the dictionary. An InvalidArgumentException is thrown if the objects and keys arrays do not have the same number of elements.

public NSDictionary( Object anObject, Object aKey)

Creates a dictionary containing a single object, anObject, for a single key, aKey.

public NSDictionary(NSDictionary otherDictionary)

Creates a dictionary containing the keys and values found in otherDictionary.




Instance Methods



allKeys

public NSArray allKeys()

Returns a new array containing the dictionary's keys or an empty array if the dictionary has no entries. The order of the elements in the array isn't defined.

See Also: allValues, allKeysForObject



allKeysForObject

public NSArray allKeysForObject(Object anObject)

Finds all occurrences of the value anObject in the dictionary and returns a new array with the corresponding keys. Each object in the dictionary is sent an isEqual: message to determine if it's equal to anObject. If no object matching anObject is found, this method returns null.

See Also: allKeys, keyEnumerator



allValues

public NSArray allValues()

Returns a new array containing the dictionary's values, or an empty array if the dictionary has no entries. The order of the values in the array isn't defined.

See Also: allKeys, objectEnumerator



count

public int count()

Returns the number of entries in the dictionary.



isEqualToDictionary

public boolean isEqualToDictionary(NSDictionary otherDictionary)

Compares the receiving dictionary to otherDictionary. 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

public java.util.Enumeration keyEnumerator()

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

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

public java.util.Enumeration objectEnumerator()

Returns an enumerator object that lets you access each value in the dictionary:

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

public Object objectForKey(Object akey)

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

See Also: allKeys, allValues



objectsForKeys

public NSArray objectsForKeys( NSArray keys, Object anObject)

Returns the set of objects from the receiver that correspond to the specified keys as an NSArray. 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.




Table of Contents