NSHashTable 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
NSHashTable.h

Overview

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

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.

Tasks

Initialization

Convenience Constructors

Accessing Content

Manipulating Membership

Comparing Hash Tables

Set Functions

Accessing Pointer Functions

Deprecated Methods

Class Methods

hashTableWithOptions:

Returns a hash table with given pointer functions options.

+ (id)hashTableWithOptions:(NSPointerFunctionsOptions)options
Parameters
options

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

Return Value

A hash table with given pointer functions options.

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

weakObjectsHashTable

Returns a new hash table for storing weak references to its contents.

+ (id)weakObjectsHashTable
Return Value

A new has table that uses the options NSHashTableZeroingWeakMemory and NSPointerFunctionsObjectPersonality and has an initial capacity of 0.

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

Instance Methods

addObject:

Adds a given object to the hash table.

- (void)addObject:(id)object
Parameters
object

The object to add to the hash table.

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

allObjects

Returns an array that contains the hash table’s members.

- (NSArray *)allObjects
Return Value

An array that contains the hash table’s members.

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

anyObject

Returns one of the objects in the hash table.

- (id)anyObject
Return Value

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

Discussion

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

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

containsObject:

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

- (BOOL)containsObject:(id)anObject
Parameters
anObject

The object to test for membership in the hash table.

Return Value

YES if the hash table contains anObject, otherwise NO.

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.

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

count

Returns the number of elements in the hash table.

- (NSUInteger)count
Return Value

The number of elements in the hash table.

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

initWithOptions:capacity:

Returns a hash table initialized with the given attributes.

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

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

initWithPointerFunctions:capacity:

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

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

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

intersectHashTable:

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

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

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

intersectsHashTable:

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

- (BOOL)intersectsHashTable:(NSHashTable *)other
Parameters
other

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

Return Value

YES if other intersects with the receiving hash table, otherwise NO.

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.

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

isEqualToHashTable:

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

- (BOOL)isEqualToHashTable:(NSHashTable *)other
Parameters
other

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

Return Value

YES if the contents of other are equal to the contents of the receiving hash table, otherwise NO.

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.

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

isSubsetOfHashTable:

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

- (BOOL)isSubsetOfHashTable:(NSHashTable *)other
Parameters
other

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

Return Value

YES if every element in the receiving hash table is also present in other, otherwise NO.

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.

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

member:

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

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

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

minusHashTable:

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

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

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

objectEnumerator

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

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

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

pointerFunctions

Returns the pointer functions for the hash table.

- (NSPointerFunctions *)pointerFunctions
Return Value

The pointer functions for the hash table.

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

removeAllObjects

Removes all objects from the hash table.

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

removeObject:

Removes a given object from the hash table.

- (void)removeObject:(id)object
Parameters
object

The object to remove from the hash table.

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

setRepresentation

Returns a set that contains the hash table’s members.

- (NSSet *)setRepresentation
Return Value

A set that contains the hash table’s members.

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

unionHashTable:

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

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

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

Constants

Hash Table Options

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

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

Equal to NSPointerFunctionsStrongMemory.

Available in OS X v10.5 and later.

Declared in NSHashTable.h.

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.

Declared in NSHashTable.h.

NSHashTableCopyIn

Equal to NSPointerFunctionsCopyIn.

Available in OS X v10.5 and later.

Declared in NSHashTable.h.

NSHashTableObjectPointerPersonality

Equal to NSPointerFunctionsObjectPointerPersonality.

Available in OS X v10.5 and later.

Declared in NSHashTable.h.

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.

Declared in NSHashTable.h.