iOS Developer Library — Pre-Release

Developer

Foundation Framework Reference NSMutableDictionary Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableDictionary

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.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • Creates and returns a mutable dictionary, initially giving it enough allocated memory to hold a given number of entries.

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • init(capacity:) - initWithCapacity: Designated Initializer

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

    Declaration

    Swift

    init(capacity numItems: Int)

    Objective-C

    - (instancetype)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.

    This method is a designated initializer of NSMutableDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • init() - init Designated Initializer

    Initializes a newly allocated mutable dictionary.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    A mutable dictionary.

    Discussion

    This method is a designated initializer of NSMutableDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    init(sharedKeySet keyset: AnyObject) -> NSMutableDictionary

    Objective-C

    + (NSMutableDictionary *)dictionaryWithSharedKeySet:(id)keyset

    Parameters

    keyset

    The keyset, created by the NSDictionary class method sharedKeySetForKeys:.

    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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • Adds a given key-value pair to the dictionary.

    Declaration

    Swift

    func setObject(_ anObject: AnyObject, forKey aKey: NSCopying)

    Objective-C

    - (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.

    aKey

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Adds a given key-value pair to the dictionary.

    Declaration

    Objective-C

    - (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.

    aKey

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

    Discussion

    This method is identical to setObject:forKey:.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 6.0 and later.

  • Adds a given key-value pair to the dictionary.

    Declaration

    Swift

    func setValue(_ value: AnyObject?, forKey key: String)

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    valueForKey: (NSDictionary)

  • Adds to the receiving dictionary the entries from another dictionary.

    Declaration

    Swift

    func addEntriesFromDictionary(_ otherDictionary: [NSObject : AnyObject])

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Sets the contents of the receiving dictionary to entries in a given dictionary.

    Declaration

    Swift

    func setDictionary(_ otherDictionary: [NSObject : AnyObject])

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func removeObjectForKey(_ aKey: AnyObject)

    Objective-C

    - (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"];

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Empties the dictionary of its entries.

    Declaration

    Swift

    func removeAllObjects()

    Objective-C

    - (void)removeAllObjects

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func removeObjectsForKeys(_ keyArray: [AnyObject])

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.