NSDictionary

NSDictionary Mac OS X 10.0

This class manages a collection of objects as key-value pairs: objects are identified by a unique key within the dictionary. A key-value pair within a dictionary is called an entry. NSDictionary is an immutable class whose contents cannot be altered after they have been initially set. If you need a mutable dictionary, use NSMutableDictionary instead. A dictionary key is typically an NSString, but according to the API the key can be any object that is type id. The fact that a key can be an object of any type opens the way for interesting design possibilities in Cocoa.

NSDictionary has three primitive methods upon which the rest of the API is based. They are count, objectForKey:, and keyEnumerator. The count method returns the number of objects contained in the dictionary. The method objectForKey: is used to access an object in the dictionary. Finally, keyEnumerator will return an NSEnumerator object that will enumerate the keys of the dictionary. In addition to keyEnumerator, NSDictionary responds to objectEnumerator for enumerating the contents of the dictionary. Note that there is no order in a dictionary as there is in an array. When enumerating the contents of a dictionary, there is no guarantee regarding the order that member objects will be returned by the enumerator.

Often we want to send a message to each member of a collection. NSDictionary provides a method that save us from the burden of having to enumerate the contents of the dictionary and send the message manually. This method is makeObjectsPerformSelector:, which will cause the method matching the selector to be invoked in each member of the collection. If you need to invoke a method that takes an argument, then use the method makeObjectsPerformSelector:withObject:.

NSDictionary is toll-free bridged with the Core Foundation type CFDictionary. As such, NSDictionary objects can be used interchangeably with the CFDictionary pointer type, CFDictionaryRef.

figs/cocn_1330.gif

@interface NSDictionary : NSObject <NSCoding, NSCopying, NSMutableCopying>
 // Convenience Constructors
   + (id)dictionary;
   + (id)dictionaryWithContentsOfFile:(NSString *)path;
   + (id)dictionaryWithContentsOfURL:(NSURL *)url;
   + (id)dictionaryWithDictionary:(NSDictionary *)dict;
   + (id)dictionaryWithObject:(id)object forKey:(id)key;
   + (id)dictionaryWithObjects:(NSArray *)objects forKeys:(NSArray *)keys;
   + (id)dictionaryWithObjects:(id *)objects forKeys:(id *)keys count:(unsigned)count;
   + (id)dictionaryWithObjectsAndKeys:(id)firstObject, ...;
 // Initializers
   - (id)initWithContentsOfFile:(NSString *)path;
   - (id)initWithContentsOfURL:(NSURL *)url;
   - (id)initWithDictionary:(NSDictionary *)otherDictionary;
   - (id)initWithDictionary:(NSDictionary *)otherDictionary copyItems:(BOOL)aBool;
   - (id)initWithObjects:(NSArray *)objects forKeys:(NSArray *)keys;
   - (id)initWithObjects:(id *)objects forKeys:(id *)keys count:(unsigned)count;
   - (id)initWithObjectsAndKeys:(id)firstObject, ...;
 // Instance Methods
   - (NSArray *)allKeys;
   - (NSArray *)allKeysForObject:(id)anObject;
   - (NSArray *)allValues;
   - (unsigned)count;
   - (NSString *)description;
   - (NSString *)descriptionInStringsFileFormat;
   - (NSString *)descriptionWithLocale:(NSDictionary *)locale;
   - (NSString *)descriptionWithLocale:(NSDictionary *)locale indent:(unsigned)level;
   - (NSDate *)fileCreationDate;
   - (BOOL)fileExtensionHidden;
   - (NSNumber *)fileGroupOwnerAccountID;
   - (NSString *)fileGroupOwnerAccountName;
   - (OSType)fileHFSCreatorCode;
   - (OSType)fileHFSTypeCode;
   - (BOOL)fileIsAppendOnly;
   - (BOOL)fileIsImmutable;
   - (NSDate *)fileModificationDate;
   - (NSNumber *)fileOwnerAccountID;
   - (NSString *)fileOwnerAccountName;
   - (unsigned long)filePosixPermissions;
   - (unsigned long long)fileSize;
   - (unsigned long)fileSystemFileNumber;
   - (unsigned long)fileSystemNumber;
   - (NSString *)fileType;
   - (BOOL)isEqualToDictionary:(NSDictionary *)otherDictionary;
   - (NSEnumerator *)keyEnumerator;
   - (NSArray *)keysSortedByValueUsingSelector:(SEL)comparator;
   - (NSEnumerator *)objectEnumerator;
   - (id)objectForKey:(id)aKey;
   - (NSArray *)objectsForKeys:(NSArray *)keys notFoundMarker:(id)marker;
   - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
   - (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically;
 // Methods Implementing NSCoding
   - (void)encodeWithCoder:(NSCoder *)aCoder;
   - (id)initWithCoder:(NSCoder *)aDecoder;
 // Methods Implementing NSCopying
   - (id)copyWithZone:(NSZone *)zone;
 // Methods Implementing NSMutableCopying
   - (id)mutableCopyWithZone:(NSZone *)zone;

Subclasses

NSMutableDictionary



    Part II: API Quick Reference
    Chapter 13. Foundation Classes