NSCountedSet $Revision$ $Date$ NSCountedSet Foundation/NSSet.h NSCoding

The NSCountedSet class is used to maintain a set of objects where the number of times each object has been added (wiithout a corresponding removal) is kept track of.

In GNUstep, extra methods are provided to make use of a counted set for uniquing objects easier.

addObject: anObject Adds an object to the set. If the set already contains an object equal to the specified object (as determined by the [-isEqual:] method) then the count for that object is incremented rather than the new object being added. allObjects Returns an array containing all the objects stored in the set. count Returns the number of objects stored in the set. countForObject: anObject Returns the number of times that an object that is equal to the specified object (as determined byt the [-isEqual:] method) has been added to the set and not removed from it. initWithArray: anArray Initialises a newly allocated set by adding all the objects in the supplied array to the set. Each object is added to the set as many times as it occurs in the array. initWithCapacity: numItems Initialises a newly allocated set to contain no objects but to have space available to hold the specified number of items. initWithSet: aSet Initialises a newly allocated set by adding all the objects in the supplied set. objectEnumerator Returns an NSEnumerator object able to step through all the objects in the set. purge: count

This method removes from the set all objects whose count is less than or equal to the specified value.

This is useful where a counted set is used for uniquing objects. The set can be periodically purged of objects that have only been added once - and are therefore simply wasting space.

removeObject: anObject Decrements the count of the number of times that the specified object (or an object qequal to it as determined by the [-isEqual:] method) has been added to the set. If the count becomes zero, the object is removed from the set. unique: anObject

If the supplied object (or one equal to it as determined by the [-isEqual:] method) is already present in the set, the count for that object is incremented, the supplied object is released, and the object in the set is retained and returned. Otherwise, the supplied object is added to the set and returned.

This method is useful for uniquing objects - the init method of a class need simply end with - return [myUniquingSet unique: self];

NSCountedSet related functions

GNUstep provides some functions that may be using to maintain a global NSCountedSet object for usin in uniquing objects. In a multi-threaded application, accesses to this global set are automatically protected by locks.

flag This function sets the state of a flag that determines the behavior of the GSUnique() function. If the flag is on, uniquing is performed, if it is off the function has no effect. The default is for uniquing to be turned off. anObject This function uniques the supplied argument, returning the result. It works by using the [-unique:] method of a global NSCountedSet object. It handles locking as necessary. If uniquing is turned off, it simply returns its argument. count This function purges the global NSCountedSet object used for uniquing. It handles locking as necessary. It can be used to purge the set even when uniquing is turned off. anObject count This function sets the count for the specified object. If the count for the object is set to zero then the object is removed from the global uniquing set. The object is added to the set if necessary. The object returned is the one stored in the set. The function handles locking as necessary. It can be used to alter the set even when uniquing is turned off.