WebObjects 5.2

com.webobjects.foundation
Class NSDictionary

java.lang.Object
  |
  +--com.webobjects.foundation.NSDictionary
All Implemented Interfaces:
Cloneable, NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Serializable
Direct Known Subclasses:
NSMutableDictionary

public class NSDictionary
extends Object
implements Cloneable, Serializable, NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions

The NSDictionary class declares an API for objects that manage immutable associations of keys and values. This class, or its subclass NSMutableDictionary, is used when a convenient and efficient way is needed 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 is 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.

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. This 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 or otherwise guarantee that the keys will not change with respect to either the equals or hashCode methods. java.lang.String objects are immutable and make good keys.

The NSDictionary methods that provide the basis for all NSDictionary's other 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.

NSDictionary's Base API
Method Description
countReturns the number of entries in the dictionary.
objectForKeyReturns the value associated with a given key.
keysNoCopyReturns a natural language array containing the keys in the dictionary.
objectsNoCopyReturns 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.

See Also:
Map, HashMap, Hashtable, count(), objectForKey(java.lang.Object), Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSCoding
NSCoding.Support
 
Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding
NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor
 
Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions
NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility
 
Field Summary
static NSDictionary EmptyDictionary
          A NSDictionary instance containing no entries which may be shared.
 
Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding
NullValue
 
Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
KeyPathSeparator
 
Constructor Summary
NSDictionary()
          Creates an empty dictionary.
NSDictionary(Dictionary dictionary, boolean ignoreNull)
          Creates a dictionary containing the keys and values found in dictionary.
NSDictionary(NSArray objects, NSArray keys)
          Creates an NSDictionary with entries from the contents of the keys and objects NSArrays.
NSDictionary(NSDictionary otherDictionary)
          Creates a dictionary containing the keys and values found in otherDictionary.
NSDictionary(Object[] objects, Object[] keys)
          Creates an NSDictionary with entries from the contents of the keys and objects arrays.
NSDictionary(Object object, Object key)
          Creates a dictionary containing a single object object for a single key key.
 
Method Summary
 NSArray allKeys()
          The order of the elements in the returned array is not defined.
 NSArray allKeysForObject(Object object)
          Finds all occurrences of the value object in the dictionary and returns a new array with the corresponding keys.
 NSArray allValues()
          The order of the values in the array is not defined.
 Class classForCoder()
          Conformance to NSCoding.
 Object clone()
          Returns a copy (an NSDictionary object) of this dictionary.
 int count()
          This method returns a count of the number of key-value pairs.
static Object decodeObject(NSCoder coder)
          Creates an NSDictionary from the data in coder.
 void encodeWithCoder(NSCoder coder)
          Encodes the receiver using coder.
 boolean equals(Object object)
          Compares this dictionary to object.
 int hashCode()
           
 Hashtable hashtable()
           
 NSDictionary immutableClone()
          Since NSDictionaries are immutable, there's no need to make an actual copy.
 boolean isEqualToDictionary(NSDictionary otherDictionary)
          Provided for backward compatibility.
 Enumeration keyEnumerator()
          This method provides a java.util.Enumeration which can be used to access each key in this dictionary.
protected  Object[] keysNoCopy()
          This method should only be used by subclasses.
 NSMutableDictionary mutableClone()
           
 Enumeration objectEnumerator()
          This method provides a java.util.Enumeration which can be used to access each value in this dictionary.
 Object objectForKey(Object key)
          This method returns the Object associated with key
 NSArray objectsForKeys(NSArray keys, Object notFoundMarker)
          This method takes a subset of the dictionary as specified by the array of keys and returns an array of the value objects associated with each of the keys.
protected  Object[] objectsNoCopy()
          This method should only be used by subclasses.
 void takeValueForKey(Object value, String key)
          Conformance to NSKeyValueCoding.
 void takeValueForKeyPath(Object value, String keyPath)
          Conformance to NSKeyValueCodingAdditions.
 String toString()
           
 Object valueForKey(String key)
          Conformance to NSKeyValueCoding.
 Object valueForKeyPath(String keyPath)
          Conformance to NSKeyValueCodingAdditions.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EmptyDictionary

public static final NSDictionary EmptyDictionary
A NSDictionary instance containing no entries which may be shared.
Constructor Detail

NSDictionary

public NSDictionary()
Creates an empty dictionary. To improve performance, the EmptyDictionary constant should be used instead.
See Also:
EmptyDictionary

NSDictionary

public NSDictionary(Object object,
                    Object key)
