NSSet Class Cluster
Class Cluster Description
The NSSet, NSMutableSet, and NSCountedSet classes declare the programmatic interface for objects that store unordered sets of objects.Because of the nature of class clusters, the objects you create with the NSSet class cluster 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.
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, each 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. Newly created instances of NSSet created by invoking the allocWithZone:
method can be populated with objects using any of the init
methods.
The set classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert a set of one type to the other.
NSSet
Inherits From:
NSObject
Conforms To:
NSCoding
NSCopying
NSMutableCopying
NSObject (NSObject)
Declared In:
Foundation/NSSet.h
Class At A Glance
Purpose
- An NSSet object stores an immutable set of objects.
Principal Attributes
- The objects that make up the set.
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
- - member:
- - count
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 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 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, the 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 makeObjectsPerform:
and makeObjectsPerform:withObject:
methods provides for sending messages to individual objects in the set.
Exceptions
NSSet implements theencodeWithCoder:
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.
Adopted Protocols
- NSCoding
- - encodeWithCoder:
- - initWithCoder:
- - encodeWithCoder:
- NSCopying
- - copyWithZone:
- NSMutableCopying
- - mutableCopyWithZone:
Method Types
- Creating a set
- + allocWithZone:
- + set
- + setWithArray:
- + setWithObject:
- + setWithObjects:
- - initWithArray:
- - initWithObjects:
- - initWithObjects:count:
- - initWithSet:
- - initWithSet:copyItems:
- + set
- + allocWithZone:
- Counting entries
- - count
- Accessing the members
- - allObjects
- - anyObject
- - containsObject:
- - makeObjectsPerform:
- - makeObjectsPerform:withObject:
- - member:
- - objectEnumerator
- - anyObject
- - allObjects
- Comparing sets
- - isSubsetOfSet:
- - intersectsSet:
- - isEqualToSet:
- - intersectsSet:
- - isSubsetOfSet:
- Describing a set
- - description
- - descriptionWithLocale:
- - description
Class Methods
allocWithZone:
+ (id)allocWithZone:
(NSZone *)zone
Creates and returns an uninitialized set in the specified zone. If the receiver is the NSSet class object, an instance of an immutable private subclass is returned; otherwise, an object of the receiver's class is returned.
Typically, you create temporary sets using the set...
class methods, not the allocWithZone:
and init...
methods. Note that it's your responsibility to free objects created with the allocWithZone:
method.
See also:
+ set
, + setWithObject:
, + setWithObjects:
, + setWithArray:
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:
+ setWithArray:
, + set
, + 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:
+ setWithArray:
, + set
, + setWithObject:
setWithObjects:count:
+ (id)setWithObjects:
(id *)objects count:
(unsigned int)count
Creates and returns a set containing count objects from the list of objects specified by objects.
setWithSet:
+ (id)setWithArray:
(NSSet *)aSet
Creates and returns a set containing those objects contained within the set aSet.
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.
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 int)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
hash
@protocol NSObject- (unsigned int)hash
Returns an unsigned integer that can be used as a table address in a hash table structure. For a set, hash
returns the number of members in the set. If two sets are equal (as determined by the isEqual:
method), they will have the same hash value.
See also:
- isEqual:
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:
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:
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:
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:
isEqual:
@protocol NSObject- (BOOL)isEqual:
(id)anObject
Returns YES if the receiver and anObject are equal; otherwise returns NO. A YES return value indicates that the receiver and anObject both inherit from NSSet and contain the same contents (as determined by the isEqualToSet:
method).
See also:
- isEqualToSet:
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:
makeObjectsPerform:
- (void)makeObjectsPerform:
(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:
- makeObjectsPerform:withObject:
makeObjectsPerformSelector:
- (void)makeObjectsPerformSelector:
(SEL)aSelector
Same as makeObjectsPerform:
.
makeObjectsPerformSelector:withObject:
- (void)makeObjectsPerformSelector:
(SEL)aSelector withObject:
(id)anObject
Same as makeObjectsPerform:withObject:
.
makeObjectsPerform:withObject:
- (void)makeObjectsPerform:
(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:
- makeObjectsPerform:
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
.
See also:
- containsObject:
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)
NSMutableSet
Inherits From:
NSSet : NSObject
Conforms To:
NSCoding
NSCopying
NSMutableCopying (NSSet)
NSObject (NSObject)
Declared In:
Foundation/NSSet.h
Class At A Glance
Purpose
- An NSMutableSet object stores a modifiable set of objects.
Principal Attributes
- The objects that make up the set.
Creation
+ setWithCapacity: Returns An empty set with enough allocated memory to hold a specified number of objects. Commonly Used Methods
- addObject: Adds an object to the set, if it isn't already a member. - removeObject: Removes an object from the set. Primitive Methods
- - addObject:
- - removeObject:
- - addObject:
Class Description
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.
Objects are added to an NSMutableSet with addObject:
, which adds a single object to the set; addObjectsFromArray:
, which adds all objects from a specified array to the set; or with unionSet:
, which adds all the objects from another set.
Objects are removed from an NSMutableSet using any of the methods intersectSet:
, minusSet:
, removeAllObjects
, or removeObject:
.
- Creating an NSMutableSet
- + allocWithZone:
- + setWithCapacity:
- - initWithCapacity:
- + setWithCapacity:
- + allocWithZone:
- Adding and removing entries
- - addObject:
- - removeObject:
- - removeAllObjects
- - addObjectsFromArray:
- - removeObject:
- - addObject:
- Combining and recombining sets
- - unionSet:
- - minusSet:
- - intersectSet:
- - setSet:
- - minusSet:
- - unionSet:
Class Methods
allocWithZone:
+ (id)allocWithZone:
(NSZone *)zone
Creates and returns an uninitialized mutable set in the specified zone. If the receiver is the NSMutableSet class object, an instance of a mutable private subclass is returned; otherwise, an object of the receiver's class is returned.
Typically, you create temporary sets using the set...
class methods, not the allocWithZone:
and init...
methods.
See also:
- initWithCapacity:
, + set
(NSSet), + setWithObjects:count:
(NSSet)
setWithCapacity:
+ (id)setWithCapacity:
(unsigned)numItems
Creates and returns a mutable set, giving it enough allocated memory to hold numItems members. Mutable sets allocate additional memory as needed, so numItems simply establishes the object's initial capacity.
See also:
- initWithCapacity:
, + set
(NSSet), + setWithObjects:count:
(NSSet)
Instance Methods
addObject:
- (void)addObject:
(id)anObject
Adds the specified object to the receiver if it is not already a member. anObject is sent a retain
message as it is added to the receiver. If anObject is already present in the set, this method has no effect on either the set or on anObject.
See also:
- addObjectsFromArray:
, - unionSet:
addObjectsFromArray:
- (void)addObjectsFromArray:
(NSArray *)anArray
Adds each object contained in anArray to the receiver, if that object is not already a member. The new member is retained. If a given element of the array is already present in the set, this method has no effect on either the set or on the array element.
See also:
- addObject:
, - unionSet:
initWithCapacity:
- (id)initWithCapacity:
(unsigned)numItems
Initializes a newly allocated mutable set, giving it enough allocated memory to hold numItems members. Mutable sets allocate additional memory as needed, so numItems simply establishes the object's initial capacity. Returns self
.
See also:
+ setWithCapacity:
intersectSet:
- (void)intersectSet:
(NSSet *)otherSet
Removes from the receiver each object that isn't a member of otherSet. Each object that's removed from the receiver is sent a release
message.
See also:
- removeObject:
, - removeAllObjects
,
- minusSet:
minusSet:
- (void)minusSet:
(NSSet *)otherSet
Removes from the receiver each object contained in otherSet that is also present in the receiver. Each object that's successfully removed from the receiver is sent a release
message. If any member of otherSet isn't present in the receiving set, this method has no effect on either the receiver or on the otherSet member.
See also:
- removeObject:
, - removeAllObjects
,
- intersectSet:
removeAllObjects
- (void)removeAllObjects
Empties the set of all of its members. Each member is sent a release
message.
See also:
- removeObject:
,
- minusSet:
, - intersectSet:
removeObject:
- (void)removeObject:
(id)anObject
Removes anObject from the set. The removed object is sent a release
message if it was a member of the receiver.
See also:
- removeAllObjects
,
- minusSet:
, - intersectSet:
setSet:
- (void)setSet:
(NSSet *)otherSet
Empties the receiver, then adds each object contained in otherSet to the receiver The new member is sent a retain
message as it is added to the receiver.
unionSet:
- (void)unionSet:
(NSSet *)otherSet
Adds each object contained in otherSet to the receiver, if that object is not already a member. The new member is sent a retain
message as it is added to the receiver. If any member of otherSet is already present in the receiver, this method has no effect on either the receiver or on the otherSet member.
See also:
- addObject:
, - addObjectsFromArray:
Copyright © 1997, Apple Computer, Inc. All rights reserved.