Mac Developer Library

Developer

Foundation Framework Reference NSHashTable Class Reference

Options
Deployment Target:

On This Page
Language:

NSHashTable

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.5 and later.

NSHashTable is modeled after NSSet but provides different options, in particular to support weak relationships.

  • It can hold weak references to its members.

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

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

    You can configure an NSHashTable 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 Hash Tables for more information) The object-based API (such as addObject:) will not work for non-object pointers without type-casting.

Because of its options, NSHashTable is not a set because it can behave differently (for example, if pointer equality is specified two isEqual: strings will both be entered).

When configuring hash tables, note that only the options listed in Hash Table Options 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 hash table may not work correctly, or may not even be initialized correctly.

Subclassing Notes

NSHashTable is not suitable for subclassing.

  • Returns a hash table initialized with the given attributes.

    Declaration

    Swift

    init(options options: NSPointerFunctionsOptions, capacity capacity: Int)

    Objective-C

    - (instancetype)initWithOptions:(NSPointerFunctionsOptions)options capacity:(NSUInteger)capacity

    Parameters

    options

    A bit field that specifies the options for the elements in the hash table. For possible values, see “Hash Table Options”.

    capacity

    The initial number of elements the hash table can hold.

    Return Value

    A hash table initialized with options specified by options and initial capacity of capacity.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a hash table initialized with the given functions and capacity.

    Declaration

    Swift

    init(pointerFunctions functions: NSPointerFunctions, capacity initialCapacity: Int)

    Objective-C

    - (instancetype)initWithPointerFunctions:(NSPointerFunctions *)functions capacity:(NSUInteger)initialCapacity

    Parameters

    functions

    The pointer functions for the new hash table.

    initialCapacity

    The initial capacity of the hash table.

    Return Value

    A hash table initialized with the given functions and capacity.

    Discussion

    Hash tables allocate additional memory as needed, so initialCapacity simply establishes the object’s initial capacity.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • The hash table’s members. (read-only)

    Declaration

    Swift

    var allObjects: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *allObjects

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • anyObject anyObject Property

    One of the objects in the hash table. (read-only)

    Declaration

    Swift

    var anyObject: AnyObject? { get }

    Objective-C

    @property(nonatomic, readonly) id anyObject

    Discussion

    One of the objects in the hash table, or nil if the hash table contains no objects.

    The object returned is chosen at the hash table’s convenience—the selection is not guaranteed to be random.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a Boolean value that indicates whether the hash table contains a given object.

    Declaration

    Swift

    func containsObject(_ anObject: AnyObject) -> Bool

    Objective-C

    - (BOOL)containsObject:(id)anObject

    Parameters

    anObject

    The object to test for membership in the hash table.

    Return Value

    YEStrue if the hash table contains anObject, otherwise NOfalse.

    Discussion

    The equality test used depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • count count Property

    The number of elements in the hash 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.

  • Determines whether the hash table contains a given object, and returns that object if it is present

    Declaration

    Swift

    func member(_ object: AnyObject) -> AnyObject?

    Objective-C

    - (id)member:(id)object

    Parameters

    object

    The object to test for membership in the hash table.

    Return Value

    If object is a member of the hash table, returns object, otherwise returns nil.

    Discussion

    The equality test used depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    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 object in the hash table.

    Declaration

    Swift

    func objectEnumerator() -> NSEnumerator

    Objective-C

    - (NSEnumerator *)objectEnumerator

    Return Value

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

    Discussion

    The following code fragment illustrates how you can use this method.

    • NSEnumerator *enumerator = [myHashTable objectEnumerator];
    • id value;
    • while ((value = [enumerator nextObject])) {
    • /* code that acts on the hash 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.

  • A set that contains the hash table’s members. (read-only)

    Declaration

    Swift

    var setRepresentation: Set<NSObject> { get }

    Objective-C

    @property(readonly, copy) NSSet *setRepresentation

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Adds a given object to the hash table.

    Declaration

    Swift

    func addObject(_ object: AnyObject)

    Objective-C

    - (void)addObject:(id)object

    Parameters

    object

    The object to add to the hash table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Removes all objects from the hash table.

    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.

  • Removes a given object from the hash table.

    Declaration

    Swift

    func removeObject(_ object: AnyObject)

    Objective-C

    - (void)removeObject:(id)object

    Parameters

    object

    The object to remove from the hash table.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a Boolean value that indicates whether a given hash table intersects with the receiving hash table.

    Declaration

    Swift

    func intersectsHashTable(_ other: NSHashTable) -> Bool

    Objective-C

    - (BOOL)intersectsHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table with which to compare the receiving hash table.

    Return Value

    YEStrue if other intersects with the receiving hash table, otherwise NOfalse.

    Discussion

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Removes from the receiving hash table each element that isn’t a member of another given hash table.

    Declaration

    Swift

    func intersectHashTable(_ other: NSHashTable)

    Objective-C

    - (void)intersectHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table with which to perform the intersection.

    Discussion

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a Boolean value that indicates whether a given hash table is equal to the receiving hash table.

    Declaration

    Swift

    func isEqualToHashTable(_ other: NSHashTable) -> Bool

    Objective-C

    - (BOOL)isEqualToHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table with which to compare the receiving hash table.

    Return Value

    YEStrue if the contents of other are equal to the contents of the receiving hash table, otherwise NOfalse.

    Discussion

    Two hash tables have equal contents if they each have the same number of members and if each member of one hash table is present in the other.

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Returns a Boolean value that indicates whether every element in the receiving hash table is also present in another given hash table.

    Declaration

    Swift

    func isSubsetOfHashTable(_ other: NSHashTable) -> Bool

    Objective-C

    - (BOOL)isSubsetOfHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table with which to compare the receiving hash table.

    Return Value

    YEStrue if every element in the receiving hash table is also present in other, otherwise NOfalse.

    Discussion

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Removes each element in another given hash table from the receiving hash table, if present.

    Declaration

    Swift

    func minusHashTable(_ other: NSHashTable)

    Objective-C

    - (void)minusHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table of elements to remove from the receiving hash table.

    Discussion

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Adds each element in another given hash table to the receiving hash table, if not present.

    Declaration

    Swift

    func unionHashTable(_ other: NSHashTable)

    Objective-C

    - (void)unionHashTable:(NSHashTable *)other

    Parameters

    other

    The hash table of elements to add to the receiving hash table.

    Discussion

    The equality test used for members depends on the personality option selected. For instance, choosing the NSPointerFunctionsObjectPersonality option will use isEqual: to determine equality. See NSPointerFunctionsOptions for more information on personality options and their corresponding equality tests.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • The pointer functions for the hash table. (read-only)

    Declaration

    Swift

    @NSCopying var pointerFunctions: NSPointerFunctions { get }

    Objective-C

    @property(readonly, copy) NSPointerFunctions *pointerFunctions

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.5 and later.

  • Components in a bit-field to specify the behavior of elements in an NSHashTable object.

    Declaration

    Swift

    typealias NSHashTableOptions = Int

    Objective-C

    enum { NSHashTableStrongMemory = 0, NSHashTableZeroingWeakMemory = NSPointerFunctionsZeroingWeakMemory, NSHashTableCopyIn = NSPointerFunctionsCopyIn, NSHashTableObjectPointerPersonality = NSPointerFunctionsObjectPointerPersonality, NSHashTableWeakMemory = NSPointerFunctionsWeakMemory }; typedef NSUInteger NSHashTableOptions;

    Constants

    • NSHashTableStrongMemory

      NSHashTableStrongMemory

      Available in OS X v10.5 and later.

    • NSHashTableZeroingWeakMemory

      NSHashTableZeroingWeakMemory

      This option has been deprecated. Instead use the NSHashTableWeakMemory option. Equal to NSPointerFunctionsZeroingWeakMemory.

      Note that NSHashTableWeakMemory 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.

    • NSHashTableCopyIn

      NSHashTableCopyIn

      Available in OS X v10.5 and later.

    • NSHashTableObjectPointerPersonality

      NSHashTableObjectPointerPersonality

      Available in OS X v10.5 and later.

    • NSHashTableWeakMemory

      NSHashTableWeakMemory

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

      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.