WebObjects 5.4.2

com.webobjects.foundation
Class NSMutableDictionary

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

public class NSMutableDictionary
extends NSDictionary

The NSMutableDictionary class adds methods to insert, modify, and remove elements to the API of its parent class NSDictionary.

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

The following table describes NSMutableDictionary methods that provide the basis for all NSMutableDictionary's other methods; that is, all other methods are implemented in terms of these seven. If you create a subclass of NSMutableDictionary, 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.

NSMutableDictionary's Base API
Method Description
count Returns the number of entries in the dictionary. Inherited from NSDictionary.
objectForKey Returns the value associated with a given key. Inherited from NSDictionary.
keysNoCopy Returns a natural language array containing the keys in the dictionary. Inherited from NSDictionary.
objectsNoCopy Returns a natural language array containing the objects in the dictionary. Inherited from NSDictionary.
removeAllObjects Empties the dictionary of its entries.
removeObjectForKey Removes the specified key object and its associated value object from the dictionary.
setObjectForKey Adds or replaces an entry to the receiver consisting of the specified key and value objects.

The other methods declared here provide convenient ways of adding or removing multiple entries at a time.

See Also:
Map, HashMap, Hashtable, NSDictionary._count, NSDictionary.objectForKey(java.lang.Object), NSMutableDictionary.setObjectForKey(java.lang.Object, java.lang.Object), NSMutableDictionary.removeObjectForKey(java.lang.Object), NSMutableDictionary.removeAllObjects(), NSMutableDictionary.addEntriesFromDictionary(com.webobjects.foundation.NSDictionary), 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
 
Fields inherited from class com.webobjects.foundation.NSDictionary
CheckForNull, EmptyDictionary, IgnoreNull
 
Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions
KeyPathSeparator
 
Constructor Summary
NSMutableDictionary()
          Creates an empty NSMutableDictionary.
NSMutableDictionary(Dictionary dictionary, boolean ignoreNull)
          Creates an NSMutableDictionary containing the keys and values found in dictionary.
NSMutableDictionary(int capacity)
          Creates an empty NSMutableDictionary prepared to hold at least capacity entries.
NSMutableDictionary(Map map)
          Creates a dictionary containing the keys and values found in Map.
NSMutableDictionary(NSArray objects, NSArray keys)
          Creates an NSMutableDictionary with entries from the contents of the keys and objects NSArrays.
NSMutableDictionary(NSDictionary otherDictionary)
          Creates a new NSMutableDictionary containing the keys and values found in otherDictionary.
NSMutableDictionary(Object[] objects, Object[] keys)
          Creates an NSMutableDictionary with entries from the contents of the keys and objects arrays.
NSMutableDictionary(Object object, Object key)
          Creates an NSMutableDictionary containing a single object object for a single key key.
 
Method Summary
 void addEntriesFromDictionary(NSDictionary otherDictionary)
          Adds all the entries from otherDictionary to this dictionary.
 void clear()
          Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
 Object clone()
          Creates a new NSMutableDictionary with the same collection of keys and their values as this one currently contains.
 NSDictionary immutableClone()
          Creates a new NSDictionary with the same collection of keys and their values as this dictionary currently contains.
 NSMutableDictionary mutableClone()
          Creates a new NSMutableDictionary with the same collection of keys and their values as this one currently contains.
 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.
 void removeAllObjects()
          Deletes all the entries from the dictionary.
 Object removeObjectForKey(Object key)
          Removes the dictionary entry identified by key and returns the entry's value object.
 void removeObjectsForKeys(NSArray keys)
          Removes one or more objects which may exist in this dictionary.
 void setDictionary(NSDictionary otherDictionary)
          Replaces this dictionary's entries with those in otherDictionary.
 void setObjectForKey(Object object, Object key)
          Adds or replaces an entry to this dictionary consisting of key and its corresponding value object.
 void takeValueForKey(Object value, String key)
          Conformance to NSKeyValueCoding.
 
Methods inherited from class com.webobjects.foundation.NSDictionary
allKeys, allKeysForObject, allValues, classForCoder, containsKey, containsValue, count, decodeObject, emptyDictionary, encodeWithCoder, entrySet, equals, get, hashCode, hashMap, hashtable, isEmpty, isEqualToDictionary, keyEnumerator, keySet, keysNoCopy, objectEnumerator, objectForKey, objectsForKeys, objectsNoCopy, size, takeValueForKeyPath, toString, valueForKey, valueForKeyPath, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

NSMutableDictionary

public NSMutableDictionary()
Creates an empty NSMutableDictionary.

For better performance, one should use NSMutableDictionary(int capacity) instead.

See Also:
NSMutableDictionary.NSMutableDictionary(int capacity)

NSMutableDictionary

public NSMutableDictionary(int capacity)
Creates an empty NSMutableDictionary prepared to hold at least capacity entries. NSMutableDictionaries grow as necessary, so this is a recommended performance enhancement.

Parameters:
capacity - a size hint for the expected number of entries

NSMutableDictionary

public NSMutableDictionary(Object object,
                           Object key)
Creates an NSMutableDictionary containing a single object object for a single key key. Neither argument is permitted to be null

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

Parameters:
object - the value object with which to initialize this dictionary
key - key corresponding to the value object

NSMutableDictionary

public NSMutableDictionary(Object[] objects,
                           Object[] keys)
Creates an NSMutableDictionary 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. A key corresponds to the object which shares the same index in each of the array arguments.

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

Parameters:
objects - an array of objects with which to initialize this dictionary
keys - an array of corresponding keys
Throws:
IllegalArgumentException - if the objects and keys do not have the same number of elements, or any element in them is null

NSMutableDictionary

public NSMutableDictionary(NSArray objects,
                           NSArray keys)
