PATH Documentation > WebObjects

Table of Contents

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.

See Also: removeObjectForKey, removeObjectsForKeys



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.



© 2001 Apple Computer, Inc. (Last Published April 17, 2001)


Table of Contents