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

NSCountedSet 

Inherits From:	NSMutableSet : NSSet : NSObject

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

Declared In:	Foundation/NSSet.h 

Class Description

The NSCountedSet class declares the programmatic interface to an object that manages a mutable set of objects. NSCountedSet provides support for the mathematical concept of a counted set. A counted set, both in its mathematical sense and in the OpenStep implementation of NSCountedSet, is an unordered collection of elements, just as in a regular set, but the elements of the set aren't necessarily distinct. In the literature, a counted set is also knownas a bag.

Each newÐthat is, distinctÐobject inserted into an NSCountedSet object has a counter associated with it. NSCountedSet keeps track of the number of times objects are inserted and requires that objects are removed the same number of times. OpenStep also provides the NSSet class for sets whose elements are distinctÐthat is, there is only one instance of an object in an NSSet even if the object has been added to the set multiple times.

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.

Objects in a set must respond to hash and isEqual: methods. See the NSObject protocol for details on hash and isEqual:. Each new distinct object must provide a unique hash value.

Generally, you instantiate an NSCountedSet object by sending one of the set¼ methods to the NSCountedSet class object, as described in NSSet. These methods return an NSCountedSet object containing the elements (if any) you pass in as arguments. Newly created instances of NSCountedSet created by invoking the set method can be populated with objects using any of the init¼ methods. initWithObjects:: is the designated initializer for this class.

You add or remove objects from a counted set using the addObject: and removeObject: methods.

An NSCountedSet may be queried using the objectEnumerator method, which provides for traversing elements of the set one by one. The countForObject: method returns the number of times the specified object has been added to this set.

Initializing an NSCountedSet

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

- (id)initWithCapacity:(unsigned int)numItems	Initializes a newly allocated set object, giving it enough memory to hold numItems objects.

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

Adding Objects	

- (void)addObject:(id)anObject	Adds anObject to the set, unless anObject is equal to some object already in the set. In either case, the counter that's returned by countForObject: is incremented.

Removing Objects

- (void)removeObject:(id)anObject	Decrements the counter for the object, if the set contains an object that's equal to anObject. If this causes the counter to reach zero, the object that's equal to anObject is removed from the set.

Querying the NSCountedSet

- (unsigned int)countForObject:(id)anObject	Returns the number of times that an object equal to anObject has ostensibly been added to the set. (This number is incremented by addObject: and decremented by removeObject:.)

- (NSEnumerator *)objectEnumerator	Returns an enumerator object that will access each object in the set only once, regardless of its count.