Next Page > Hide TOC

NSMutableDictionary Class Reference

Class at a Glance

An NSDictionary object stores a mutable set of entries.

Principal Attributes

• A count of the number of entries in the dictionary

• The set of keys contained in the dictionary

• The objects that correspond to the keys in the dictionary

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.

Overview

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 runtime error if anObject was not retained before it was removed:

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

[aDictionary removeObjectForKey:theKey];

[anObject someMessage];

Tasks

Creating and Initializing a Mutable Dictionary

• + dictionaryWithCapacity:
• – initWithCapacity:

Adding Entries to a Mutable Dictionary

• – setObject:forKey:
• – setValue:forKey:
• – addEntriesFromDictionary:
• – setDictionary:

Removing Entries From a Mutable Dictionary

• – removeObjectForKey:
• – removeAllObjects
• – removeObjectsForKeys:

Class Methods

dictionaryWithCapacity:

Creates and returns a mutable dictionary, initially giving it enough allocated memory to hold a given number of entries.

+ (id)dictionaryWithCapacity:(NSUInteger)numItems

Parameters

numItems

The initial capacity of the new dictionary.

Return Value

A new mutable dictionary with enough allocated memory to hold numItems entries.

Discussion

Mutable dictionaries allocate additional memory as needed, so numItems simply establishes the object’s initial capacity.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• dictionary (NSDictionary)
• dictionaryWithContentsOfFile: (NSDictionary)
• dictionaryWithContentsOfURL:: (NSDictionary)
• dictionaryWithObject:forKey: (NSDictionary)
• dictionaryWithObjects:forKeys:: (NSDictionary)
• dictionaryWithObjects:forKeys:count: (NSDictionary)
• dictionaryWithObjectsAndKeys: (NSDictionary)
• – initWithCapacity:

Related Sample Code

• Dicey
• EnhancedAudioBurn
• NSFontAttributeExplorer
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

Instance Methods

addEntriesFromDictionary:

Adds to the receiver the entries from another dictionary.

- (void)addEntriesFromDictionary:(NSDictionary *)otherDictionary

Parameters

otherDictionary

The dictionary from which to add entries

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setObject:forKey:

Related Sample Code

• EnhancedAudioBurn
• EnhancedDataBurn
• Sketch-112

Declared In

initWithCapacity:

Initializes a newly allocated mutable dictionary, allocating enough memory to hold numItems entries.

- (id)initWithCapacity:(NSUInteger)numItems

Parameters

numItems

The initial capacity of the initialized dictionary.

Return Value

An initialized mutable dictionary, which might be different than the original receiver.

Discussion

Mutable dictionaries allocate additional memory as needed, so numItems simply establishes the object’s initial capacity.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + dictionaryWithCapacity:

Declared In

removeAllObjects

Empties the receiver of its entries.

- (void)removeAllObjects

Discussion

Each key and corresponding value object is sent a release message.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeObjectForKey:
• – removeObjectsForKeys:

Related Sample Code

• QTSSConnectionMonitor
• QTSSInspector

Declared In

removeObjectForKey:

Removes a given key and its associated value from the receiver.

- (void)removeObjectForKey:(id)aKey

Parameters

aKey

The key to remove.

Discussion

Does nothing if aKey does not exist.

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

NSMutableDictionary *stations = nil;

stations = [[NSMutableDictionary alloc]

        initWithContentsOfFile: pathToArchive];

[stations removeObjectForKey:@"KIKT"];

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeAllObjects
• – removeObjectsForKeys:

Related Sample Code

• AnimatedSlider
• CoreRecipes
• EnhancedAudioBurn
• GridCalendar

Declared In

removeObjectsForKeys:

Removes from the receiver entries specified by elements in a given array.

- (void)removeObjectsForKeys:(NSArray *)keyArray

Parameters

keyArray

An array of objects specifying the keys to remove.

Discussion

If a key in keyArray does not exist, the entry is ignored.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeObjectForKey:
• – removeObjectForKey:

Related Sample Code

• CoreRecipes

Declared In

setDictionary:

Sets the contents of the receiver to entries in a given dictionary.

- (void)setDictionary:(NSDictionary *)otherDictionary

Parameters

otherDictionary

A dictionary containing the new entries.

Discussion

All entries are removed from the receiver (with removeAllObjects), then each entry from otherDictionary added into the receiver.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setObject:forKey:

Adds a given key-value pair to the receiver.

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

Parameters

anObject

The value for key. The object receives a retain message before being added to the receiver. This value must not be nil.

aKey

The key for value. The key is copied (using copyWithZone:; keys must conform to the NSCopying protocol). The key must not be nil.

Discussion

Raises an NSInvalidArgumentException if aKey or anObject is nil. If you need to represent a nil value in the dictionary, use NSNull.

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeObjectForKey:

Related Sample Code

• Dicey
• GridCalendar
• Quartz Composer WWDC 2005 TextEdit
• Sketch-112
• TextEditPlus

Declared In

setValue:forKey:

Adds a given key-value pair to the receiver.

- (void)setValue:(id)value forKey:(NSString *)key

Parameters

value

The value for key.

key

The key for value. Note that when using key-value coding, the key must be a string (see Key-Value Coding Fundamentals).

Discussion

This method adds value and key to the receiver using setObject:forKey:, unless value is nil in which case the method instead attempts to remove key using removeObjectForKey:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• valueForKey: (NSDictionary)

Related Sample Code

• CustomAtomicStoreSubclass
• Dicey
• SimpleCalendar
• Spotlight
• StickiesExample

Declared In

Next Page > Hide TOC