Mac OS X Reference Library Apple Developer Connection spyglass button

NSMapTable Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac 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, in particular to support weak relationships in a garbage-collected environment.

NSMapTable is modeled after NSDictionary but offers different behaviors:

To configure an NSMapTable instance for pointer use, you can: create or initialize it using mapTableWithKeyOptions:valueOptions: or initWithKeyOptions:valueOptions:capacity: and the appropriate NSPointerFunctionsOptions options; or initialize it with initWithKeyPointerFunctions:valuePointerFunctions:capacity: and appropriate instances of NSPointerFunctions. Note that only the options listed in “NSMapTableOptions” guarantee that the rest of the API will work correctly—including copying, archiving, and fast enumeration. If you use other NSPointerFunctions options, the map table may not work correctly, or may not even be initialized correctly.

Tasks

Creating and Initializing a Map Table

Accessing Content

Manipulating Content

Creating a Dictionary Representation

Accessing Pointer Functions

Class Methods

mapTableWithKeyOptions:valueOptions:

Returns a new map table, initialized with the given options

+ (id)mapTableWithKeyOptions:(NSPointerFunctionsOptions)keyOptionsvalueOptions:(NSPointerFunctionsOptions)valueOptions

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

Return Value

A new map table, initialized with the given options.

Availability
See Also
Declared In
NSMapTable.h

mapTableWithStrongToStrongObjects

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

+ (id)mapTableWithStrongToStrongObjects

Return Value

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

Availability
Declared In
NSMapTable.h

mapTableWithStrongToWeakObjects

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

+ (id)mapTableWithStrongToWeakObjects

Return Value

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

Availability
Declared In
NSMapTable.h

mapTableWithWeakToStrongObjects

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

+ (id)mapTableWithWeakToStrongObjects

Return Value

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

Availability
Declared In
NSMapTable.h

mapTableWithWeakToWeakObjects

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

+ (id)mapTableWithWeakToWeakObjects

Return Value

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

Availability
Declared In
NSMapTable.h

Instance Methods

count

Returns the number of key-value pairs in the receiver.

- (NSUInteger)count

Return Value

The number of key-value pairs in the receiver.

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

dictionaryRepresentation

Returns a dictionary representation of the receiver.

- (NSDictionary *)dictionaryRepresentation

Return Value

A dictionary representation of the receiver.

Discussion

The receiver’s contents must be objects.

Availability
  • Available in Mac 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 receiver. 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 Mac OS X v10.5 and later.
See Also
Declared In
NSMapTable.h

initWithKeyPointerFunctions:valuePointerFunctions:capacity:

Returns a map table, initialized with the given functions.

- (id)initWithKeyPointerFunctions:(NSPointerFunctions *)keyFunctionsvaluePointerFunctions:(NSPointerFunctions *)valueFunctionscapacity:(NSUInteger)initialCapacity

Parameters
keyFunctions

The functions the receiver uses to manage keys.

valueFunctions

The functions the receiver uses to manage values.

initialCapacity

The initial capacity of the receiver. 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 Mac OS X v10.5 and later.
Declared In
NSMapTable.h

keyEnumerator

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

- (NSEnumerator *)keyEnumerator

Return Value

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

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 */
}

See also NSFastEnumeration.

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

keyPointerFunctions

Returns the pointer functions the receiver uses to manage keys.

- (NSPointerFunctions *)keyPointerFunctions

Return Value

The pointer functions the receiver uses to manage keys.

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

objectEnumerator

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

- (NSEnumerator *)objectEnumerator

Return Value

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

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 */
}

See also NSFastEnumeration.

Availability
  • Available in Mac 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 Mac OS X v10.5 and later.
Declared In
NSMapTable.h

removeAllObjects

Empties the receiver of its entries.

- (void)removeAllObjects

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

removeObjectForKey:

Removes a given key and its associated value from the receiver.

- (void)removeObjectForKey:(id)aKey

Parameters
aKey

The key to remove.

Discussion

Does nothing if aKey does not exist.

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

setObject:forKey:

Adds a given key-value pair to the receiver.

- (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 Mac OS X v10.5 and later.
Declared In
NSMapTable.h

valuePointerFunctions

Returns the pointer functions the receiver uses to manage values.

- (NSPointerFunctions *)valuePointerFunctions

Return Value

The pointer functions the receiver uses to manage values.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
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
};
typedef NSUInteger NSMapTableOptions;
Constants
NSMapTableStrongMemory

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

Equal to NSPointerFunctionsStrongMemory.

Available in Mac OS X v10.5 and later.

Declared in NSMapTable.h.

NSMapTableZeroingWeakMemory

Specifies a zeroing weak reference from the map table to its contents.

Equal to NSPointerFunctionsZeroingWeakMemory.

Available in Mac OS X v10.5 and later.

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 Mac 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 Mac OS X v10.5 and later.

Declared in NSMapTable.h.



Last updated: 2009-08-14

Did this document help you? Yes It's good, but... Not helpful...