WebObjects 5.4.2

com.webobjects.foundation
Class NSDictionary

java.lang.Object
  extended by com.webobjects.foundation.NSDictionary
All Implemented Interfaces:
NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Serializable, Cloneable, Map
Direct Known Subclasses:
NSMutableDictionary

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

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, NSDictionary._count, NSDictionary.objectForKey(java.lang.Object), Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding
NSCoding.Support
 
Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry
 
Field Summary
static boolean CheckForNull
          Convenience for the constructor methods
static NSDictionary EmptyDictionary
          A NSDictionary instance containing no entries which may be shared.
static boolean IgnoreNull
          Convenience for the constructor methods
 
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(Map map)
          Creates a dictionary containing the keys and values found in Map.
NSDictionary(Map map, boolean ignoreNull)
          Creates a dictionary containing the keys and values found in Map.
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.
 void clear()
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 Object clone()
          Returns a copy (an NSDictionary object) of this dictionary.
 boolean containsKey(Object key)
          NSDictionaries do not allow null keys which differs from the java.util.Map specification.
 boolean containsValue(Object value)
          NSDictionaries do not allow for null values which differs from the java.util.Map specification.
 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.
static NSDictionary emptyDictionary()
          Returns the empty NSDictionary (immutable).
 void encodeWithCoder(NSCoder coder)
          Encodes the receiver using coder.
 Set entrySet()
           
 boolean equals(Object object)
          Compares this dictionary to object.
 Object get(Object key)
          Conforms to NSDictionary.objectForKey() specification.
 int hashCode()
           
 HashMap hashMap()
           
 Hashtable hashtable()
           
 NSDictionary immutableClone()
          Since NSDictionaries are immutable, there's no need to make an actual copy.
 boolean isEmpty()
           
 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.
 Set keySet()
           
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.
 Object put(Object key, Object value)
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 void putAll(Map t)
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 Object remove(Object key)
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 int size()
           
 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.
 Collection values()
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 
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.


CheckForNull

public static final boolean CheckForNull
Convenience for the constructor methods

See Also:
Constant Field Values

IgnoreNull

public static final boolean IgnoreNull
Convenience for the constructor methods

See Also:
Constant Field Values
Constructor Detail

NSDictionary

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

See Also:
NSDictionary.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(Map map,
                    boolean ignoreNull)
Creates a dictionary containing the keys and values found in Map. If ignoreNull is false, throws an IllegalArgumentException if any key or value in dictionary is null. Throws a NullPointerException if map is null.

Parameters:
map - the input Map 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
Since:
5.3
See Also:
Map

NSDictionary

public NSDictionary(Map map)
Creates a dictionary containing the keys and values found in Map. Throws an IllegalArgumentException if any key or value in dictionary is null. Throws a NullPointerException if map is null.

Parameters:
map - the input Map from which the current dictionary is to be created
Throws:
java.lang.IllegalArgumentException - when null is not allowed and a null is encountered
Since:
5.4
See Also:
Map

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

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:
NSDictionary.objectsNoCopy(), NSDictionary.allKeys()

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:
NSDictionary.keysNoCopy(), NSDictionary.allValues()

count

public int count()
This method returns a count of the number of key-value pairs.

Returns:
the number of entries in the dictionary.

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:
NSDictionary.allKeys(), NSDictionary.allValues()

hashtable

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

hashMap

public HashMap hashMap()
Returns:
a copy of this dictionary transformed into a java.util.HashMap
Since:
5.3

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:
NSDictionary.allKeys(), NSDictionary.keyEnumerator()

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

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:
NSDictionary.equals(java.lang.Object)

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. Note, this method does not adhere to the java.util.Map specification for equals and entrySets cannot Be compared to each other.

Specified by:
equals in interface Map
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)

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:
NSDictionary.allValues(), NSDictionary.allKeysForObject(java.lang.Object), NSDictionary.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:
NSDictionary.allKeys(), NSDictionary.objectEnumerator()

keyEnumerator