Creates a dictionary containing a single object object for a single key key. null is an illegal value for both object and 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.

Parameters:
object - object to be stored in the dictionary
key - key corresponding to the object to be stored in the dictionary

NSDictionary

public NSDictionary(Object[] objects,
                    Object[] keys)
Creates an 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. None of the objects are permitted to be null.

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.

Parameters:
objects - array of objects to be stored in the dictionary
keys - array of keys corresponding to the object to be stored in the dictionary
Throws:
java.lang.IllegalArgumentException - if the object array and the key array do not have the same size, or any element is null

NSDictionary

public NSDictionary(NSArray objects,
                    NSArray keys)
Creates an NSDictionary with entries from the contents of the keys and objects NSArrays. 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.

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.

Parameters:
objects - array of objects to be stored in the dictionary
keys - array of keys corresponding to the objects to be stored in the dictionary
Throws:
java.lang.IllegalArgumentException - if the object array and the key array do not have the same size

NSDictionary

public NSDictionary(NSDictionary otherDictionary)
Creates a dictionary containing the keys and values found in otherDictionary.
Parameters:
otherDictionary - the input dictionary from which the duplicate dictionary is to be created

NSDictionary

public NSDictionary(Dictionary dictionary,
                    boolean ignoreNull)
Creates a dictionary containing the keys and values found in dictionary. If ignoreNull is false, throws an IllegalArgumentException if any key or value in dictionary is null.
Parameters:
dictionary - the input dictionary from which the current dictionary is to be created
ignoreNull - true if null is to be allowed in the input fields.
Throws:
java.lang.IllegalArgumentException - when null is not allowed and a null is encountered
Method Detail

allKeys

public NSArray allKeys()
The order of the elements in the returned array is not defined.
Returns:
a new array containing the dictionary's keys or an empty array if the dictionary has no entries
See Also:
allValues(), allKeysForObject(java.lang.Object), keyEnumerator()

allKeysForObject

public NSArray allKeysForObject(Object object)
Finds all occurrences of the value object 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 is equalivalent to object. If no Object matching object is found, this method returns an empty array.
Parameters:
object - the search target in the dictionary
Returns:
an array with all the occurrences of keys associated with object
See Also:
allKeys(), keyEnumerator()

allValues

public NSArray allValues()
The order of the values in the array is not defined.
Returns:
a new array containing the dictionary's values, or an empty array if the dictionary has no entries
See Also:
allKeys(), objectEnumerator()

classForCoder

public Class classForCoder()
Conformance to NSCoding. See the method description of classForCoder in the interface specification for NSCoding.
Specified by:
classForCoder in interface NSCoding
Returns:
NSDictionary.class

clone

public Object clone()
Returns a copy (an NSDictionary object) of this dictionary. Since NSDictionaries are immutable, there's no need to make an actual copy.

Overrides:
clone in class Object
Returns:
this
See Also:
mutableClone(), immutableClone(), Object.clone()

count

public int count()
This method returns a count of the number of key-value pairs.
Returns:
the number of entries in the dictionary.

decodeObject

public static Object decodeObject(NSCoder coder)
Creates an NSDictionary from the data in coder.
Parameters:
coder - the input coder
Returns:
a dictionary with the data in the input array
See Also:
NSCoding

encodeWithCoder

public void encodeWithCoder(NSCoder coder)
Description copied from interface: NSCoding
Encodes the receiver using coder. Object type information along with an object's data is stored.
Specified by:
encodeWithCoder in interface NSCoding
Following copied from interface: com.webobjects.foundation.NSCoding
Parameters:
coder - an NSCoder object that will be used to encode object of classes that implement this interface
See Also:
NSCoder

equals

public boolean equals(Object object)
Compares this dictionary to object. If object is an instanceof NSDictionary and the contents of object are equal to these contents, 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 each key, the corresponding value objects in each dictionary satisfy the equals test.

Overrides:
equals in class Object
Parameters:
object - the object to compare this dictionary against
Returns:
true if this dictionary is equivalent to object, else false
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Overrides:
hashCode in class Object
Returns:
an appropriate hash code useful for storing the receiver in a hash-based data structure
See Also:
Object.hashCode()

hashtable

public Hashtable hashtable()
Returns:
a copy of this dictionary transformed into a java.util.Hashtable

immutableClone

public NSDictionary immutableClone()
Since NSDictionaries are immutable, there's no need to make an actual copy.
Returns:
an immutable copy of this dictionary
See Also:
mutableClone(), clone()

isEqualToDictionary

