NSDictionary.h

/*  NSDictionary.h
    Copyright (c) 1994-2013, Apple Inc. All rights reserved.
*/

#import <Foundation/NSObject.h>
#import <Foundation/NSEnumerator.h>

@class NSArray, NSSet, NSString, NSURL;

/****************   Immutable Dictionary    ****************/

#pragma mark - 不可变字典

@interface NSDictionary : NSObject <NSCopying, NSMutableCopying, NSSecureCoding, NSFastEnumeration>

- (NSUInteger)count;                            // 键值对个数
- (id)objectForKey:(id)aKey;                    // 取出某个key对应的值
- (NSEnumerator *)keyEnumerator;                // key的迭代器

@end

@interface NSDictionary (NSExtendedDictionary)

- (NSArray *)allKeys;                           // 取出字典的所有key，并放到数组中
- (NSArray *)allKeysForObject:(id)anObject;     // 取出指向和某一对象值相同的key，放到数组中的
- (NSArray *)allValues;                         // 取出所有值
- (NSString *)description;                      // 重写父类的description方法
- (NSString *)descriptionInStringsFileFormat;
- (NSString *)descriptionWithLocale:(id)locale;
- (NSString *)descriptionWithLocale:(id)locale indent:(NSUInteger)level;
- (BOOL)isEqualToDictionary:(NSDictionary *)otherDictionary; // 判断两个字典是否相同
- (NSEnumerator *)objectEnumerator;                          // 值迭代器
- (NSArray *)objectsForKeys:(NSArray *)keys notFoundMarker:(id)marker;
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile; // 写入文件
- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically; // 写入URL，如果某些类型的原子性不可用，将不会采用原子性写入。

- (NSArray *)keysSortedByValueUsingSelector:(SEL)comparator; // 排序

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

- (id)objectForKeyedSubscript:(id)key NS_AVAILABLE(10_8, 6_0);

#if NS_BLOCKS_AVAILABLE
// 使用迭代器对字典进行遍历
- (void)enumerateKeysAndObjectsUsingBlock:(void (^)(id key, id obj, BOOL *stop))block NS_AVAILABLE(10_6, 4_0);

- (void)enumerateKeysAndObjectsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(id key, id obj, BOOL *stop))block NS_AVAILABLE(10_6, 4_0);

// 对键进行排序，并返回排序后的数组
- (NSArray *)keysSortedByValueUsingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);
- (NSArray *)keysSortedByValueWithOptions:(NSSortOptions)opts usingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);

- (NSSet *)keysOfEntriesPassingTest:(BOOL (^)(id key, id obj, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);
- (NSSet *)keysOfEntriesWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(id key, id obj, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);
#endif

@end

@interface NSDictionary (NSDictionaryCreation)

+ (instancetype)dictionary;                             // 类方法创建字典
+ (instancetype)dictionaryWithObject:(id)object forKey:(id <NSCopying>)key;    // 按照对应的键值创建字典
#if TARGET_OS_WIN32
+ (instancetype)dictionaryWithObjects:(const id [])objects forKeys:(const id [])keys count:(NSUInteger)cnt;
#else
+ (instancetype)dictionaryWithObjects:(const id [])objects forKeys:(const id <NSCopying> [])keys count:(NSUInteger)cnt;
#endif
+ (instancetype)dictionaryWithObjectsAndKeys:(id)firstObject, ... NS_REQUIRES_NIL_TERMINATION;
+ (instancetype)dictionaryWithDictionary:(NSDictionary *)dict;
+ (instancetype)dictionaryWithObjects:(NSArray *)objects forKeys:(NSArray *)keys;

- (instancetype)init;   /* designated initializer */
#if TARGET_OS_WIN32
- (instancetype)initWithObjects:(const id [])objects forKeys:(const id [])keys count:(NSUInteger)cnt;
#else
- (instancetype)initWithObjects:(const id [])objects forKeys:(const id <NSCopying> [])keys count:(NSUInteger)cnt;   /* designated initializer */
#endif

- (instancetype)initWithObjectsAndKeys:(id)firstObject, ... NS_REQUIRES_NIL_TERMINATION;
- (instancetype)initWithDictionary:(NSDictionary *)otherDictionary;
- (instancetype)initWithDictionary:(NSDictionary *)otherDictionary copyItems:(BOOL)flag;
- (instancetype)initWithObjects:(NSArray *)objects forKeys:(NSArray *)keys;

+ (id /* NSDictionary * */)dictionaryWithContentsOfFile:(NSString *)path;   // 从文件创建字典
+ (id /* NSDictionary * */)dictionaryWithContentsOfURL:(NSURL *)url;        // 从URL创建字典
- (id /* NSDictionary * */)initWithContentsOfFile:(NSString *)path;         // 从文件初始化字典
- (id /* NSDictionary * */)initWithContentsOfURL:(NSURL *)url;              // 从URL初始化字典

@end

/****************   Mutable Dictionary  ****************/

@interface NSMutableDictionary : NSDictionary

- (void)removeObjectForKey:(id)aKey;                        // 删除对应键的键值对
- (void)setObject:(id)anObject forKey:(id <NSCopying>)aKey;

@end

@interface NSMutableDictionary (NSExtendedMutableDictionary)

- (void)addEntriesFromDictionary:(NSDictionary *)otherDictionary;
- (void)removeAllObjects;                                   // 删除所有键值对
- (void)removeObjectsForKeys:(NSArray *)keyArray;           // 删除与数组中对应元素相同的键对应的键值对
- (void)setDictionary:(NSDictionary *)otherDictionary;
- (void)setObject:(id)obj forKeyedSubscript:(id <NSCopying>)key NS_AVAILABLE(10_8, 6_0);

@end

@interface NSMutableDictionary (NSMutableDictionaryCreation)

+ (instancetype)dictionaryWithCapacity:(NSUInteger)numItems;

- (instancetype)init;   /* designated initializer */
- (instancetype)initWithCapacity:(NSUInteger)numItems;  /* designated initializer */

@end

@interface NSDictionary (NSSharedKeySetDictionary)

/*  Use this method to create a key set to pass to +dictionaryWithSharedKeySet:.
 The keys are copied from the array and must be copyable.
 If the array parameter is nil or not an NSArray, an exception is thrown.
 If the array of keys is empty, an empty key set is returned.
 The array of keys may contain duplicates, which are ignored (it is undefined which object of each duplicate pair is used).
 As for any usage of hashing, is recommended that the keys have a well-distributed implementation of -hash, and the hash codes must satisfy the hash/isEqual: invariant.
 Keys with duplicate hash codes are allowed, but will cause lower performance and increase memory usage.
 */
+ (id)sharedKeySetForKeys:(NSArray *)keys NS_AVAILABLE(10_8, 6_0);

@end

@interface NSMutableDictionary (NSSharedKeySetDictionary)

/*  Create a mutable dictionary which is optimized for dealing with a known set of keys.
 Keys that are not in the key set can still be set into the dictionary, but that usage is not optimal.
 As with any dictionary, the keys must be copyable.
 If keyset is nil, an exception is thrown.
 If keyset is not an object returned by +sharedKeySetForKeys:, an exception is thrown.
 */
+ (id /* NSMutableDictionary * */)dictionaryWithSharedKeySet:(id)keyset NS_AVAILABLE(10_8, 6_0);

@end