NSCountedSet Class Reference

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

Overview

The NSCountedSet class declares the programmatic interface to a mutable, unordered collection of indistinct objects. A counted set is also known as a bag.

Each distinct object inserted into an NSCountedSet object has a counter associated with it. NSCountedSetkeeps track of the number of times objects are inserted and requires that objects be removed the same number of times. Thus, there is only one instance of an object in an NSSet object even if the object has been added to the set multiple times. The count method defined by the superclass NSSet has special significance; it returns the number of distinct objects, not the total number of times objects are represented in the set. The NSSet and NSMutableSet classes are provided for static and dynamic sets (respectively) whose elements are distinct.

While NSCountedSet and CFBag are not toll-free bridged, they provide similar functionality. For more information on CFBag, consult the CFBag Reference.

Subclassing Notes

Because NSCountedSet is not a class cluster, it does not have primitive methods that provide the basis for its implementation. In general, there should be little need for subclassing.

Methods to Override

If you subclass NSCountedSet, you must override any method of which you want to change the behavior.

If you change the primitive behavior of an NSCountedSet, for instance if you change how objects are stored, you must override all of the affected methods. These include:

If you change the primitive behavior, you must also override the primitive methods of NSSet and NSMutableSet.

Tasks

Initializing a Counted Set

Adding and Removing Entries

Examining a Counted Set

Instance Methods

addObject:

Adds a given object to the set.

- (void)addObject:(id)anObject
Parameters
anObject

The object to add to the set.

Discussion

If anObject is already a member, addObject: increments the count associated with the object. If anObject is not already a member, it is sent a retain message.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSet.h

countForObject:

Returns the count associated with a given object in the set.

- (NSUInteger)countForObject:(id)anObject
Parameters
anObject

The object for which to return the count.

Return Value

The count associated with anObject in the set, which can be thought of as the number of occurrences of anObject present in the set.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSet.h

initWithArray:

Returns a counted set object initialized with the contents of a given array.

- (id)initWithArray:(NSArray *)anArray
Parameters
anArray

An array of objects to add to the new set.

Return Value

An initialized counted set object with the contents of anArray. The returned object might be different than the original receiver.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSet.h

initWithCapacity:

Returns a counted set object initialized with enough memory to hold a given number of objects.

- (id)initWithCapacity:(NSUInteger)numItems
Parameters
numItems

The initial capacity of the new counted set.

Return Value

A counted set object initialized with enough memory to hold numItems objects

Discussion

The method is the designated initializer for NSCountedSet.

Note that the capacity is simply a hint to help initial memory allocation—the initial count of the object is 0, and the set still grows and shrinks as you add and remove objects. The hint is typically useful if the set will become large.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSet.h

initWithSet:

Returns a counted set object initialized with the contents of a given set.

- (id)initWithSet:(NSSet *)aSet
Parameters
aSet

An set of objects to add to the new set.

Return Value

An initialized counted set object with the contents of aSet. The returned object might be different than the original receiver.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSet.h

objectEnumerator

Returns an enumerator object that lets you access each object in the set once, independent of its count.

- (NSEnumerator *)objectEnumerator
Return Value

An enumerator object that lets you access each object in the set once, independent of its count.

Discussion

If you add a given object to the counted set multiple times, an enumeration of the set will produce that object only once.

You shouldn’t modify the set during enumeration. If you intend to modify the set, use the allObjects method to create a “snapshot,” then enumerate the snapshot and modify the original set.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSet.h

removeObject:

Removes a given object from the set.

- (void)removeObject:(id)anObject
Parameters
anObject

The object to remove from the set.

Discussion

If anObject is present in the set, decrements the count associated with it. If the count is decremented to 0, anObject is removed from the set and sent a release message. removeObject: does nothing if anObject is not present in the set.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSet.h