< Previous PageNext Page > Hide TOC

Sets: Unordered Collections of Objects

A set is an unordered collection of objects. Cocoa provides three classes to represent sets. An NSSet object is a static unordered collection of objects. You establish a static set’s entries when it’s created, and thereafter you cannot remove, replace, or add to them. NSMutableSet, a subclass of NSSet, is a dynamic set of objects. A dynamic—or mutable—set allows the addition and deletion of entries at any time, automatically allocating memory as needed. NSMapTableis similar to NSMutableSet (although it does not inherit from NSSet) in that represents a dynamic set of objects, but it provides additional features for memory management of its contents.

Contents:

Set Fundamentals
Mutable Sets
Using Sets


Set Fundamentals

You can use sets as an alternative to arrays when the order of elements isn’t important and performance in testing whether an object is contained in the set is a consideration. While arrays are ordered, testing them for membership is slower than testing sets.

When using sets in Objective-C code, the objects in a set must respond to the NSObject protocol methods hash and isEqual: (see the NSObject protocol for more information). Note that if mutable objects are stored in a set, either the hash method of the objects shouldn’t depend on the internal state of the mutable objects or the mutable objects shouldn’t be modified while they’re in the set (note that it can be difficult to know whether or not a given object is in a collection).

NSSet provides a number of initializer methods such as setWithObjects: and initWithArray: that return an NSSet object containing the elements (if any) you pass in as arguments. Objects added to a set are not copied (unless you pass YES as the argument to initWithSet:copyItems:); rather, an object is added directly to a set. In a managed memory environment, an object receives a retain message when it’s added; in a garbage collected environment, it is strongly referenced. The set method is a convenience method to create an empty immutable set.

Mutable Sets

You can create an NSMutableSet object using any of the initializers provided by NSSet. You can create an NSMutableSet object from an instance of NSSet (or vice versa) using setWithSet: or initWithSet:.

NSMutableSet provides methods for adding objects to a set: addObject: adds a single object to the set. addObjectsFromArray: adds all objects from a specified array to the set. And unionSet: adds all the objects from another set.

NSMutableSet provides these methods to remove objects from a set: intersectSet:, removeAllObjects, removeObject:, and minusSet: .

In a managed memory environment, when an object is removed from a mutable set it receives a release message. This means that if a set is the only owner of an object, then (by standard rules of memory management) the object is deallocated when it is removed. If you want to use the object after its removal, you should therefore typically send it a retain message before it’s removed from the set. For example, if in the following example aSet is the only owner of anObject, the third statement below would result in a run-time error:

id anObject = [aSet anyObject];
[aSet removeObject:anObject];
// if no object other than aSet owned anObject, the next line causes a crash
[anObject someMessage];

If you want to use an object after removing it from a set, you should retain it first as shown in the following example:

id anObject = [[aSet anyObject] retain];
[aSet removeObject:anObject];
[anObject someMessage];
// remember to send anObject a release message when you have finished with it

Using Sets

NSSet provides methods for querying the elements of the set. allObjects returns an array containing the objects in a set. anyObject returns some object in the set. count returns the number of objects currently in the set. member: returns the object in the set that is equal to a specified object. Additionally, intersectsSet: tests for set intersection, isEqualToSet: tests for set equality, and isSubsetOfSet: tests for one set being a subset of another.

The NSSet method objectEnumerator lets you traverse elements of the set one by one. And the Objective-C methods makeObjectsPerformSelector: and makeObjectsPerformSelector:withObject: provides for sending messages to individual objects in the set.



< Previous PageNext Page > Hide TOC


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-02-04)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.