PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSMutableDictionary


Inherits from:
NSDictionary : NSObject
Conforms to:
NSCoding
NSCopying
NSMutableCopying (NSDictionary)
NSObject (NSObject)
Declared in:
Foundation/NSDictionary.h



Class at a Glance


An NSDictionary object stores a mutable set of entries.

Principal Attributes


Creation



+ dictionaryWithCapacity: Returns an empty dictionary with enough allocated space to hold a specified number of objects

Commonly Used Methods



- removeObjectForKey: Removes the specified entry from the dictionary.
- removeObjectsForKeys: Removes multiple entries from the dictionary.


Class Description


The NSMutableDictionary class declares the programmatic interface to objects that manage mutable associations of keys and values. With its two efficient primitive methods- setObject:forKey: and removeObjectForKey:-this class adds modification operations to the basic operations it inherits from NSDictionary.

The other methods declared here operate by invoking one or both of these primitives. The non-primitive methods provide convenient ways of adding or removing multiple entries at a time.

When an entry is removed from a mutable dictionary, the key and value objects that make up the entry receive release messages. If there are no further references to the objects, they're deallocated. Note that if your program keeps a reference to such an object, the reference will become invalid unless you remember to send the object a retain message before it's removed from the dictionary. For example, the third statement below would result in a run-time error if anObject was not retained before it was removed:

id anObject = [aDictionary objectForKey:theKey] retain];

[aDictionary removeObjectForKey:theKey];
[anObject someMessage];




Method Types


Creating an NSMutableDictionary
+ dictionaryWithCapacity:
- initWithCapacity:
Adding and removing entries
- addEntriesFromDictionary:
- removeAllObjects
- removeObjectForKey:
- removeObjectsForKeys:
- setDictionary:
- setObject:forKey:


Class Methods



dictionaryWithCapacity:

+ (id)dictionaryWithCapacity:(unsigned)numItems

Creates and returns a mutable dictionary, giving it enough allocated memory to hold numItems entries. Mutable dictionaries allocate additional memory as needed, so numItems simply establishes the object's initial capacity.

See Also: + dictionary (NSDictionary), + dictionaryWithContentsOfFile: (NSDictionary), + dictionaryWithObjects:forKeys: (NSDictionary), + dictionaryWithObjects:forKeys:count: (NSDictionary), + dictionaryWithObjectsAndKeys: (NSDictionary), - initWithCapacity:




Instance Methods



addEntriesFromDictionary:

- (void)addEntriesFromDictionary:(NSDictionary *)otherDictionary

Adds the entries from otherDictionary to the receiver. Each value object from otherDictionary is sent a retain message before being added to the receiver. In contrast, each key object is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the receiver.

If both dictionaries contain the same key, the receiver's previous value object for that key is sent a release message and the new value object takes its place.

See Also: - setObject:forKey:



initWithCapacity:

- (id)initWithCapacity:(unsigned)numItems

Initializes a newly allocated mutable dictionary, allocating enough memory to hold numItems entries. Mutable dictionaries allocate additional memory as needed, so numItems simply establishes the object's initial capacity. Returns self.

See Also: - dictionaryWithCapacity:



removeAllObjects

- (void)removeAllObjects

Empties the dictionary of its entries. Each key and corresponding value object is sent a release message.

See Also: - removeObjectForKey:, - removeObjectsForKeys:



removeObjectForKey:

- (void)removeObjectForKey:(id)aKey

Removes aKey and its associated value object from the dictionary.

For example, assume you have an archived dictionary that records the call letters and associated frequencies of radio stations. To remove an entry of a defunct station, you could write code similar to the following:

NSMutableDictionary *stations = nil;

stations = [[NSMutableDictionary alloc] 
        initWithContentsOfFile: theArchiveFile];
[stations removeObjectForKey:@"KIKT"];

See Also: - removeAllObjects, - removeObjectsForKeys:



removeObjectsForKeys:

- (void)removeObjectsForKeys:(NSArray *)keyArray

Removes one or more entries from the receiver. The entries are identified by the keys in keyArray.

See Also: - removeObjectForKey:, - removeObjectForKey:



setDictionary:

- (void)setDictionary:(NSDictionary *)otherDictionary

Sets the receiver to entries in otherDictionary. setDictionary: does this by removing all entries from the receiver (with removeAllObjects) then adding each entry from otherDictionary into the receiver.



setObject:forKey:

- (void)setObject:(id)anObject forKey:(id)aKey

Adds an entry to the receiver, consisting of aKey and its corresponding value object anObject. The value object receives a retain message before being added to the dictionary. In contrast, the key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the dictionary. Raises an NSInvalidArgumentException if the key or value object is nil.

If aKey already exists in the receiver, the receiver's previous value object for that key is sent a release message and anObject takes its place.

See Also: - removeObjectForKey:




Table of Contents