iOS Developer Library — Pre-Release

Developer

Foundation Framework Reference NSDictionary Class Reference

Options
Deployment Target:

On This Page
Language:

NSDictionary

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. Use this class or its subclass NSMutableDictionary when you need a convenient and efficient way to retrieve data associated with an arbitrary key. NSDictionary creates static dictionaries, and NSMutableDictionary creates dynamic dictionaries. (For convenience, the term dictionary refers to any instance of one of these classes without specifying its exact class membership.)

A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key and a second object that is that key’s value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by isEqual:). In general, a key can be any object (provided that it conforms to the NSCopying protocol—see below), but note that when using key-value coding the key must be a string (see Key-Value Coding Fundamentals). Neither a key nor a value can be nil; if you need to represent a null value in a dictionary, you should use NSNull.

NSDictionary is “toll-free bridged” with its Core Foundation counterpart, CFDictionaryRef. See Toll-Free Bridging for more information on toll-free bridging.

Subclassing Notes

You generally shouldn’t need to subclass NSDictionary. Custom behavior can usually be achieved through composition rather than subclassing.

Methods to Override

If you do need to subclass NSDictionary, take into account that it is a class cluster. Any subclass must override the following primitive methods:

The other methods of NSDictionary operate by invoking one or more of these primitives. The non-primitive methods provide convenient ways of accessing multiple entries at once.

Alternatives to Subclassing

Before making a custom class of NSDictionary, investigate NSMapTable and the corresponding Core Foundation type, CFDictionary Reference. Because NSDictionary and CFDictionary are “toll-free bridged,” you can substitute a CFDictionary object for a NSDictionary object in your code (with appropriate casting). Although they are corresponding types, CFDictionary and NSDictionary do not have identical interfaces or implementations, and you can sometimes do things with CFDictionary that you cannot easily do with NSDictionary.

