PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSSet


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSMutableCopying
NSObject (NSObject)
Declared in:
Foundation/NSSet.h



Class at a Glance


An NSSet object stores an immutable set of objects.

Principal Attributes


Creation



+ set Returns an empty set.
+ setWithArray:: Returns a set containing a number of objects from an array.
+ setWithObject: Returns a set containing a single object.
+ setWithObjects: Returns a set containing a number of objects.
+ setWithObjects:count: Returns a set containing a specified number of objects.
+ setWithSet: Returns a set containing a number of objects from another set.

Commonly Used Methods



- allObjects Returns an array containing the set's member objects.
- count Returns the number of objects in the set.
- containsObject: Indicates whether a given object is present in the set.

Primitive Methods



- count
- member:
- objectEnumerator




Class Description


The NSSet, NSMutableSet, and NSCountedSet classes declare the programmatic interface to an object that manages a set of objects. NSSet provides support for the mathematical concept of a set. A set, both in its mathematical sense and in the implementation of NSSet, is an unordered collection of distinct elements. The NSMutableSet and NSCountedSet classes are provided for sets whose contents may be altered.

NSSet and NSMutableSet are part of a class cluster, so sets are not actual instances of NSSet or NSMutableSet. Rather, the instances belong to one of their private subclasses. (For convenience, we use the term set to refer to any one of these instances without specifying its exact class membership.) Although a set's class is private, its interface is public, as declared by the abstract superclasses NSSet and NSMutableSet. Note that NSCountedSet is not part of the class cluster; it is a concrete subclass of NSMutableSet.

NSSet declares the programmatic interface for static sets of objects. You establish a static set's entries when it's created, and thereafter the entries can't be modified. NSMutableSet, on the other hand, declares a programmatic interface for dynamic sets of objects. A dynamic-or mutable-set allows the addition and deletion of entries at any time, automatically allocating memory as needed.

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 for membership is slower than with sets.

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

Objects added to a set are not copied; rather, an object receives a retain message before it's added to a set.

Generally, you create a temporary set by sending one of the set... methods to the NSSet class object. These methods return an NSSet object containing the elements (if any) you pass in as arguments. The set method is a "convenience" method to create an empty mutable set.

The set classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert a set of one type to the other.

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 objectEnumerator method provides for traversing elements of the set one by one.

NSSet's makeObjectsPerformSelector: and makeObjectsPerformSelector:withObject: methods provides for sending messages to individual objects in the set.




Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copyWithZone:
NSMutableCopying
- mutableCopyWithZone:


Method Types


Creating a set
+ set
+ setWithArray:
+ setWithObject:
+ setWithObjects:
+ setWithObjects:count:
+ setWithSet:
- initWithArray:
- initWithObjects:
- initWithObjects:count:
- initWithSet:
- initWithSet:copyItems:
Counting entries
- count
Accessing the members
- allObjects
- anyObject
- containsObject:
- makeObjectsPerformSelector:
- makeObjectsPerformSelector:withObject:
- member:
- objectEnumerator
Comparing sets
- isSubsetOfSet:
- intersectsSet:
- isEqualToSet:
Describing a set
- description
- descriptionWithLocale:


Class Methods



set

+ (id)set

Creates and returns an empty set. This method is declared primarily for the use of mutable subclasses of NSSet.

See Also: - setWithArray:, + setWithObject:, - setWithObjects:



setWithArray:

+ (id)setWithArray:(NSArray *)anArray

Creates and returns a set containing those objects contained within the array anArray.

See Also: - set, + setWithObject:, - setWithObjects:



setWithObject:

+ (id)setWithObject:(id)anObject

Creates and returns a set containing a single member, anObject. anObject receives a retain message after being added to the set.

See Also: - set, + setWithArray:, - setWithObjects:



setWithObjects:

+ (id)setWithObjects:(id)anObject, ...

Creates and returns a set containing the objects in the argument list. The argument list is a comma-separated list of objects ending with nil.

As an example, the following code excerpt creates a set containing three different types of elements (assuming aPath exits):

NSSet *mySet;
NSData *someData = [NSData dataWithContentsOfFile:aPath]; 
NSValue *aValue = [NSNumber numberWithInt:5]; 
NSString *aString = @"a string";
	
mySet = [NSSet setWithObjects:someData, aValue, aString, nil];

See Also: - set, + setWithArray:, - setWithObject:



setWithObjects:count:

+ (id)setWithObjects:(id *)objects count:(unsigned)count

Creates and returns a set containing count objects from the list of objects specified by objects.

See Also: - set, + setWithArray:, - setWithObject:, - setWithObjects:



setWithSet:

+ (id)setWithArray:(NSSet *)aSet

Creates and returns a set containing those objects contained within the set aSet.

See Also: - set, + setWithArray:, - setWithObject:, - setWithObjects:




Instance Methods



allObjects

- (NSArray *)allObjects

Returns an array containing the receiver's members, or an empty array if the receiver has no members. The order of the objects in the array isn't defined.

See Also: - anyObject, - objectEnumerator



anyObject

- (id)anyObject

Returns one of the objects in the set (essentially chosen at random), or nil if the set contains no objects.

