ADC Home > Reference Library > Reference > Cocoa > Data Management > NSMutableSet Class Reference >

Next Page > Hide TOC

NSMutableSet Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSPredicate.h
NSSet.h
Related sample code

Overview

The NSMutableSet class declares the programmatic interface to an object that manages a mutable set of objects. NSMutableSet provides support for the mathematical concept of a set. A set, both in its mathematical sense and in the NSMutableSet implementation, is an unordered collection of distinct elements.

The NSCountedSet class, which is a concrete subclass of NSMutableSet, supports mutable sets that can contain multiple instances of the same element. The NSSet class supports creating and managing immutable sets.

You add objects to an NSMutableSet object with addObject:, which adds a single object to the set; addObjectsFromArray:, which adds all objects from a specified array to the set; or unionSet:, which adds all the objects from another set. You remove objects from an NSMutableSet object using any of the methods intersectSet:, minusSet:, removeAllObjects, or removeObject:.

When an object is added to a set, it receives a retain message. When an object is removed from a mutable set, it receives a release message. If there are no further references to the object, this means that the object is deallocated. If your program keeps a reference to such an object, the reference will become invalid unless you send the object a retain message before it’s removed from the array. For example, if anObject is not retained before it is removed from the set, the third statement below could result in a runtime error:

id anObject = [[aSet anyObject] retain];
[aSet removeObject:anObject];
[anObject someMessage];

Tasks

Creating a Mutable Set

Adding and Removing Entries

Combining and Recombining Sets

Class Methods

setWithCapacity:

Creates and returns a mutable set with a given initial capacity.

+ (id)setWithCapacity:(NSUInteger)numItems

Parameters
numItems

The initial capacity of the new set.

Return Value

A mutable set with initial capacity to hold numItems members.

Discussion

Mutable sets allocate additional memory as needed, so numItems simply establishes the object’s initial capacity.

Availability
See Also
Declared In
NSSet.h

Instance Methods

addObject:

Adds a given object to the receiver, if it is not already a member.

- (void)addObject:(id)anObject

Parameters
anObject

The object to add to the receiver.

Discussion

If anObject is already present in the set, this method has no effect on either the set or anObject.

Availability
See Also
Related Sample Code
Declared In
NSSet.h

addObjectsFromArray:

Adds to the receiver each object contained in a given array that is not already a member.

- (void)addObjectsFromArray:(NSArray *)anArray

Parameters
anArray

An array of objects to add to the receiver.

Discussion

If a given element of the array is already present in the set, this method has no effect on either the set or the array element.

Availability
See Also
Related Sample Code
Declared In
NSSet.h

filterUsingPredicate:

Evaluates a given predicate against the receiver’s content and removes from the receiver those objects for which the predicate returns false.

- (void)filterUsingPredicate:(NSPredicate *)predicate

Parameters
predicate

A predicate.

Discussion

The following example illustrates the use of this method.

NSMutableSet *mutableSet =
    [NSMutableSet setWithObjects:@"One", @"Two", @"Three", @"Four", nil];
NSPredicate *predicate =
    [NSPredicate predicateWithFormat:@"SELF beginswith 'T'"];
[mutableSet filterUsingPredicate:predicate];
// mutableSet contains (Two, Three)
Availability
Declared In
NSPredicate.h

initWithCapacity:

Returns an initialized mutable set with a given initial capacity.

- (id)initWithCapacity:(NSUInteger)numItems

Parameters
numItems

The initial capacity of the set.

Return Value

An initialized mutable set with initial capacity to hold numItems members. The returned object might be different than the original receiver.

Discussion

Mutable sets allocate additional memory as needed, so numItems simply establishes the object’s initial capacity.

Availability
See Also
Declared In
NSSet.h

intersectSet:

Removes from the receiver each object that isn’t a member of another given set.

- (void)intersectSet:(NSSet *)otherSet

Parameters
otherSet

The set with which to perform the intersection.

Availability
See Also
Declared In
NSSet.h

minusSet:

Removes from the receiver each object contained in another given set that is present in the receiver.

- (void)minusSet:(NSSet *)otherSet

Parameters
otherSet

The set of objects to remove from the receiver.

Discussion

If any member of otherSet isn’t present in the receiving set, this method has no effect on either the receiver or the otherSet member.

Availability
See Also
Related Sample Code
Declared In
NSSet.h

removeAllObjects

Empties the receiver of all of its members.

- (void)removeAllObjects

Availability
See Also
Related Sample Code
Declared In
NSSet.h

removeObject:

Removes a given object from the receiver.

- (void)removeObject:(id)anObject

Parameters
anObject

The object to remove from the receiver.

Availability
See Also
Related Sample Code
Declared In
NSSet.h

setSet:

Empties the receiver, then adds to the receiver each object contained in another given set.

- (void)setSet:(NSSet *)otherSet

Parameters
otherSet

The set whose members replace the receiver's content.

Availability
Declared In
NSSet.h

unionSet:

Adds to the receiver each object contained in another given set that is not already a member.

- (void)unionSet:(NSSet *)otherSet

Parameters
otherSet

The set of objects to add to the receiver.

Discussion

If any member of otherSet is already present in the receiver, this method has no effect on either the receiver or the otherSet member.

Availability
See Also
Declared In
NSSet.h

Next Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-09-19)

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.