NSMutableDictionary

Inherits from:
NSDictionary : Object

Implements:
Cloneable
java.io.Serializable
NSCoding
NSKeyValueCoding
NSKeyValueCodingAdditions

Package:
com.webobjects.foundation

Class Description

The NSMutableDictionary class declares the programmatic interface to objects that manage mutable associations of keys and values. This class adds modification operations to the basic operations it inherits from NSDictionary.

Methods that add entries to NSMutableDictionaries-whether during construction or modification-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-9 describes the 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.

**Table 0-9 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.

Interfaces Implemented

Cloneable

clone

java.io.Serializable

NSCoding

classForCoder
decodeObject
encodeWithCoder

NSKeyValueCoding

takeValueForKey
valueForKey

NSKeyValueCodingAdditions

takeValueForKeyPath
valueForKeyPath

Method Types

Constructors

NSMutableDictionary

Adding and removing entries

addEntriesFromDictionary
removeAllObjects
removeObjectForKey
removeObjectsForKeys
setDictionary
setObjectForKey

Copying the dictionary

immutableClone

Methods inherited from Object

clone

Constructors

NSMutableDictionary

public NSMutableDictionary()

Creates an empty NSMutableDictionary.

public NSMutableDictionary(int capacity)

Creates an empty NSMutableDictionary prepared to hold at least capacity entries.

public NSMutableDictionary( NSArray objectArray, NSArray keyArray)

Creates an NSMutableDictionary with entries from the contents of the keyArray and objectArray NSArrays. This method steps through objectArray and keyArray, creating entries in the new dictionary as it goes. Each key object and its corresponding value object is added directly to the dictionary. An InvalidArgumentException is thrown if the objectArray and keyArray do not have the same number of elements.

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.

public NSMutableDictionary(NSDictionary dictionary)

Creates an NSMutableDictionary containing the keys and values found in dictionary.

public NSMutableDictionary( Object object, Object key)

Creates an NSMutableDictionary containing a single object object for a single key 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.

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. Each key object and its corresponding value object is added directly to the dictionary. An InvalidArgumentException is thrown if the objects and keys do not have the same number of elements.

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.

public NSMutableDictionary( java.util.Dictionary dictionary, boolean ignoreNull)

Creates an NSMutableDictionary containing the keys and values found in dictionary. If ignoreNull is false, throws an InvalidArgumentException if any key or value in dictionary is null.

Instance Methods

addEntriesFromDictionary

public void addEntriesFromDictionary(NSDictionary otherDictionary)

Adds the entries from otherDictionary to the receiver.

See Also: setObjectForKey

clone

public Object clone()

Returns a copy (a NSMutableDictionary object) of the receiver.

immutableClone

public NSDictionary immutableClone()

Returns an immutable copy (an NSDictionary object) of the receiver.

mutableClone

public NSMutableArray mutableClone()

Description forthcoming.

removeAllObjects

public void removeAllObjects()

Empties the dictionary of its entries.

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.

See Also: removeObjectsForKeys, removeAllObjects

removeObjectsForKeys

public void removeObjectsForKeys(NSArray keyArray)

Removes one or more objects from the receiver. The entries are identified by the keys in keyArray. This method does not raise if the receiver does not contain entries for one or more of the keys.

See Also: removeObjectForKey, removeAllObjects

setDictionary

public void setDictionary(NSDictionary otherDictionary)

Sets the receiver to entries in otherDictionary. This method removes all entries from the receiver (with removeAllObjects) and adds each entry from otherDictionary into the receiver.

setObjectForKey

public void setObjectForKey( Object anObject, Object aKey)

Adds or replaces an entry to the receiver consisting of aKey and its corresponding value object anObject. Throws an InvalidArgumentException if the key or value object is null.

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.

See Also: removeObjectForKey

takeValueForKey

public void takeValueForKey( Object value, String key)

Conformance to NSKeyValueCoding. Invokes setObjectForKey with the specified parameters if value is not null. Otherwise invokes removeObjectForKey for 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.