public boolean isEqualToDictionary(NSDictionary otherDictionary)
Provided for backward compatibility. Use equals instead.
Parameters:
otherDictionary - the dictionary to compare this one to
Returns:
true if both the input dictionary and the this dictionary are equivalent, else false
See Also:
equals(java.lang.Object)

keyEnumerator

public Enumeration keyEnumerator()
This method provides a java.util.Enumeration which can be used to access each key in this 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.

Returns:
a java.util.Enumeration object that lets you access each key in the dictionary
See Also:
allKeys(), allKeysForObject(java.lang.Object), objectEnumerator()

keysNoCopy

protected Object[] keysNoCopy()
This method should only be used by subclasses. The order of the values in the returned array is not defined. This method is similar to allKeys except the keys might not be copied.
Returns:
an array containing the dictionary's values, or an empty array if the dictionary has no entries
See Also:
objectsNoCopy(), allKeys()

mutableClone

public NSMutableDictionary mutableClone()
Returns:
a new NSMutableDictionary with the same keys and value objects as the receiver
See Also:
immutableClone(), clone()

objectEnumerator

public Enumeration objectEnumerator()
This method provides a java.util.Enumeration which can be used to access each value in this 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.

Returns:
an object that lets you access all the values in the dictionary
See Also:
keyEnumerator(), allValues()

objectForKey

public Object objectForKey(Object key)
This method returns the Object associated with key
Parameters:
key - the key to be searched for
Returns:
the value for key, or null if no value is associated with key
See Also:
allKeys(), allValues()

objectsForKeys

public NSArray objectsForKeys(NSArray keys,
                              Object notFoundMarker)
This method takes a subset of the dictionary as specified by the array of keys and returns an array of the value objects associated with each of the keys. 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 is not found in this dictionary for a corresponding key, the notFoundMarker Object is placed in that key's position in the resultant array.
Parameters:
keys - a subset of keys
notFoundMarker - a marker object indicating that the object corresponding to a key was not found
Returns:
an array of objects from this dictionary that correspond to each element of keys

objectsNoCopy

protected Object[] objectsNoCopy()
This method should only be used by subclasses. The order of the values in the array isn't defined. This method is similar to allValues except the objects might not be copied.
Returns:
an array containing the dictionary's values, or an empty array if the dictionary has no entries
See Also:
keysNoCopy(), allValues()

takeValueForKey

public void takeValueForKey(Object value,
                            String key)
Conformance to NSKeyValueCoding. Since NSDictionaries are immutable, this method simply throws an IllegalStateException.
Specified by:
takeValueForKey in interface NSKeyValueCoding
Parameters:
value - the input object
key - the key corresponding to the object
Throws:
java.lang.IllegalStateException -  
See Also:
NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String)

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)
Conformance to NSKeyValueCodingAdditions. Since NSDictionaries are immutable, this method simply throws an IllegalStateException.
Specified by:
takeValueForKeyPath in interface NSKeyValueCodingAdditions
Parameters:
value - the input object
keyPath - the path of the input object
Throws:
java.lang.IllegalStateException -  
See Also:
NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String)

toString

public String toString()
Overrides:
toString in class Object
Returns:
a string representation each key-value pair.

valueForKey

public Object valueForKey(String key)
Conformance to NSKeyValueCoding. This method is similar to objectForKey. It provides an entry's value given its key, or null if no value is associated with key.

Additionally, all dictionaries have the keys "allValues", "allKeys", and "count" defined, which provide a result identical to the invocation of the method of that name on this dictionary. If the dictionary contains an actual key which conflicts with these special keys, the real key trumps the computation. For example, if a dictionary has the key-value pair "count"-"dog" valueForKey will return "dog" instead of the result of the count method.

Specified by:
valueForKey in interface NSKeyValueCoding
Parameters:
key - the key to be searched for
Returns:
the value of the entry, or null if the key is not found
See Also:
objectForKey(java.lang.Object), NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String)

valueForKeyPath

public Object valueForKeyPath(String keyPath)
Conformance to NSKeyValueCodingAdditions. If the keyPath exists as a distinct key in the dictionary, this method returns the corresponding object in the dictionary by invoking objectForKey. Otherwise, it recursively invokes valueForKey for each segment of the keyPath on the result of the previous segment.
Specified by:
valueForKeyPath in interface NSKeyValueCodingAdditions
Parameters:
keyPath - the key path of the object
Returns:
the object corresponding to keypath
See Also:
objectForKey(java.lang.Object), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCoding.valueForKey(java.lang.String)

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.