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

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)