Mac Developer Library

Developer

Foundation Framework Reference NSMapTable Class Reference

Options
Deployment Target:

On This Page
Language:

NSMapTable

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 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. (See Managing Map Tables for more information) 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.

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.5 and later.
  • Returns a the value associated with a given key.

    Declaration

    Swift

    func objectForKey(_ aKey: AnyObject) -> AnyObject?

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func keyEnumerator() -> NSEnumerator

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func objectEnumerator() -> NSEnumerator

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • count count Property

    The number of key-value pairs in the map table. (read-only)

    Declaration

    Swift

    var count: Int { get }

    Objective-C

    @property(readonly) NSUInteger count

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func setObject(_ anObject: AnyObject, forKey aKey: AnyObject)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func removeObjectForKey(_ aKey: AnyObject)

    Objective-C

    - (void)removeObjectForKey:(id)aKey

    Parameters

    aKey

    The key to remove.

    Discussion

    Does nothing if aKey does not exist.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Empties the map table of its entries.

    Declaration

    Swift

    func removeAllObjects()

    Objective-C

    - (void)removeAllObjects

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a dictionary representation of the map table.

    Declaration

    Swift

    func dictionaryRepresentation() -> [NSObject : AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Deprecation Statement

    Use strongToStrongObjectsMapTable instead.

    Declaration

    Objective-C

    + (id)mapTableWithStrongToStrongObjects

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    Use weakToStrongObjectsMapTable instead.

    Declaration

    Objective-C

    + (id)mapTableWithWeakToStrongObjects

    Return Value

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

    Special Considerations

    NSMapTable objects created using this method do not support weak references under Automatic Reference Counting (ARC).

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    Use strongToWeakObjectsMapTable instead.

    Declaration

    Objective-C

    + (id)mapTableWithStrongToWeakObjects

    Return Value

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

    Special Considerations

    NSMapTable objects created using this method do not support weak references under Automatic Reference Counting (ARC).

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Deprecation Statement

    Use weakToWeakObjectsMapTable instead.

    Declaration

    Objective-C

    + (id)mapTableWithWeakToWeakObjects

    Return Value

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

    Special Considerations

    NSMapTable objects created using this method do not support weak references under Automatic Reference Counting (ARC).

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    typealias NSMapTableOptions = Int

    Objective-C

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

    Constants

    • NSMapTableStrongMemory

      NSMapTableStrongMemory

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

      Equal to NSPointerFunctionsStrongMemory.

      Available in OS X v10.5 and later.

    • NSMapTableZeroingWeakMemory

      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.

    • NSMapTableCopyIn

      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.

    • NSMapTableObjectPointerPersonality

      NSMapTableObjectPointerPersonality

      Use shifted pointer hash and direct equality, object description.

      Equal to NSPointerFunctionsObjectPointerPersonality.

      Available in OS X v10.5 and later.

    • NSMapTableWeakMemory

      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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.