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.
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
NSHashTableinstance to operate on arbitrary pointers and not just objects, although typically you are encouraged to use the C function API forvoid *pointers. (See “Hash Tables” in Foundation Functions Reference for more information) The object-based API (such asaddObject:) 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.
Tasks
Initialization
Convenience Constructors
Accessing Content
Manipulating Membership
Comparing Hash Tables
Set Functions
Accessing Pointer Functions
Deprecated Methods
-
+ hashTableWithWeakObjectsDeprecated in OS X v10.8
Class Methods
hashTableWithOptions:
Returns a hash table with given pointer functions 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.hweakObjectsHashTable
Returns a new hash table for storing weak references to its contents.
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.hInstance Methods
addObject:
Adds a given object to the hash table.
Parameters
- object
The object to add to the hash table.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hallObjects
Returns an array that contains the hash table’s members.
Return Value
An array that contains the hash table’s members.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hanyObject
Returns one of the objects in the hash table.
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.hcontainsObject:
Returns a Boolean value that indicates whether the hash table contains a given object.
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.hcount
Returns the number of elements in the hash table.
Return Value
The number of elements in the hash table.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hinitWithOptions:capacity:
Returns a hash table initialized with the given attributes.
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.hinitWithPointerFunctions:capacity:
Returns a hash table initialized with the given functions and capacity.
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.hintersectHashTable:
Removes from the receiving hash table each element that isn’t a member of another given hash table.
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.hintersectsHashTable:
Returns a Boolean value that indicates whether a given hash table intersects with the receiving hash table.
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.hisEqualToHashTable:
Returns a Boolean value that indicates whether a given hash table is equal to the receiving hash table.
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.hisSubsetOfHashTable:
Returns a Boolean value that indicates whether every element in the receiving hash table is also present in another given hash table.
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.hmember:
Determines whether the hash table contains a given object, and returns that object if it is present
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.hminusHashTable:
Removes each element in another given hash table from the receiving hash table, if present.
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.hobjectEnumerator
Returns an enumerator object that lets you access each object in the hash table.
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.hpointerFunctions
Returns the pointer functions for the hash table.
Return Value
The pointer functions for the hash table.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hremoveAllObjects
Removes all objects from the hash table.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hremoveObject:
Removes a given object from the hash table.
Parameters
- object
The object to remove from the hash table.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hsetRepresentation
Returns a set that contains the hash table’s members.
Return Value
A set that contains the hash table’s members.
Availability
- Available in OS X v10.5 and later.
Declared In
NSHashTable.hunionHashTable:
Adds each element in another given hash table to the receiving hash table, if not present.
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.hConstants
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
NSHashTableStrongMemoryEqual to
NSPointerFunctionsStrongMemory.Available in OS X v10.5 and later.
Declared in
NSHashTable.h.NSHashTableZeroingWeakMemoryThis option has been deprecated. Instead use the
NSHashTableWeakMemoryoption. Equal toNSPointerFunctionsZeroingWeakMemory.Note that
NSHashTableWeakMemoryis 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.
Declared in
NSHashTable.h.NSHashTableCopyInEqual to
NSPointerFunctionsCopyIn.Available in OS X v10.5 and later.
Declared in
NSHashTable.h.NSHashTableObjectPointerPersonalityEqual to
NSPointerFunctionsObjectPointerPersonality.Available in OS X v10.5 and later.
Declared in
NSHashTable.h.NSHashTableWeakMemoryEqual to
NSPointerFunctionsWeakMemory. Uses weak read and write barriers appropriate for ARC or GC. Using NSPointerFunctionsWeakMemory object references will turn toNULLon last release.Available in OS X v10.8 and later.
Declared in
NSHashTable.h.
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)