NSDictionary

Inherits from:
Object

Implements:
Cloneable
java.io.Serializable
NSCoding
NSKeyValueCoding
NSKeyValueCodingAdditions

Package:
com.webobjects.foundation

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 class 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. These methods also add each key object directly to the dictionary, which means that you must ensure that the keys do not change. If you expect your keys to change for any reason, you should make copies of the keys and add the copies to the dictionary.

Table 0-6 describes the NSDictionary methods that provide the basis for all NSDictionary's other methods; that is, all other methods are implemented in terms of these four. If you create a subclass of NSDictionary, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

**Table 0-6 NSDictionary's Base API**
Method	Description
count	Returns the number of entries in the dictionary.
objectForKey	Returns the value associated with a given key.
keysNoCopy	Returns a natural language array containing the keys in the dictionary.
objectsNoCopy	Returns a natural language array containing the objects 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.

Constants

NSDictionary provides the following constant as a convenience; you can use it when you need an empty dictionary.

Constant	Type	Description
`EmptyDictionary`	NSDictionary	A shared NSDictionary instance containing no entries.

Interfaces Implemented

Cloneable

java.io.Serializable

NSCoding

classForCoder
decodeObject
encodeWithCoder

NSKeyValueCoding

takeValueForKey
valueForKey

NSKeyValueCodingAdditions

takeValueForKeyPath
valueForKeyPath

Method Types

Constructors

NSDictionary

Accessing keys and values

allKeys
allKeysForObject
allValues
isEqualToDictionary
keyEnumerator
keysNoCopy
objectEnumerator
objectForKey
objectsForKeys
objectsNoCopy

Counting entries

count

Creating hash tables

hashtable

Copying dictionaries

immutableClone
mutableClone

Methods inherited from Object

clone
equals
hashCode
toString

Constructors

NSDictionary

public NSDictionary()

Creates an empty dictionary. To improve performance, use the EmptyDictionary shared instance instead. See Constants.

public NSDictionary( NSArray objectArray, NSArray keyArray)

Creates a NSDictionary with entries from the contents of the keyArray and objectArray NSArrays. This method steps through objectArray and keyArray, creating entries in the new dictionary as it goes. Each key object and its corresponding value object is added directly to the dictionary. An InvalidArgumentException is thrown if the objectArray and keyArray do not have the same number of elements.

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

public NSDictionary(NSDictionary dictionary)

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

public NSDictionary( Object object, Object key)

Creates a dictionary containing a single object object for a single key key.

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

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

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

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

public NSDictionary( java.util.Dictionary dictionary, boolean ignoreNull)

Creates a dictionary containing the keys and values found in dictionary. If ignoreNull is false, throws an InvalidArgumentException if any key or value in dictionary is null.

Static Methods

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSDictionary from the data in coder.

See Also: NSCoding

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 equals 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

classForCoder

public Class classForCoder()

Conformance to NSCoding. See the method description of classForCoder in the interface specification for NSCoding.

clone

public Object clone()

Returns a copy (an NSDictionary object) of the receiver. Since NSDictionaries are immutable, there's no need to make an actual copy.

count

public int count()

Returns the number of entries in the dictionary.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Conformance to NSCoding. See the method description of encodeWithCoder in the interface specification for NSCoding.

equals

public boolean equals(Object anObject)

Compares the receiving dictionary to anObject. If anObject is an NSDictionary and the contents of anObject 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.

hashCode

public int hashCode()

Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.

hashtable

public java.util.Hashtable hashtable()

Returns a java.util.Hashtable containing the receiver's entries.

immutableClone

public NSDictionary immutableClone()

Returns an immutable copy (an NSDictionary) of the receiver. Since NSDictionaries are immutable, there's no need to make an actual copy.

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.

keyEnumerator

public java.util.Enumeration keyEnumerator()

Returns an Enumeration 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

keysNoCopy

protected Object[] keysNoCopy()

Returns an 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. This method is similar to allKeys except the keys are not copied.

See Also: objectsNoCopy

mutableClone

public NSMutableDictionary mutableClone()

Returns a mutable dictionary (an NSMutableDictionary) with the same keys and value objects as the receiver.

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

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.

objectsNoCopy

protected Object[] objectsNoCopy()

See Also: keysNoCopy

takeValueForKey

public void takeValueForKey( Object object, String key)

Conformance to NSKeyValueCoding. Since NSDictionaries are immutable, this method simply throws an IllegalStateException.

takeValueForKeyPath

public void takeValueForKeyPath( Object object, String key)

Conformance to NSKeyValueCodingAdditions. See the method specification of takeValueForKeyPath in the interface specification for NSKeyValueCodingAdditions.

toString

public String toString()

Returns a string representation of the receiver containing a string representation of each key-value pair.

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding. Equivalent to objectForKey.

valueForKeyPath

public Object valueForKeyPath(String key)

Conformance to NSKeyValueCodingAdditions. If the key exists in the dictionary, this method returns the corresponding object in the dictionary by invoking objectForKey. Otherwise it invokes the default implementation of valueForKeyPath. See the method specification of valueForKeyPath in the interface specification for NSKeyValueCodingAdditions.