PATH |
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.
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()
EmptyDictionary
shared instance instead. See Constants.
public NSDictionary( NSArray objectArray, NSArray keyArray)
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)
public NSDictionary( Object object, Object 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[])
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)
false
, throws an InvalidArgumentException if any key or value in dictionary is null
.
Static Methods
decodeObject
public static Object decodeObject(NSCoder coder)
See Also: NSCoding
Instance Methods
allKeys
public NSArray allKeys()
See Also: allValues, allKeysForObject
allKeysForObject
public NSArray allKeysForObject(Object anObject)
null
.
See Also: allKeys, keyEnumerator
allValues
public NSArray allValues()
See Also: allKeys, objectEnumerator
classForCoder
public Class classForCoder()
clone
public Object clone()
count
public int count()
encodeWithCoder
public void encodeWithCoder(NSCoder coder)
equals
public boolean equals(Object anObject)
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()
hashtable
public java.util.Hashtable hashtable()
immutableClone
public NSDictionary immutableClone()
isEqualToDictionary
public boolean isEqualToDictionary(NSDictionary otherDictionary)
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()
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()
See Also: objectsNoCopy
mutableClone
public NSMutableDictionary mutableClone()
objectEnumerator
public java.util.Enumeration objectEnumerator()
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)
null
if no value is associated with aKey.
objectsForKeys
public NSArray objectsForKeys( NSArray keys, Object anObject)
objectsNoCopy
protected Object[] objectsNoCopy()
See Also: keysNoCopy
takeValueForKey
public void takeValueForKey( Object object, String key)
takeValueForKeyPath
public void takeValueForKeyPath( Object object, String key)
toString
public String toString()
valueForKey
public Object valueForKey(String key)
valueForKeyPath
public Object valueForKeyPath(String key)
© 2001 Apple Computer, Inc. (Last Published April 17, 2001)