Creates an NSMutableDictionary 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. A key corresponds to the object which shares the same index in each of the array arguments.

Note: NSMutableDictionary 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 - an array of objects with which to initialize this dictionary
keys - an array of corresponding keys
Throws:
IllegalArgumentException - if the objects and keys do not have the same number of elements

NSMutableDictionary

public NSMutableDictionary(NSDictionary otherDictionary)
Creates a new NSMutableDictionary containing the keys and values found in otherDictionary. One should use mutableClone instead.

Parameters:
otherDictionary - the dictionary to duplicate
See Also:
NSMutableDictionary.mutableClone(), NSMutableDictionary.clone()

NSMutableDictionary

public NSMutableDictionary(Dictionary dictionary,
                           boolean ignoreNull)
Creates an NSMutableDictionary containing the keys and values found in dictionary.

Parameters:
dictionary - a java.util.Dictionary containing a mapping of keys and values with which to initialize this dictionary
ignoreNull - true if null value is to be ignored, else false
Throws:
IllegalArgumentException - if any key or value in dictionary is null
See Also:
Dictionary

NSMutableDictionary

public NSMutableDictionary(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
Method Detail

setObjectForKey

public void setObjectForKey(Object object,
                            Object key)
Adds or replaces an entry to this dictionary consisting of key and its corresponding value object.

Note: NSMutableDictionary assumes that key objects are immutable. If the key objects are mutable, copies should be made and added to the dictionary.

Parameters:
object - a new value or a replacement value
key - the key to either insert or replace
Throws:
IllegalArgumentException - if either the key or value object is null
See Also:
NSDictionary.objectForKey(java.lang.Object), NSMutableDictionary.removeObjectForKey(java.lang.Object)

removeObjectForKey

public Object removeObjectForKey(Object key)
Removes the dictionary entry identified by key and returns the entry's value object. If no entry identified by key exists, this method returns null.

Parameters:
key - key identifying the dictionary entry
Returns:
the object which previously corresponded to key or null
See Also:
NSMutableDictionary.removeObjectsForKeys(com.webobjects.foundation.NSArray), NSMutableDictionary.removeAllObjects()

removeAllObjects

public void removeAllObjects()
Deletes all the entries from the dictionary.

See Also:
NSMutableDictionary.removeObjectForKey(java.lang.Object), NSMutableDictionary.removeObjectsForKeys(com.webobjects.foundation.NSArray)

setDictionary

public void setDictionary(NSDictionary otherDictionary)
Replaces this dictionary's entries with those in otherDictionary. This method removes all entries from this dictionary and then adds all the entries from otherDictionary into this dictionary.

Parameters:
otherDictionary - a dictionary containing the new keys and objects for this one
See Also:
NSMutableDictionary.removeAllObjects()

addEntriesFromDictionary

public void addEntriesFromDictionary(NSDictionary otherDictionary)
Adds all the entries from otherDictionary to this dictionary. Entries in otherDictionary which overlap with existing entries in this dictionary replace the current entries.

Parameters:
otherDictionary - a dictionary containing the keys and objects to add to this one
See Also:
NSMutableDictionary.setObjectForKey(java.lang.Object, java.lang.Object)

removeObjectsForKeys

public void removeObjectsForKeys(NSArray keys)
Removes one or more objects which may exist in this dictionary. The entries are identified by the keys in keys. This method simply ignores any keys which are not present in this dictionary.

Parameters:
keys - keys in the key array identifying the dictionary entries
See Also:
NSMutableDictionary.removeObjectForKey(java.lang.Object), NSMutableDictionary.removeAllObjects()

takeValueForKey

public void takeValueForKey(Object value,
                            String key)
Conformance to NSKeyValueCoding.

Invokes setObjectForKey with the specified parameters if value is not null. Otherwise if value is is nullremoveObjectForKey with the specified key.

Note: NSMutableDictionary 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.

Specified by:
takeValueForKey in interface NSKeyValueCoding
Overrides:
takeValueForKey in class NSDictionary
Parameters:
value - a new value object, or null
key - key whose corresponding value should be updated, or the key to be removed.
See Also:
NSKeyValueCoding, NSMutableDictionary.setObjectForKey(java.lang.Object, java.lang.Object), NSMutableDictionary.removeObjectForKey(java.lang.Object)

clone

public Object clone()
Creates a new NSMutableDictionary with the same collection of keys and their values as this one currently contains.

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

immutableClone

public NSDictionary immutableClone()
Creates a new NSDictionary with the same collection of keys and their values as this dictionary currently contains. The new dictionary is immutable.

Overrides:
immutableClone in class NSDictionary
Returns:
an immutable copy (an NSDictionary object) of this dictionary
See Also:
NSMutableDictionary.mutableClone(), NSMutableDictionary.clone()

mutableClone

public NSMutableDictionary mutableClone()
Creates a new NSMutableDictionary with the same collection of keys and their values as this one currently contains.

Overrides:
mutableClone in class NSDictionary
Returns:
a clone of this NSMutableDictionary
See Also:
NSMutableDictionary.immutableClone(), NSMutableDictionary.clone()

put

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

Specified by:
put in interface Map
Overrides:
put in class NSDictionary
Since:
5.4
See Also:
Map.put(K, V)

remove

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

Specified by:
remove in interface Map
Overrides:
remove in class NSDictionary
Since:
5.4
See Also:
Map.remove(java.lang.Object)

putAll

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

Specified by:
putAll in interface Map
Overrides:
putAll in class NSDictionary
Since:
5.4
See Also:
Map.putAll(java.util.Map)

clear

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

Specified by:
clear in interface Map
Overrides:
clear in class NSDictionary
Since:
5.4
See Also:
Map.clear()

Last updated June 2008

Copyright © 2000-2008 Apple Inc.