Class

NSMapTable

A collection similar to a dictionary, but with a broader range of available memory semantics.

Declaration

@interface NSMapTable<__covariant KeyType, __covariant ObjectType> : NSObject

Overview

The map table is modeled after NSDictionary with the following differences:

  • Keys and/or values are optionally held “weakly” such that entries are removed when one of the objects is reclaimed.

  • Its keys or values may be copied on input or may use pointer identity for equality and hashing.

  • It can contain arbitrary pointers (its contents are not constrained to being objects).

You can configure an NSMapTable instance to operate on arbitrary pointers and not just objects, although typically you are encouraged to use the C function API for void * pointers. The object-based API (such as setObject:forKey:) will not work for non-object pointers without type-casting.

When configuring map tables, note that only the options listed in NSMapTableOptions guarantee that the rest of the API will work correctly—including copying, archiving, and fast enumeration. While other NSPointerFunctions options are used for certain configurations, such as to hold arbitrary pointers, not all combinations of the options are valid. With some combinations the map table may not work correctly, or may not even be initialized correctly.

Subclassing Notes

NSMapTable is not suitable for subclassing.

Topics

Creating and Initializing a Map Table

- initWithKeyOptions:valueOptions:capacity:

Returns a map table, initialized with the given options.

+ mapTableWithKeyOptions:valueOptions:

Returns a new map table, initialized with the given options

- initWithKeyPointerFunctions:valuePointerFunctions:capacity:

Returns a map table, initialized with the given functions.

+ strongToStrongObjectsMapTable

Returns a new map table object which has strong references to the keys and values.

+ weakToStrongObjectsMapTable

Returns a new map table object which has weak references to the keys and strong references to the values.

+ strongToWeakObjectsMapTable

Returns a new map table object which has strong references to the keys and weak references to the values.

+ weakToWeakObjectsMapTable

Returns a new map table object which has weak references to the keys and values.

NSMapTableOptions

Constants used as components in a bitfield to specify the behavior of elements (keys and values) in an NSMapTable object.

Accessing Content

- objectForKey:

Returns a the value associated with a given key.

- keyEnumerator

Returns an enumerator object that lets you access each key in the map table.

- objectEnumerator

Returns an enumerator object that lets you access each value in the map table.

count

The number of key-value pairs in the map table.

Manipulating Content

- setObject:forKey:

Adds a given key-value pair to the map table.

- removeObjectForKey:

Removes a given key and its associated value from the map table.

- removeAllObjects

Empties the map table of its entries.

Creating a Dictionary Representation

- dictionaryRepresentation

Returns a dictionary representation of the map table.

Accessing Pointer Functions

keyPointerFunctions

The pointer functions the map table uses to manage keys.

valuePointerFunctions

The pointer functions the map table uses to manage values.

NSPointerFunctions

An instance of NSPointerFunctions defines callout functions appropriate for managing a pointer reference held somewhere else.

Deprecated

+ mapTableWithStrongToStrongObjects

Returns a new map table object which has strong references to the keys and values.

Deprecated
+ mapTableWithWeakToStrongObjects

Returns a new map table object which has weak references to the keys and strong references to the values.

Deprecated
+ mapTableWithStrongToWeakObjects

Returns a new map table object which has strong references to the keys and weak references to the values.

Deprecated
+ mapTableWithWeakToWeakObjects

Returns a new map table object which has weak references to the keys and values.

Deprecated

Relationships

Inherits From

See Also

Pointer Collections

NSPointerArray

A collection similar to an array, but with a broader range of available memory semantics.

NSHashTable

A collection similar to a set, but with broader range of available memory semantics.