- Inherits from:
- NSDictionary : NSObject
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying (NSDictionary)
- NSObject (NSObject)
Declared in:
- Foundation/NSDictionary.h
An NSDictionary object stores a mutable set of entries.
+ dictionaryWithCapacity: | Returns an empty dictionary with enough allocated space to hold a specified number of objects |
- removeObjectForKey: | Removes the specified entry from the dictionary. |
- removeObjectsForKeys: | Removes multiple entries from the dictionary. |
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];
- Creating an NSMutableDictionary
- + dictionaryWithCapacity:
- - initWithCapacity:
- Adding and removing entries
- - addEntriesFromDictionary:
- - removeAllObjects
- - removeObjectForKey:
- - removeObjectsForKeys:
- - setDictionary:
- - setObject:forKey:
+ (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:
- (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:
- (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:
- (void)removeAllObjects
Empties the dictionary of its entries. Each key and corresponding value object is sent a release message.
See Also: - removeObjectForKey:, - removeObjectsForKeys:
- (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:
- (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:
- (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.
- (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: