com.webobjects.foundation
Class NSMutableDictionary

java.lang.Object
  com.webobjects.foundation.NSDictionary
      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()