If the behavior you want to add supplements that of the existing class, you could write a category on NSDictionary. Keep in mind, however, that this category will be in effect for all instances of NSDictionary that you use, and this might have unintended consequences. Alternatively, you could use composition to achieve the desired behavior.

  • Creates and returns an empty dictionary.

    Declaration

    Objective-C

    + (instancetype)dictionary

    Return Value

    A new empty dictionary.

    Discussion

    This method is declared primarily for use with mutable subclasses of NSDictionary.

    If you don’t want a temporary object, you can also create an empty dictionary using alloc... and init.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary using the keys and values found in a file specified by a given path.

    Declaration

    Objective-C

    + (NSDictionary *)dictionaryWithContentsOfFile:(NSString *)path

    Parameters

    path

    A full or relative pathname. The file identified by path must contain a string representation of a property list whose root object is a dictionary.

    Return Value

    A new dictionary that contains the dictionary at path, or nil if there is a file error or if the contents of the file are an invalid representation of a dictionary.

    Discussion

    The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary using the keys and values found in a resource specified by a given URL.

    Declaration

    Objective-C

    + (NSDictionary *)dictionaryWithContentsOfURL:(NSURL *)aURL

    Parameters

    aURL

    An URL that identifies a resource containing a string representation of a property list whose root object is a dictionary.

    Return Value

    A new dictionary that contains the dictionary at aURL, or nil if there is an error or if the contents of the resource are an invalid representation of a dictionary.

    Discussion

    The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary containing the keys and values from another given dictionary.

    Declaration

    Objective-C

    + (instancetype)dictionaryWithDictionary:(NSDictionary *)otherDictionary

    Parameters

    otherDictionary

    A dictionary containing the keys and values with which to initialize the new dictionary.

    Return Value

    A new dictionary containing the keys and values found in otherDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary containing a given key and value.

    Declaration

    Swift

    convenience init(object anObject: AnyObject, forKey aKey: NSCopying)

    Objective-C

    + (instancetype)dictionaryWithObject:(id)anObject forKey:(id<NSCopying>)aKey

    Parameters

    anObject

    The value corresponding to aKey.

    If this value is nil, an NSInvalidArgumentException is raised.

    aKey

    The key for anObject.

    If this value is nil, an NSInvalidArgumentException is raised.

    Return Value

    A new dictionary containing a single object, anObject, for a single key, aKey.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary containing entries constructed from the contents of an array of keys and an array of values.

    Declaration

    Objective-C

    + (instancetype)dictionaryWithObjects:(NSArray *)objects forKeys:(NSArray *)keys

    Parameters

    objects

    An array containing the values for the new dictionary.

    keys

    An array containing the keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the dictionary.

    Return Value

    A new dictionary containing entries constructed from the contents of objects and keys.

    Discussion

    This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if objects and keys don’t have the same number of elements.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary containing count objects from the objects array.

    Declaration

    Objective-C

    + (instancetype)dictionaryWithObjects:(const id [])objects forKeys:(const id<NSCopying> [])keys count:(NSUInteger)count

    Parameters

    objects

    A C array of values for the new dictionary.

    keys

    A C array of keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

    count

    The number of elements to use from the keys and objects arrays. count must not exceed the number of elements in objects or keys.

    Discussion

    This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if a key or value object is nil.

    The following code fragment illustrates how to create a dictionary that associates the alphabetic characters with their ASCII values:

    • static const NSInteger N_ENTRIES = 26;
    • NSDictionary *asciiDict;
    • NSString *keyArray[N_ENTRIES];
    • NSNumber *valueArray[N_ENTRIES];
    • NSInteger i;
    • for (i = 0; i < N_ENTRIES; i++) {
    • char charValue = 'a' + i;
    • keyArray[i] = [NSString stringWithFormat:@"%c", charValue];
    • valueArray[i] = [NSNumber numberWithChar:charValue];
    • }
    • asciiDict = [NSDictionary dictionaryWithObjects:(id *)valueArray
    • forKeys:(id *)keyArray count:N_ENTRIES];

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a dictionary containing entries constructed from the specified set of values and keys.

    Declaration

    Objective-C

    + (instancetype)dictionaryWithObjectsAndKeys:(id)firstObject, ...

    Parameters

    firstObject

    The first value to add to the new dictionary.

    ...

    First the key for firstObject, then a null-terminated list of alternating values and keys. If any key is nil, an NSInvalidArgumentException is raised.

    Discussion

    This method is similar to dictionaryWithObjects:forKeys:, differing only in the way key-value pairs are specified.

    For example:

    • NSDictionary *dict = [NSDictionary dictionaryWithObjectsAndKeys:
    • @"value1", @"key1", @"value2", @"key2", nil];

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary using the keys and values found in a file at a given path.

    Declaration

    Swift

    convenience init?(contentsOfFile path: String)

    Objective-C

    - (NSDictionary *)initWithContentsOfFile:(NSString *)path

    Parameters

    path

    A full or relative pathname. The file identified by path must contain a string representation of a property list whose root object is a dictionary.

    Return Value

    An initialized dictionary—which might be different than the original receiver—that contains the dictionary at path, or nil if there is a file error or if the contents of the file are an invalid representation of a dictionary.

    Discussion

    The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary using the keys and values found at a given URL.

    Declaration

    Swift

    convenience init?(contentsOfURL aURL: NSURL)

    Objective-C

    - (NSDictionary *)initWithContentsOfURL:(NSURL *)aURL

    Parameters

    aURL

    An URL that identifies a resource containing a string representation of a property list whose root object is a dictionary.

    Return Value

    An initialized dictionary—which might be different than the original receiver—that contains the dictionary at aURL, or nil if there is an error or if the contents of the resource are an invalid representation of a dictionary.

    Discussion

    The dictionary representation in the file identified by path must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this dictionary are immutable, even if the dictionary is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary by placing in it the keys and values contained in another given dictionary.

    Declaration

    Swift

    convenience init(dictionary otherDictionary: [NSObject : AnyObject])

    Objective-C

    - (instancetype)initWithDictionary:(NSDictionary *)otherDictionary

    Parameters

    otherDictionary

    A dictionary containing the keys and values with which to initialize the new dictionary.

    Return Value

    An initialized dictionary—which might be different than the original receiver—containing the keys and values found in otherDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary using the objects contained in another given dictionary.

    Declaration

    Swift

    convenience init(dictionary otherDictionary: [NSObject : AnyObject], copyItems flag: Bool)

    Objective-C

    - (instancetype)initWithDictionary:(NSDictionary *)otherDictionary copyItems:(BOOL)flag

    Parameters

    otherDictionary

    A dictionary containing the keys and values with which to initialize the new dictionary.

    flag

    If YEStrue, each object in otherDictionary receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned dictionary.

    If NOfalse, then in a managed memory environment each object in otherDictionary simply receives a retain message when it is added to the returned dictionary.

    Return Value

    An initialized object—which might be different than the original receiver—containing the keys and values found in otherDictionary.

    Discussion

    After an immutable dictionary has been initialized in this way, it cannot be modified.

    The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YEStrue for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NOfalse the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary with entries constructed from the contents of the objects and keys arrays.

    Declaration

    Swift

    convenience init(objects objects: [AnyObject], forKeys keys: [AnyObject])

    Objective-C

    - (instancetype)initWithObjects:(NSArray *)objects forKeys:(NSArray *)keys

    Parameters

    objects

    An array containing the values for the new dictionary.

    keys

    An array containing the keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

    Discussion

    This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if the objects and keys arrays do not have the same number of elements.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary with count entries.

    Declaration

    Swift

    init(objects objects: UnsafePointer<AnyObject?>, forKeys keys: UnsafePointer<NSCopying?>, count count: Int)

    Objective-C

    - (instancetype)initWithObjects:(const id [])objects forKeys:(const id<NSCopying> [])keys count:(NSUInteger)count

    Parameters

    objects

    A C array of values for the new dictionary.

    keys

    A C array of keys for the new dictionary. Each key is copied (using copyWithZone:; keys must conform to the NSCopying protocol), and the copy is added to the new dictionary.

    count

    The number of elements to use from the keys and objects arrays. count must not exceed the number of elements in objects or keys.

    Discussion

    This method steps through the objects and keys arrays, creating entries in the new dictionary as it goes. An NSInvalidArgumentException is raised if a key or value object is nil.

    This method is a designated initializer of NSDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated dictionary with entries constructed from the specified set of values and keys.

    Declaration

    Objective-C

    - (instancetype)initWithObjectsAndKeys:(id)firstObject, ...

    Parameters

    firstObject

    The first value to add to the new dictionary.

    ...

    First the key for firstObject, then a null-terminated list of alternating values and keys. If any key is nil, an NSInvalidArgumentException is raised.

    Discussion

    This method is similar to initWithObjects:forKeys:, differing only in the way in which the key-value pairs are specified.

    For example:

    • NSDictionary *dict = [[NSDictionary alloc] initWithObjectsAndKeys:
    • @"value1", @"key1", @"value2", @"key2", nil];

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

  • init() - init Designated Initializer

    Initializes a newly allocated dictionary.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    A dictionary.

    Discussion

    This method is a designated initializer of NSDictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • Creates a shared key set object for the specified keys.

    Declaration

    Swift

    class func sharedKeySetForKeys(_ keys: [AnyObject]) -> AnyObject

    Objective-C

    + (id)sharedKeySetForKeys:(NSArray *)keys

    Parameters

    keys

    The array of keys. If the parameter is nil, an exception is thrown. If the array of keys is empty, an empty key set is returned.

    Return Value

    A shared key set object.

    Discussion

    The array of keys may contain duplicates which are quietly ignored. Duplicate hash values of the keys are quietly allowed, but may cause lower performance and increase memory usage.

    Typically you would create a shared key set for a given set of keys once, before creating shared key dictionaries, and retain and save the result of this method for use with the NSMutableDictionary class method dictionaryWithSharedKeySet:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • count count Property

    The number of entries in the dictionary (read-only)

    Declaration

    Swift

    var count: Int { get }

    Objective-C

    @property(readonly) NSUInteger count

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a Boolean value that indicates whether the contents of the receiving dictionary are equal to the contents of another given dictionary.

    Declaration

    Swift

    func isEqualToDictionary(_ otherDictionary: [NSObject : AnyObject]) -> Bool

    Objective-C

    - (BOOL)isEqualToDictionary:(NSDictionary *)otherDictionary

    Parameters

    otherDictionary

    The dictionary with which to compare the receiving dictionary.

    Return Value

    YEStrue if the contents of otherDictionary are equal to the contents of the receiving dictionary, otherwise NOfalse.

    Discussion

    Two dictionaries have equal contents if they each hold the same number of entries and, for a given key, the corresponding value objects in each dictionary satisfy the isEqual: test.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    isEqual: (NSObject protocol)

  • allKeys allKeys Property

    A new array containing the dictionary’s keys, or an empty array if the dictionary has no entries (read-only)

    Declaration

    Swift

    var allKeys: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *allKeys

    Discussion

    The order of the elements in the array is not defined.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a new array containing the keys corresponding to all occurrences of a given object in the dictionary.

    Declaration

    Swift

    func allKeysForObject(_ anObject: AnyObject) -> [AnyObject]

    Objective-C

    - (NSArray *)allKeysForObject:(id)anObject

    Parameters

    anObject

    The value to look for in the dictionary.

    Return Value

    A new array containing the keys corresponding to all occurrences of anObject in the dictionary. If no object matching anObject is found, returns an empty array.

    Discussion

    Each object in the dictionary is sent an isEqual: message to determine if it’s equal to anObject.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • allValues allValues Property

    A new array containing the dictionary’s values, or an empty array if the dictionary has no entries (read-only)

    Declaration

    Swift

    var allValues: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *allValues

    Discussion

    The order of the values in the array isn’t defined.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns by reference C arrays of the keys and values in the dictionary.

    Declaration

    Swift

    func getObjects(_ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>, andKeys keys: AutoreleasingUnsafeMutablePointer<AnyObject?>)

    Objective-C

    - (void)getObjects:(id [])objects andKeys:(id [])keys

    Parameters

    objects

    Upon return, contains a C array of the values in the dictionary.

    keys

    Upon return, contains a C array of the keys in the dictionary.

    Discussion

    The elements in the returned array and the keys array have a one-for-one correspondence, so that the nth object in the returned array corresponds to the the key in keys.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value associated with a given key.

    Declaration

    Swift

    func objectForKey(_ aKey: AnyObject) -> AnyObject?

    Objective-C

    - (id)objectForKey:(id)aKey

    Parameters

    aKey

    The key for which to return the corresponding value.

    Return Value

    The value associated with aKey, or nil if no value is associated with aKey.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value associated with a given key.

    Declaration

    Objective-C

    - (id)objectForKeyedSubscript:(id)key

    Parameters

    key

    The key for which to return the corresponding value.

    Return Value

    The value associated with aKey, or nil if no value is associated with aKey.

    Discussion

    This method behaves the same as objectForKey:.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 6.0 and later.

  • Returns the set of objects from the dictionary that corresponds to the specified keys as an NSArray.

    Declaration

    Swift

    func objectsForKeys(_ keys: [AnyObject], notFoundMarker anObject: AnyObject) -> [AnyObject]

    Objective-C

    - (NSArray *)objectsForKeys:(NSArray *)keys notFoundMarker:(id)anObject

    Parameters

    keys

    An NSArray containing the keys for which to return corresponding values.

    anObject

    The marker object to place in the corresponding element of the returned array if an object isn’t found in the dictionary to correspond to a given key.

    Discussion

    The objects in the returned array and the keys array have a one-for-one correspondence, so that the nthe object in the returned array corresponds to the nthe key in keys.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value associated with a given key.

    Declaration

    Swift

    func valueForKey(_ key: String) -> AnyObject?

    Objective-C

    - (id)valueForKey:(NSString *)key

    Parameters

    key

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

    Return Value

    The value associated with key.

    Discussion

    If key does not start with “@”, invokes objectForKey:. If key does start with “@”, strips the “@” and invokes [super valueForKey:] with the rest of the key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    setValue:forKey: (NSMutableDictionary)
    – getObjects:andKeys:

  • Returns an enumerator object that lets you access each key in the dictionary.

    Declaration

    Objective-C

    - (NSEnumerator *)keyEnumerator

    Return Value

    An enumerator object that lets you access each key in the dictionary.

    Discussion

    The following code fragment illustrates how you might use this method.

    • NSEnumerator *enumerator = [myDictionary keyEnumerator];
    • id key;
    • while ((key = [enumerator nextObject])) {
    • /* code that uses the returned key */
    • }

    If you use this method with instances of mutable subclasses of NSDictionary, your code should not modify the entries during enumeration. If you intend to modify the entries, use the allKeys property to create a “snapshot” of the dictionary’s keys. Then use this snapshot to traverse the entries, modifying them along the way.

    Note that the objectEnumerator method provides a convenient way to access each value in the dictionary.

    Special Considerations

    It is more efficient to use the fast enumeration protocol (see NSFastEnumeration). Fast enumeration is available on OS X v10.5 and later and iOS 2.0 and later.

  • Returns an enumerator object that lets you access each value in the dictionary.

    Declaration

    Swift

    func objectEnumerator() -> NSEnumerator

    Objective-C

    - (NSEnumerator *)objectEnumerator

    Return Value

    An enumerator object that lets you access each value in the dictionary.

    Discussion

    The following code fragment illustrates how you might use the method.

    • NSEnumerator *enumerator = [myDictionary objectEnumerator];
    • id value;
    • while ((value = [enumerator nextObject])) {
    • /* code that acts on the dictionary’s values */
    • }

    If you use this method with instances of mutable subclasses of NSDictionary, your code should not modify the entries during enumeration. If you intend to modify the entries, use the allValues method to create a “snapshot” of the dictionary’s values. Work from this snapshot to modify the values.

    Special Considerations

    It is more efficient to use the fast enumeration protocol (see NSFastEnumeration). Fast enumeration is available on OS X v10.5 and later and iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – keyEnumerator:
    nextObject (NSEnumerator)

  • Applies a given block object to the entries of the dictionary.

    Declaration

    Swift

    func enumerateKeysAndObjectsUsingBlock(_ block: (AnyObject!, AnyObject!, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateKeysAndObjectsUsingBlock:(void (^)(id key, id obj, BOOL *stop))block

    Parameters

    block

    A block object to operate on entries in the dictionary.

    Discussion

    If the block sets *stop to YEStrue, the enumeration stops.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Applies a given block object to the entries of the dictionary.

    Declaration

    Swift

    func enumerateKeysAndObjectsWithOptions(_ opts: NSEnumerationOptions, usingBlock block: (AnyObject!, AnyObject!, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateKeysAndObjectsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(id key, id obj, BOOL *stop))block

    Parameters

    opts

    Enumeration options.

    block

    A block object to operate on entries in the dictionary.

    Discussion

    If the block sets *stop to YEStrue, the enumeration stops.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values.

    Declaration

    Swift

    func keysSortedByValueUsingSelector(_ comparator: Selector) -> [AnyObject]

    Objective-C

    - (NSArray *)keysSortedByValueUsingSelector:(SEL)comparator

    Parameters

    comparator

    A selector that specifies the method to use to compare the values in the dictionary.

    The comparator method should return NSOrderedAscending if the dictionary value is smaller than the argument, NSOrderedDescending if the dictionary value is larger than the argument, and NSOrderedSame if they are equal.

    Return Value

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values.

    Discussion

    Pairs of dictionary values are compared using the comparison method specified by comparator; the comparator message is sent to one of the values and has as its single argument the other value from the dictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using a given comparator block.

    Declaration

    Swift

    func keysSortedByValueUsingComparator(_ cmptr: NSComparator) -> [AnyObject]

    Objective-C

    - (NSArray *)keysSortedByValueUsingComparator:(NSComparator)cmptr

    Parameters

    cmptr

    A comparator block.

    Return Value

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using cmptr.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Returns an array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using a given comparator block and a specified set of options.

    Declaration

    Swift

    func keysSortedByValueWithOptions(_ opts: NSSortOptions, usingComparator cmptr: NSComparator) -> [AnyObject]

    Objective-C

    - (NSArray *)keysSortedByValueWithOptions:(NSSortOptions)opts usingComparator:(NSComparator)cmptr

    Parameters

    opts

    A bitmask of sort options.

    cmptr

    A comparator block.

    Return Value

    An array of the dictionary’s keys, in the order they would be in if the dictionary were sorted by its values using cmptr with the options given in opts.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Returns the set of keys whose corresponding value satisfies a constraint described by a block object.

    Declaration

    Swift

    func keysOfEntriesPassingTest(_ predicate: (AnyObject!, AnyObject!, UnsafeMutablePointer<ObjCBool>) -> Bool) -> Set<NSObject>

    Objective-C

    - (NSSet *)keysOfEntriesPassingTest:(BOOL (^)(id key, id obj, BOOL *stop))predicate

    Parameters

    predicate

    A block object that specifies constraints for values in the dictionary.

    Return Value

    The set of keys whose corresponding value satisfies predicate.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Returns the set of keys whose corresponding value satisfies a constraint described by a block object.

    Declaration

    Swift

    func keysOfEntriesWithOptions(_ opts: NSEnumerationOptions, passingTest predicate: (AnyObject!, AnyObject!, UnsafeMutablePointer<ObjCBool>) -> Bool) -> Set<NSObject>

    Objective-C

    - (NSSet *)keysOfEntriesWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(id key, id obj, BOOL *stop))predicate

    Parameters

    opts

    A bit mask of enumeration options.

    predicate

    A block object that specifies constraints for values in the dictionary.

    Return Value

    The set of keys whose corresponding value satisfies predicate.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Writes a property list representation of the contents of the dictionary to a given path.

    Declaration

    Swift

    func writeToFile(_ path: String, atomically flag: Bool) -> Bool

    Objective-C

    - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag

    Parameters

    path

    The path at which to write the file.

    If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

    flag

    A flag that specifies whether the file should be written atomically.

    If flag is YEStrue, the dictionary is written to an auxiliary file, and then the auxiliary file is renamed to path. If flag is NOfalse, the dictionary is written directly to path. The YEStrue option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

    Return Value

    YEStrue if the file is written successfully, otherwise NOfalse.

    Discussion

    This method recursively validates that all the contained objects are property list objects (instances of NSData, NSDate, NSNumber, NSString, NSArray, or NSDictionary) before writing out the file, and returns NOfalse if all the objects are not property list objects, since the resultant file would not be a valid property list.

    If the dictionary’s contents are all property list objects, the file written by this method can be used to initialize a new dictionary with the class method dictionaryWithContentsOfFile: or the instance method initWithContentsOfFile:.

    For more information about property lists, see Property List Programming Guide.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Writes a property list representation of the contents of the dictionary to a given URL.

    Declaration

    Swift

    func writeToURL(_ aURL: NSURL, atomically flag: Bool) -> Bool

    Objective-C

    - (BOOL)writeToURL:(NSURL *)aURL atomically:(BOOL)flag

    Parameters

    aURL

    The URL to which to write the dictionary.

    flag

    A flag that specifies whether the output should be written atomically.

    If flag is YEStrue, the dictionary is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If flag is NOfalse, the dictionary is written directly to aURL. The YEStrue option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing. flag is ignored if aURL is of a type that cannot be written atomically.

    Return Value

    YEStrue if the location is written successfully, otherwise NOfalse.

    Discussion

    This method recursively validates that all the contained objects are property list objects (instances of NSData, NSDate, NSNumber, NSString, NSArray, or NSDictionary) before writing out the file, and returns NOfalse if all the objects are not property list objects, since the resultant output would not be a valid property list.

    If the dictionary’s contents are all property list objects, the location written by this method can be used to initialize a new dictionary with the class method dictionaryWithContentsOfURL: or the instance method initWithContentsOfURL:.

    For more information about property lists, see Property List Programming Guide.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileCreationDate key.

    Declaration

    Swift

    func fileCreationDate() -> NSDate?

    Objective-C

    - (NSDate *)fileCreationDate

    Return Value

    The value for the NSFileCreationDate key, or nil if the dictionary doesn’t have an entry for the key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileExtensionHidden key.

    Declaration

    Swift

    func fileExtensionHidden() -> Bool

    Objective-C

    - (BOOL)fileExtensionHidden

    Return Value

    The value for the NSFileExtensionHidden key, or NOfalse if the dictionary doesn’t have an entry for the key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileGroupOwnerAccountID key.

    Declaration

    Swift

    func fileGroupOwnerAccountID() -> NSNumber?

    Objective-C

    - (NSNumber *)fileGroupOwnerAccountID

    Return Value

    The value for the NSFileGroupOwnerAccountID key, or nil if the dictionary doesn’t have an entry for the key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileGroupOwnerAccountName key.

    Declaration

    Swift

    func fileGroupOwnerAccountName() -> String?

    Objective-C

    - (NSString *)fileGroupOwnerAccountName

    Return Value

    The value for the key NSFileGroupOwnerAccountName, or nil if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the name of the corresponding file’s group.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileHFSCreatorCode key.

    Declaration

    Swift

    func fileHFSCreatorCode() -> OSType

    Objective-C

    - (OSType)fileHFSCreatorCode

    Return Value

    The value for the NSFileHFSCreatorCode key, or 0 if the dictionary doesn’t have an entry for the key.

    Discussion

    See HFS File Types for details on the OSType data type.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileHFSTypeCode key.

    Declaration

    Swift

    func fileHFSTypeCode() -> OSType

    Objective-C

    - (OSType)fileHFSTypeCode

    Return Value

    The value for the NSFileHFSTypeCode key, or 0 if the dictionary doesn’t have an entry for the key.

    Discussion

    See HFS File Types for details on the OSType data type.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileAppendOnly key.

    Declaration

    Swift

    func fileIsAppendOnly() -> Bool

    Objective-C

    - (BOOL)fileIsAppendOnly

    Return Value

    The value for the NSFileAppendOnly key, or NOfalse if the dictionary doesn’t have an entry for the key.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileImmutable key.

    Declaration

    Swift

    func fileIsImmutable() -> Bool

    Objective-C

    - (BOOL)fileIsImmutable

    Return Value

    The value for the NSFileImmutable key, or NOfalse if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileModificationDate.

    Declaration

    Swift

    func fileModificationDate() -> NSDate?

    Objective-C

    - (NSDate *)fileModificationDate

    Return Value

    The value for the key NSFileModificationDate, or nil if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the date that the file’s data was last modified.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the NSFileOwnerAccountID key.

    Declaration

    Swift

    func fileOwnerAccountID() -> NSNumber?

    Objective-C

    - (NSNumber *)fileOwnerAccountID

    Return Value

    The value for the NSFileOwnerAccountID key, or nil if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the account name of the file’s owner.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileOwnerAccountName.

    Declaration

    Swift

    func fileOwnerAccountName() -> String?

    Objective-C

    - (NSString *)fileOwnerAccountName

    Return Value

    The value for the key NSFileOwnerAccountName, or nil if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the account name of the file’s owner.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFilePosixPermissions.

    Declaration

    Swift

    func filePosixPermissions() -> Int

    Objective-C

    - (NSUInteger)filePosixPermissions

    Return Value

    The value, as an unsigned long, for the key NSFilePosixPermissions, or 0 if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s permissions.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileSize.

    Declaration

    Swift

    func fileSize() -> UInt64

    Objective-C

    - (unsigned long long)fileSize

    Return Value

    The value, as an unsigned long long, for the key NSFileSize, or 0 if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary such, as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s size.

    Special Considerations

    If the file has a resource fork, the returned value does not include the size of the resource fork.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileSystemFileNumber.

    Declaration

    Swift

    func fileSystemFileNumber() -> Int

    Objective-C

    - (NSUInteger)fileSystemFileNumber

    Return Value

    The value, as an unsigned long, for the key NSFileSystemFileNumber, or 0 if the dictionary doesn’t have an entry for the key

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s inode.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileSystemNumber.

    Declaration

    Swift

    func fileSystemNumber() -> Int

    Objective-C

    - (NSInteger)fileSystemNumber

    Return Value

    The value, as an unsigned long, for the key NSFileSystemNumber, or 0 if the dictionary doesn’t have an entry for the key

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the ID of the device containing the file.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value for the key NSFileType.

    Declaration

    Swift

    func fileType() -> String?

    Objective-C

    - (NSString *)fileType

    Return Value

    The value for the key NSFileType, or nil if the dictionary doesn’t have an entry for the key.

    Discussion

    This and the other file... methods are for use with a dictionary, such as those returned from the methods fileAttributesAtPath:traverseLink: (NSFileManager), directoryAttributes (NSDirectoryEnumerator), and fileAttributes (NSDirectoryEnumerator), that represents the POSIX attributes of a file or directory. This method returns the file’s type. Possible return values are described in the “Constants” section of NSFileManager.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A string that represents the contents of the dictionary, formatted as a property list (read-only)

    Declaration

    Swift

    var description: String { get }

    Objective-C

    @property(readonly, copy) NSString *description

    Discussion

    If each key in the dictionary is an NSString object, the entries are listed in ascending order by key, otherwise the order in which the entries are listed is undefined. This property is intended to produce readable output for debugging purposes, not for serializing data. If you want to store dictionary data for later retrieval, see Property List Programming Guide and Archives and Serializations Programming Guide.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A string that represents the contents of the dictionary, formatted in .strings file format (read-only)

    Declaration

    Swift

    var descriptionInStringsFileFormat: String { get }

    Objective-C

    @property(readonly, copy) NSString *descriptionInStringsFileFormat

    Discussion

    The order in which the entries are listed is undefined.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string object that represents the contents of the dictionary, formatted as a property list.

    Declaration

    Swift

    func descriptionWithLocale(_ locale: AnyObject?) -> String

    Objective-C

    - (NSString *)descriptionWithLocale:(id)locale

    Parameters

    locale

    An object that specifies options used for formatting each of the dictionary’s keys and values; pass nil if you don’t want them formatted.

    On iOS and OS X v10.5 and later, either an instance of NSDictionary or an NSLocale object may be used for locale. On OS X v10.4 and earlier it must be an instance of NSDictionary.

    Discussion

    For a description of how locale is applied to each element in the dictionary, see descriptionWithLocale:indent:.

    If each key in the dictionary responds to compare:, the entries are listed in ascending order by key, otherwise the order in which the entries are listed is undefined.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a string object that represents the contents of the dictionary, formatted as a property list.

    Declaration

    Swift

    func descriptionWithLocale(_ locale: AnyObject?, indent level: Int) -> String

    Objective-C

    - (NSString *)descriptionWithLocale:(id)locale indent:(NSUInteger)level

    Parameters

    locale

    An object that specifies options used for formatting each of the dictionary’s keys and values; pass nil if you don’t want them formatted.

    On iOS and OS X v10.5 and later, either an instance of NSDictionary or an NSLocale object may be used for locale. On OS X v10.4 and earlier it must be an instance of NSDictionary.

    level

    Specifies a level of indentation, to make the output more readable: the indentation is (4 spaces) * level.

    Return Value

    A string object that represents the contents of the dictionary, formatted as a property list.

    Discussion

    The returned NSString object contains the string representations of each of the dictionary’s entries. descriptionWithLocale:indent: obtains the string representation of a given key or value as follows:

    • If the object is an NSString object, it is used as is.

    • If the object responds to descriptionWithLocale:indent:, that method is invoked to obtain the object’s string representation.

    • If the object responds to descriptionWithLocale:, that method is invoked to obtain the object’s string representation.

    • If none of the above conditions is met, the object’s string representation is obtained by through its description property.

    If each key in the dictionary responds to compare:, the entries are listed in ascending order, by key. Otherwise, the order in which the entries are listed is undefined.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.