public Enumeration keyEnumerator()
This method provides a java.util.Enumeration which can be used to access each key in this dictionary.

        <blockquote>

        java.util.Enumeration enumerator = myDict.keyEnumerator();
        while (enumerator.hasMoreElements()) {
          Object anObject = enumerator.nextElement();
          //code to act on each element
        }

        </blockquote>
 
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:
NSDictionary.allKeys(), NSDictionary.allKeysForObject(java.lang.Object), NSDictionary.objectEnumerator()

objectEnumerator

public Enumeration objectEnumerator()
This method provides a java.util.Enumeration which can be used to access each value in this dictionary.

        <blockquote>

        java.util.Enumeration enumerator = myDict.objectEnumerator();
        while (enumerator.hasMoreElements()) {
          Object anObject = enumerator.nextElement();
          //code to act on each element
        }

        </blockquote>
 

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:
NSDictionary.keyEnumerator(), NSDictionary.allValues()

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:
NSDictionary.objectForKey(java.lang.Object), NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String)

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)

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:
NSDictionary.objectForKey(java.lang.Object), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCoding.valueForKey(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)

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

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
Parameters:
coder - an NSCoder object that will be used to encode object of classes that implement this interface
See Also:
NSCoder

hashCode

public int hashCode()
Specified by:
hashCode in interface Map
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()

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:
NSDictionary.mutableClone(), NSDictionary.immutableClone(), Object.clone()

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:
NSDictionary.mutableClone(), NSDictionary.clone()

mutableClone

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

toString

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

emptyDictionary

public static final NSDictionary emptyDictionary()
Returns the empty NSDictionary (immutable). This map is serializable.

This example illustrates the type-safe way to obtain an empty dictionary:

 Map<String>      s       = NSDictionary.emptyArray();
 
Implementation note: Implementations of this method need not create a separate NSDictionary object for each call. Using this method is likely to have comparable cost to using the like-named field. (Unlike this method, the field does not provide type safety.)

Since:
5.4
See Also:
NSDictionary.EmptyDictionary

size

public int size()
Specified by:
size in interface Map
Since:
5.3
See Also:
Map.size()

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface Map
Since:
5.3
See Also:
Map.isEmpty()

containsKey

public boolean containsKey(Object key)
NSDictionaries do not allow null keys which differs from the java.util.Map specification. We return false for the key = null case

Specified by:
containsKey in interface Map
Since:
5.3
See Also:
Map.containsKey(java.lang.Object)

containsValue

public boolean containsValue(Object value)
NSDictionaries do not allow for null values which differs from the java.util.Map specification. We return false for the value = null case.

Specified by:
containsValue in interface Map
Since:
5.3
See Also:
Map.containsValue(java.lang.Object)

get

public Object get(Object key)
Conforms to NSDictionary.objectForKey() specification.

Specified by:
get in interface Map
Since:
5.3
See Also:
Map.get(java.lang.Object)

put

public Object put(Object key,
                  Object value)
Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:
put in interface Map
Throws:
UnsupportedOperationException
Since:
5.3
See Also:
Map.put(K, V)

remove

public Object remove(Object key)
Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:
remove in interface Map
Throws:
UnsupportedOperationException
Since:
5.3
See Also:
Map.remove(java.lang.Object)

putAll

public void putAll(Map t)
Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:
putAll in interface Map
Throws:
UnsupportedOperationException
Since:
5.3
See Also:
Map.putAll(java.util.Map)

clear

public void clear()
Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:
clear in interface Map
Throws:
UnsupportedOperationException
Since:
5.3
See Also:
Map.clear()

keySet

public Set keySet()
Specified by:
keySet in interface Map
Since:
5.3
See Also:
Map.keySet()

values

public Collection values()
Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:
values in interface Map
Returns:
NSArray - array of values
Since:
5.3
See Also:
Map.values()

entrySet

public Set entrySet()
Specified by:
entrySet in interface Map
Since:
5.3
See Also:
Map.keySet()

Last updated June 2008

Copyright © 2000-2008 Apple Inc.