See Also: - allObjects, - objectEnumerator



containsObject:

- (BOOL)containsObject:(id)anObject

Returns YES if anObject is present in the set, NO otherwise.

See Also: - member:



count

- (unsigned)count

Returns the number of members in the set.



description

- (NSString *)description

Returns a string object that represents the contents of the receiver, formatted as a property list.

See Also: - descriptionWithLocale:



descriptionWithLocale:

- (NSString *)descriptionWithLocale:(NSDictionary *)locale

Returns a string object that represents the contents of the receiver, formatted as a property list. locale specifies options used for formatting each of the receiver's members, each of which is sent descriptionWithLocale: with locale passed along as the sole parameter. (If the receiver's members do not respond to descriptionWithLocale:, this method sends description instead.) If you do not want the receiver's members to be formatted, specify nil for locale.

See Also: - description



initWithArray:

- (id)initWithArray:(NSArray *)array

Initializes a newly allocated set with the objects that are contained in array. This method steps through array, adding members to the new set as it goes. Each object receives a retain message as it is added to the set. Returns self.

See Also: - initWithObjects:, - initWithObjects:count:, - initWithSet:, - initWithSet:copyItems:, + setWithArray:



initWithObjects:

- (id)initWithObjects:(id)anObject...

Initializes a newly allocated set with members taken from the specified list of objects. initWithObjects: takes a comma-separated list of objects terminated by nil. Each object receives a retain message as it is added to the set. Returns self.

See Also: - initWithArray:, - initWithObjects:count:, - initWithSet:, - initWithSet:copyItems:, + setWithObjects:



initWithObjects:count:

- (id)initWithObjects:(id *)objects count:(unsigned)count

Initializes a newly allocated set with count members. This method steps through the objects array, creating members in the new set as it goes. Each object receives a retain message as it is added to the set. Returns self.

See Also: - initWithArray:, - initWithObjects:, - initWithSet:, - initWithSet:copyItems:, + setWithObjects:count:



initWithSet:

- (id)initWithSet:(NSSet *)otherSet

Initializes a newly allocated set by placing in it the objects contained in otherSet. Each object is retained as it is added to the receiver. Returns self.

See Also: - initWithArray:, - initWithObjects:, - initWithObjects:count:, - initWithSet:copyItems:, + setWithSet:



initWithSet:copyItems:

- (id)initWithSet:(NSSet *)otherSet copyItems:(BOOL)flag

Initializes a newly allocated set and, if flag is NO, places in it the objects contained in otherSet. If flag is YES, the members of otherSet are copied, and the copies are added to the receiver. (Note that copyWithZone: is invoked in making these copies. Thus, the receiver's new member objects may be immutable, even though their counterparts in otherSet were mutable. Also, members must conform to the NSCopying protocol)

This method returns self.

See Also: - initWithArray:, - initWithObjects:, - initWithObjects:count:, - initWithSet:, + setWithSet:



intersectsSet:

- (BOOL)intersectsSet:(NSSet *)otherSet

Returns YES if at least one object in the receiver is also present in otherSet, NO otherwise.

See Also: - isEqualToSet:, - isSubsetOfSet:



isEqualToSet:

- (BOOL)isEqualToSet:(NSSet *)otherSet

Compares the receiving set to otherSet. If the contents of otherSet are equal to the contents of the receiver, this method returns YES. If not, it returns NO.

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

See Also: - intersectsSet:, isEqual: (NSObject protocol), - isSubsetOfSet:



isSubsetOfSet:

- (BOOL)isSubsetOfSet:(NSSet *)otherSet

Returns YES if every object in the receiver is also present in otherSet, NO otherwise.

See Also: - intersectsSet:, - isEqualToSet:



makeObjectsPerformSelector:

- (void)makeObjectsPerformSelector:(SEL)aSelector

Sends aSelector to each object in the set. The aSelector method must be one that takes no arguments. It shouldn't have the side effect of modifying this set. The messages are sent using the performSelector: method declared in the NSObject protocol.

See Also: - makeObjectsPerformSelector:withObject:



makeObjectsPerformSelector:withObject:

- (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(id)anObject

Sends aSelector to each object in the set. The message is sent each time with anObject as the argument, so the aSelector method must be one that takes a single argument of type id. The aSelector method shouldn't, as a side effect, modify this set. The messages are sent using the performSelector:withObject: method declared in the NSObject protocol.

See Also: - makeObjectsPerformSelector:



member:

- (id)member:(id)anObject

If anObject is present in the set (as determined by isEqual:), the object in the set is returned. Otherwise, member: returns nil.



objectEnumerator

- (NSEnumerator *)objectEnumerator

Returns an enumerator object that lets you access each object in the set:

NSEnumerator *enumerator = [mySet objectEnumerator];
id value;

while ((value = [enumerator nextObject])) {
    /* code that acts on the set's values */ 
}

When this method is used with mutable subclasses of NSSet, your code shouldn't modify the set during enumeration. If you intend to modify the set, use the allObjects method to create a "snapshot" of the set's members. Enumerate the snapshot, but make your modifications to the original set.

See Also: - nextObject (NSEnumerator)




Table of Contents