Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSSet 

Inherits From:	NSObject

Conforms To:	NSCoding, NSCopying, NSMutableCopying
NSObject (NSObject)

Declared In:	Foundation/NSSet.h 

Class Description

The NSSet class declares the programmatic interface to an object that manages an immutable set of objects. NSSet provides support for the mathematical concept of a set. A set, both in its mathematical sense and in the OpenStep implementation of NSSet, is an unordered collection of distinct elements. OpenStep provides the NSMutableSet class for sets whose contents may be altered, and also provides the NSCountedSet class for sets that can contain multiple instances of the same element.

Use set objects as an alternative to array objects when the order of elements is not important, but 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. For example, the NSSet method containsObject: operates in O(1) time when applied to a set, while containsObject: operates in O(N) time when applied to an array.

Objects in a set must respond to hash and isEqual: methods. See the NSObject protocol for details on hash and isEqual:.

Generally, you instantiate an NSSet object 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 set. Newly created instances of NSSet created by invoking the set method can be populated with objects using any of the init¼ methods. initWithObjects:: is the designated initializer for the NSSet class. Objects added to the set are not copied; rather, each object receives a retain message before it's added to the set.

NSSet provides methods for querying the elements of the set. allObjects returns an array containing all objects in the 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, the intersectsSet: tests for set intersection, isEqualToSet: tests for set equality, and isSubsetOfSet: tests for one set being a subset of the specified set object.

The objectEnumerator method provides for traversing elements of the set one by one.

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

Exceptions

NSSet implements the encodeWithCoder: method, which raises NSInternalInconsistencyException if the number of objects enumerated for encoding turns out to be unequal to the number of objects in the set. 

Allocating and Initializing a Set

+ (id)allocWithZone:(NSZone *)zone	Creates and returns an uninitialized set object in zone.

+ (id)set	Creates and returns an empty set object.

+ (id)setWithArray:(NSArray *)array	Creates and returns a set object containing the objects in array.

+ (id)setWithObject:(id)anObject	Creates and returns a set object containing the single element anObject.

+ (id)setWithObjects:(id)firstObj,...	Creates and returns a set object containing the objects in the argument list. The object list is comma-separated and ends with nil.

- (id)initWithArray:(NSArray *)array	Initializes a newly allocated set object by placing in it the objects contained in array.

- (id)initWithObjects:(id)firstObj,...	Initializes a newly allocated set object by placing in it the objects in the argument list. The object list is comma-separated and ends with nil.

- (id)initWithObjects:(id *)objects	Initializes a newly allocated set object by placing in 
count:(unsigned int)count		it count objects from the objects array.

- (id)initWithSet:(NSSet *)anotherSet	Initializes a newly allocated set object by placing in it the objects contained in anotherSet.

- (id)initWithSet:(NSSet *)set	Initializes a newly allocated set object by placing in it the
copyItems:(BOOL)flag		objects contained in anotherSet (or immutable copies of them, if flag is YES).

Querying the Set

- (NSArray *)allObjects	Returns an array containing all the objects in the set.

- (id)anyObject	Returns some object in the set, or nil if the set is empty.

- (BOOL)containsObject:(id)anObject	Returns YES if anObject is present in the set.

- (unsigned int)count	Returns the number of objects currently in the set.

- (id)member:(id)anObject	Return the object in the set that is equal to anObject, or nil if none is equal.

- (NSEnumerator *)objectEnumerator	Returns an enumerator object that lets you access each object in the set.

 Sending Messages to Elements of the Set

- (void)makeObjectsPerform:(SEL)aSelector	Sends an aSelector message to each object in the set.

- (void)makeObjectsPerform:(SEL)aSelector	Sends an aSelector message to each object in the
withObject:(id)anObject		set, with anObject as an argument.

Comparing Sets

- (BOOL)intersectsSet:(NSSet *)otherSet	Returns YES if there's any object in the receiving set that's equal to an object in otherSet.

- (BOOL)isEqualToSet:(NSSet *)otherSet	Returns YES if every object in the receiving set is equal to an object in otherSet, and the two sets contain the same number of objects.

- (BOOL)isSubsetOfSet:(NSSet *)otherSet	Returns YES if every object in the receiving set is equal to an object in otherSet, and the receiving set contains no more objects than otherSet does.

Creating a String Description of the Set

- (NSString *)description	Returns a string object that describes the contents of the receiver.

- (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary
	Returns a string representation of the NSSet object, including the keys and values that represent the locale data from localeDictionary.