NSMutableDictionary Class Reference

Inherits from
NSDictionary : NSObject
Conforms to
NSCopying (NSDictionary)
NSMutableCopying (NSDictionary)
NSFastEnumeration (NSDictionary)
NSSecureCoding (NSDictionary)
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Collections Programming Topics
Declared in
NSDictionary.h
NSKeyValueCoding.h
Related sample code

Overview

The NSMutableDictionary class declares the programmatic interface to objects that manage mutable associations of keys and values. It adds modification operations to the basic operations it inherits from NSDictionary. NSMutableDictionary is “toll-free bridged” with its Core Foundation counterpart, CFMutableDictionaryRef. See “Toll-Free Bridging” for more information.

Subclassing Notes

There should typically be little need to subclass NSMutableDictionary. If you do need to customize behavior, it is often better to consider composition rather than subclassing.

Methods to Override

In a subclass, you must override both of its primitive methods:

You must also override the primitive methods of the NSDictionary class.

Tasks

Creating and Initializing a Mutable Dictionary

Adding Entries to a Mutable Dictionary

Removing Entries From a Mutable Dictionary

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 OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDictionary.h

dictionaryWithSharedKeySet:

Creates a mutable dictionary which is optimized for dealing with a known set of keys.

+ (id)dictionaryWithSharedKeySet:(id)keyset
Parameters
keyset

The keyset, created by the NSDictionary class method sharedKeySetForKeys:. If keyset is nil, an exception is thrown. If keyset is not an object returned by sharedKeySetForKeys:, an exception is thrown.

Return Value

A new mutable dictionary optimized for a known set of keys.

Discussion

Keys that are not in the key set can still be set in the dictionary, but that usage is not optimal.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSDictionary.h

Instance Methods

addEntriesFromDictionary:

Adds to the receiving dictionary 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 receiving dictionary. In contrast, each key object is copied (using copyWithZone:—keys must conform to the NSCopying protocol), and the copy is added to the receiving dictionary.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDictionary.h

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 OS X v10.0 and later.
See Also
Declared In
NSDictionary.h

removeAllObjects

Empties the dictionary of its entries.

- (void)removeAllObjects
Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDictionary.h

removeObjectForKey:

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

- (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 OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDictionary.h

removeObjectsForKeys:

Removes from the dictionary 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 OS X v10.0 and later.
See Also
Declared In
NSDictionary.h

setDictionary:

Sets the contents of the receiving dictionary 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 receiving dictionary (with removeAllObjects), then each entry from otherDictionary added into the receiving dictionary.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDictionary.h

setObject:forKey:

Adds a given key-value pair to the dictionary.

- (void)setObject:(id)anObject forKey:(id < NSCopying >)aKey
Parameters
anObject

The value for aKey. A strong reference to the object is maintained by the dictionary. Raises an NSInvalidArgumentException if anObject is nil. If you need to represent a nil value in the dictionary, use NSNull.

aKey

The key for value. The key is copied (using copyWithZone:; keys must conform to the NSCopying protocol). Raises an NSInvalidArgumentException if aKey is nil. If aKey already exists in the dictionary anObject takes its place.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDictionary.h

setObject:forKeyedSubscript:

Adds a given key-value pair to the dictionary.

- (void)setObject:(id)object forKeyedSubscript:(id < NSCopying >)aKey
Parameters
object

The value for aKey. A strong reference to the object is maintained by the dictionary. Raises an NSInvalidArgumentException if anObject is nil. If you need to represent a nil value in the dictionary, use NSNull.

aKey

The key for value. The key is copied (using copyWithZone:; keys must conform to the NSCopying protocol). Raises an NSInvalidArgumentException if aKey is nil. If aKey already exists in the dictionary anObject takes its place.

Discussion

This method is identical to setObject:forKey:.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSDictionary.h

setValue:forKey:

Adds a given key-value pair to the dictionary.

- (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 dictionary using setObject:forKey:, unless value is nil in which case the method instead attempts to remove key using removeObjectForKey:.

Availability
  • Available in OS X v10.3 and later.
See Also
Related Sample Code
Declared In
NSKeyValueCoding.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)

Did this document help you? Yes It's good, but... Not helpful...