NSMapTable Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 6.0 and later. |
| Companion guide | |
| Declared in | NSMapTable.h |
Overview
NSMapTable is a mutable collection modeled after NSDictionary but provides different options.
The major option is to have keys and/or values held “weakly” in a manner 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
NSMapTableinstance to operate on arbitrary pointers and not just objects, although typically you are encouraged to use the C function API forvoid *pointers. (See “Managing Map Tables” in Foundation Functions Reference for more information) The object-based API (such assetObject: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.
Adopted Protocols
Tasks
Creating and Initializing a Map Table
-
– initWithKeyOptions:valueOptions:capacity: -
+ mapTableWithKeyOptions:valueOptions: -
– initWithKeyPointerFunctions:valuePointerFunctions:capacity: -
+ strongToStrongObjectsMapTable -
+ weakToStrongObjectsMapTable -
+ strongToWeakObjectsMapTable -
+ weakToWeakObjectsMapTable
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
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
- Available in iOS 6.0 and later.
See Also
Declared In
NSMapTable.hstrongToStrongObjectsMapTable
Returns a new map table object which has strong references to the keys and values.
Return Value
A new map table object which has strong references to the keys and values.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hstrongToWeakObjectsMapTable
Returns a new map table object which has strong references to the keys and weak references to the values.
Return Value
A new map table object which has strong references to the keys and weak references to the values.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hweakToStrongObjectsMapTable
Returns a new map table object which has weak references to the keys and strong references to the values.
Return Value
A new map table object which has weak references to the keys and strong references to the values.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hweakToWeakObjectsMapTable
Returns a new map table object which has weak references to the keys and values.
Return Value
A new map table object which has weak references to the keys and values.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hInstance Methods
count
Returns the number of key-value pairs in the map table.
Return Value
The number of key-value pairs in the map table.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hdictionaryRepresentation
Returns a dictionary representation of the map table.
Return Value
A dictionary representation of the map table.
Discussion
The map table’s contents must be objects.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hinitWithKeyOptions:valueOptions:capacity:
Returns a map table, initialized with the given options.
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 iOS 6.0 and later.
See Also
Declared In
NSMapTable.hinitWithKeyPointerFunctions:valuePointerFunctions:capacity:
Returns a map table, initialized with the given functions.
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 iOS 6.0 and later.
Declared In
NSMapTable.hkeyEnumerator
Returns an enumerator object that lets you access each key in the map table.
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 iOS 6.0 and later.
Declared In
NSMapTable.hkeyPointerFunctions
Returns the pointer functions the map table uses to manage keys.
Return Value
The pointer functions the map table uses to manage keys.
Availability
- Available in iOS 6.0 and later.
See Also
Declared In
NSMapTable.hobjectEnumerator
Returns an enumerator object that lets you access each value in the map table.
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 iOS 6.0 and later.
Declared In
NSMapTable.hobjectForKey:
Returns a the value associated with a given key.
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 iOS 6.0 and later.
Declared In
NSMapTable.hremoveAllObjects
Empties the map table of its entries.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hremoveObjectForKey:
Removes a given key and its associated value from the map table.
Parameters
- aKey
The key to remove.
Discussion
Does nothing if aKey does not exist.
Availability
- Available in iOS 6.0 and later.
Declared In
NSMapTable.hsetObject:forKey:
Adds a given key-value pair to the map table.
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 iOS 6.0 and later.
Declared In
NSMapTable.hvaluePointerFunctions
Returns the pointer functions the map table uses to manage values.
Return Value
The pointer functions the map table uses to manage values.
Availability
- Available in iOS 6.0 and later.
See Also
Declared In
NSMapTable.hConstants
NSMapTableOptions
Constants used as components in a bitfield to specify the behavior of elements (keys and values) in an NSMapTable object.
enum {
NSMapTableStrongMemory = 0,
NSMapTableCopyIn = NSPointerFunctionsCopyIn,
NSMapTableObjectPointerPersonality = NSPointerFunctionsObjectPointerPersonality,
NSMapTableWeakMemory = NSPointerFunctionsWeakMemory
};
typedef NSUInteger NSMapTableOptions;
Constants
NSMapTableStrongMemorySpecifies a strong reference from the map table to its contents.
Equal to
NSPointerFunctionsStrongMemory.Available in iOS 6.0 and later.
Declared in
NSMapTable.h.NSMapTableCopyInUse the memory acquire function to allocate and copy items on input (see
acquireFunction[NSPointerFunctions]).Equal to
NSPointerFunctionsCopyIn.Available in iOS 6.0 and later.
Declared in
NSMapTable.h.NSMapTableObjectPointerPersonalityUse shifted pointer hash and direct equality, object description.
Equal to
NSPointerFunctionsObjectPointerPersonality.Available in iOS 6.0 and later.
Declared in
NSMapTable.h.NSMapTableWeakMemoryUses weak read and write barriers appropriate for ARC or GC. Using
NSPointerFunctionsWeakMemoryobject references will turn toNULLon last release. Equal toNSMapTableZeroingWeakMemory.Available in iOS 6.0 and later.
Declared in
NSMapTable.h.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)