NSMapTable官方文档阅读

NSMapTable

应朋友邀约，翻译关于 NSMapTable 和 NSHashTable 的官方文档，本篇是第一篇。

Overview

NSMapTable 是在 NSDictionary 之后的一个可变集合模型化的类，它们具有以下区别：

1. 主要的差别是 NSMapTable 会在集合里的对象被回收的时候删除此对象来保持对键 和/或 值保持“弱引用”；
2. 当 NSMapTable 添加一个键值对的时候其键或值可以被复制，也可以使用指针标识来进行相等和散列判断；
3. NSMapTable 可以包含任意指针（其内容不被约束为对象）。

你可以将 NSMapTable 实例配置为对任意指针进行操作，而不仅仅是对象，尽管通常会鼓励使用 C 的 API： void * 指针来操作。 （有关详细信息，请参阅管理映射表）基于对象的 API（例如 setObject：forKey :)将无法在不进行类型转换的情况下对无对象指针操作。

配置映射表时，请注意，只有NSMapTableOptions中列出的选项才能保证其余的API能够正常工作，包括复制，归档和快速枚举。虽然其他NSPointerFunctions选项用于某些配置，例如保留任意指针，但并不是所有选项的组合都有效。使用某些组合时映射表可能无法正常工作，甚至可能无法正确初始化。

NOTE： NSMapTable不适用于子类化。

Symbols

Creating and Initializing a Map Table

---

• - (instancetype)initWithKeyOptions:(NSPointerFunctionsOptions)keyOptions valueOptions:(NSPointerFunctionsOptions)valueOptions capacity:(NSUInteger)initialCapacity

  通过指定的选项来初始化NSMapTable对象；

  keyOptions：一个位域，用于指定地NSMapTable中的键的选项。
  valueOptions：一个位域，用于指定地NSMapTable中的值的选项
  initialCapacity：NSMapTable的初始容量。 这只是一个提示; 随后可以根据需要增加和缩小NSMapTable。

  值必须与键中指定的所有索引的条目对应。

---

• + (NSMapTable<KeyType,ObjectType> *)mapTableWithKeyOptions:(NSPointerFunctionsOptions)keyOptions valueOptions:(NSPointerFunctionsOptions)valueOptions

  同上，只不过没有初始指定容量；

---

• - (instancetype)initWithKeyPointerFunctions:(NSPointerFunctions *)keyFunctions valuePointerFunctions:(NSPointerFunctions *)valueFunctions capacity:(NSUInteger)initialCapacity

  使用指定的keyFunctions（NSPointerFunction的一个实例是一个适当的调用函数来管理其他地方持有的指针的引用）来初始化NSMapTable对象；

  keyFunctions：用来管理key的NSPointerFunction；
  valueFunctions：用来管理value的NSPointerFunction；

---

• + (NSMapTable<KeyType,ObjectType> *)strongToStrongObjectsMapTable

  返回一个对key & value有强引用的NSMapTable对象；

---

• + (NSMapTable<KeyType,ObjectType> *)weakToStrongObjectsMapTable

  返回一个对key弱引用，对value强引用的NSMapTable对象
  不建议使用这种映射表，因为NSMapTable可能会在自动调整大小的时候，将weak key对应的value清空；

---

• + (NSMapTable<KeyType,ObjectType> *)strongToWeakObjectsMapTable

  返回一个对value弱引用，对key强引用的NSMapTable对象

---

• + (NSMapTable<KeyType,ObjectType> *)weakToWeakObjectsMapTable

  返回一个对value弱引用，对key也弱引用的NSMapTable对象

Accessing Content

---

• - (ObjectType)objectForKey:(KeyType)aKey

  查找指定key对应的value，如果不存在此key则返回nil;

---

• - (NSEnumerator<KeyType> *)keyEnumerator

  返回一个允许访问映射表中每个键的枚举器对象，。
  以下代码片段说明了如何使用该方法：

    NSEnumerator *enumerator = [myMapTable keyEnumerator];
    id value;
  
    while ((value = [enumerator nextObject])) {
     /* code that acts on the map table's keys */
    }
  

  NOTE：使用快速枚举协议中的方法会更有效；（NSFastEnumeration）

---

• - (NSEnumerator<ObjectType> *)objectEnumerator

  同上，不过是对value的枚举；

---

• @property(readonly) NSUInteger count

  NSMapTable中键值对的个数；

Manipulating Content

---

• - (void)setObject:(ObjectType)anObject forKey:(KeyType)aKey

  在映射表中添加指定的键值对；

---

• - (void)removeObjectForKey:(KeyType)aKey

  删除指定的键值对，如果key不存在则什么都不做；

---

• - (void)removeAllObjects

  删除所有的键值对；

Creating a Dictionary Representation

---

• - (NSDictionary<KeyType,ObjectType> *)dictionaryRepresentation

  返回NSMapTable的NSDictionary表示形式。
  映射表的值和键必须符合NSMutableDictionary中 setObject: forKey: 的所有要求。

Accessing Pointer Functions

---

• @property(readonly, copy) NSPointerFunctions *keyPointerFunctions

  用于管理映射表中key的NSPointerFunctions对象；

---

• @property(readonly, copy) NSPointerFunctions *valuePointerFunctions

  用于管理映射表中value的NSPointerFunctions对象；

Constants

---

• typedef NSUInteger NSMapTableOptions

  用来指定NSMapTable对象中元素（键和值）的行为的常量。

Symbols

1. NSMapTableStrongMemory

   指定对映射表中对应内容的强引用。
   等同于NSPointerFunctionsStrongMemory；

2. NSMapTableZeroingWeakMemory

   指定对映射表中对应内容的归零弱引用。
   这并不完全等同于上面的选项的行为。 在手动和自动引用计数下，对象必须是弱引用安全的; 但是不是所有的对象都是这样的。

3. NSMapTableCopyIn

   允许对映射表中的项目进行分配内存和复制的操作；
   等同于NSPointerFunctionsCopyIn；

4. NSMapTableObjectPointerPersonality

   选项用于控制在将对象添加到集合中时是否调用对象上的 isEqualTo： 和 hash
   方法
   等同于NSPointerFunctionsObjectPointerPersonality

5. NSMapTableWeakMemory

   指定使用弱引用和读写屏障；
   等同于NSMapTableZeroingWeakMemory.

参考

建议配合这篇文章NSMapTable: 不只是一个能放weak指针的 NSDictionary一起阅读，里面有关于每个选项的详细解释