NSMapTable Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.5 and later.
Companion guide
Declared in
NSMapTable.h
Related sample code

Overview

NSMapTable is a mutable collection modeled after NSDictionary but provides different options.

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.

Adopted Protocols

NSCoding
NSCopying
NSFastEnumeration

Tasks

Creating and Initializing a Map Table

Accessing Content

Manipulating Content

Creating a Dictionary Representation

Accessing Pointer Functions

Deprecated Methods

Class Methods

mapTableWithKeyOptions:valueOptions:

Returns a new map table, initialized with the given options

+ (id)mapTableWithKeyOptions:(NSPointerFunctionsOptions)keyOptions valueOptions:(NSPointerFunctionsOptions)valueOptions
Parameters
keyOptions

A bit field that specifies the options for the keys in the map table. For possible values, see “NSMapTableOptions”.

valueOptions

A bit field that specifies the options for the values in the map table. For possible values, see “NSMapTableOptions”.

Return Value

A new map table, initialized with the given options.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

strongToStrongObjectsMapTable

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

+ (id)strongToStrongObjectsMapTable
Return Value

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSMapTable.h

strongToWeakObjectsMapTable

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

+ (id)strongToWeakObjectsMapTable
Return Value

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSMapTable.h

weakToStrongObjectsMapTable

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

+ (id)weakToStrongObjectsMapTable
Return Value

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

Special Considerations

Use of weak-to-strong map tables is not recommended. The strong values for weak keys which get zeroed out continue to be maintained until the map table resizes itself.

Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSMapTable.h

weakToWeakObjectsMapTable

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

+ (id)weakToWeakObjectsMapTable
Return Value

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

Availability
  • Available in OS X v10.8 and later.
Declared In
NSMapTable.h

Instance Methods

count

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

- (NSUInteger)count
Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

dictionaryRepresentation

Returns a dictionary representation of the map table.

- (NSDictionary *)dictionaryRepresentation
Return Value

A dictionary representation of the map table.

Discussion

The map table’s values and keys must conform to all the requirements specified in setObject:forKey: in NSMutableDictionary.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

initWithKeyOptions:valueOptions:capacity:

Returns a map table, initialized with the given options.

- (id)initWithKeyOptions:(NSPointerFunctionsOptions)keys valueOptions:(NSPointerFunctionsOptions)values capacity:(NSUInteger)capacity
Parameters
keys

A bit field that specifies the options for the keys in the map table. For possible values, see “NSMapTableOptions”.

values

A bit field that specifies the options for the values in the map table. For possible values, see “NSMapTableOptions”.

capacity

The initial capacity of the map table. This is just a hint; the map table may subsequently grow and shrink as required.

Return Value

A map table initialized using the given options.

Discussion

values must contain entries at all the indexes specified in keys.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

initWithKeyPointerFunctions:valuePointerFunctions:capacity:

Returns a map table, initialized with the given functions.

- (id)initWithKeyPointerFunctions:(NSPointerFunctions *)keyFunctions valuePointerFunctions:(NSPointerFunctions *)valueFunctions capacity:(NSUInteger)initialCapacity
Parameters
keyFunctions

The functions the map table uses to manage keys.

valueFunctions

The functions the map table uses to manage values.

initialCapacity

The initial capacity of the map table. This is just a hint; the map table may subsequently grow and shrink as required.

Return Value

A map table, initialized with the given functions.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

keyEnumerator

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

- (NSEnumerator *)keyEnumerator
Return Value

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

Discussion

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

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

It is more efficient to use the fast enumeration protocol (see NSFastEnumeration).

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

keyPointerFunctions

Returns the pointer functions the map table uses to manage keys.

- (NSPointerFunctions *)keyPointerFunctions
Return Value

The pointer functions the map table uses to manage keys.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

objectEnumerator

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

- (NSEnumerator *)objectEnumerator
Return Value

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

Discussion

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

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

It is more efficient to use the fast enumeration protocol (see NSFastEnumeration).

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

objectForKey:

Returns a the value associated with a given key.

- (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.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSMapTable.h

removeAllObjects

Empties the map table of its entries.

- (void)removeAllObjects
Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

removeObjectForKey:

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

- (void)removeObjectForKey:(id)aKey
Parameters
aKey

The key to remove.

Discussion

Does nothing if aKey does not exist.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

setObject:forKey:

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

- (void)setObject:(id)anObject forKey:(id)aKey
Parameters
anObject

The value for aKey. This value must not be nil.

aKey

The key for anObject. This value must not be nil.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSMapTable.h

valuePointerFunctions

Returns the pointer functions the map table uses to manage values.

- (NSPointerFunctions *)valuePointerFunctions
Return Value

The pointer functions the map table uses to manage values.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSMapTable.h

Constants

NSMapTableOptions

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

enum {
   NSMapTableStrongMemory             = 0,
   NSMapTableZeroingWeakMemory        = NSPointerFunctionsZeroingWeakMemory,
   NSMapTableCopyIn                   = NSPointerFunctionsCopyIn,
   NSMapTableObjectPointerPersonality = NSPointerFunctionsObjectPointerPersonality,
   NSMapTableWeakMemory               = NSPointerFunctionsWeakMemory
};
typedef NSUInteger NSMapTableOptions;
Constants
NSMapTableStrongMemory

Specifies a strong reference from the map table to its contents.

Equal to NSPointerFunctionsStrongMemory.

Available in OS X v10.5 and later.

Declared in NSMapTable.h.

NSMapTableZeroingWeakMemory

Specifies a zeroing weak reference from the map table to its contents. This option has been deprecated. This option has been superseded by the NSMapTableWeakMemory option, which causes zeroing weak behavior under manual reference counting, automatic reference counting, and garbage collection.

Note that this is not entirely equivalent to and compatible with the previous option's behavior: objects must be weak-reference-safe under manual and automatic reference counting; not all objects are.

Available in OS X v10.5 and later.

Deprecated in OS X v10.8.

Declared in NSMapTable.h.

NSMapTableCopyIn

Use the memory acquire function to allocate and copy items on input (see acquireFunction [NSPointerFunctions]).

Equal to NSPointerFunctionsCopyIn.

Available in OS X v10.5 and later.

Declared in NSMapTable.h.

NSMapTableObjectPointerPersonality

Use shifted pointer hash and direct equality, object description.

Equal to NSPointerFunctionsObjectPointerPersonality.

Available in OS X v10.5 and later.

Declared in NSMapTable.h.

NSMapTableWeakMemory

Uses weak read and write barriers appropriate for ARC or GC. Using NSPointerFunctionsWeakMemory object references will turn to NULL on last release. Equal to NSMapTableZeroingWeakMemory.

Available in OS X v10.8 and later.

Declared in NSMapTable.h.