2
<title>NSCountedSet</title>
5
<a href ="NSConnection.html">[Previous] </a>
6
<a href ="Base.html">[Up] </a>
7
<a href ="NSDate.html">[Next] </a>
11
<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
14
<p>Version: $Revision: 1.16 $</p>
15
<p>Date: $Date: 2001/12/12 14:10:12 $</p>
16
<h2><a name ="cont-0">NSCountedSet</a></h2>
17
<h2><a name ="NSCountedSet">NSCountedSet</a></h2>
18
<p><b>Declared in: </b> Foundation/NSSet.h</p>
19
<p><b>Inherits from: </b> NSMutableSet</p>
20
<p><b>Conforms to: </b> NSCoding
26
The NSCountedSet class is used to maintain a set of objects where
27
the number of times each object has been added (wiithout a
28
corresponding removal) is kept track of.
33
In GNUstep, extra methods are provided to make use of a counted
34
set for <em>uniquing</em> objects easier.
38
<h2>Instance Variables </h2>
43
<li ><a href ="NSCountedSet.html#method-0">-addObject:</a>
44
<li ><a href ="NSCountedSet.html#method-1">-allObjects</a>
45
<li ><a href ="NSCountedSet.html#method-2">-count</a>
46
<li ><a href ="NSCountedSet.html#method-3">-countForObject:</a>
47
<li ><a href ="NSCountedSet.html#method-4">-initWithArray:</a>
48
<li ><a href ="NSCountedSet.html#method-5">-initWithCapacity:</a>
49
<li ><a href ="NSCountedSet.html#method-6">-initWithSet:</a>
50
<li ><a href ="NSCountedSet.html#method-7">-objectEnumerator</a>
51
<li ><a href ="NSCountedSet.html#method-8">-purge:</a>
52
<li ><a href ="NSCountedSet.html#method-9">-removeObject:</a>
53
<li ><a href ="NSCountedSet.html#method-10">-unique:</a>
55
<hr><h2>Instances Methods </h2>
56
<h3><a name ="method-0">addObject:</a></h3>
57
- (void) <b>addObject:</b> (id)anObject;<br>
59
Adds an object to the set. If the set already contains an object
60
equal to the specified object (as determined by the [-isEqual:]
61
method) then the count for that object is incremented rather
62
than the new object being added.
65
<h3><a name ="method-1">allObjects</a></h3>
66
- (NSArray*) <b>allObjects</b>;<br>
68
Returns an array containing all the objects stored in the set.
71
<h3><a name ="method-2">count</a></h3>
72
- (unsigned int) <b>count</b>;<br>
74
Returns the number of objects stored in the set.
77
<h3><a name ="method-3">countForObject:</a></h3>
78
- (unsigned int) <b>countForObject:</b> (id)anObject;<br>
80
Returns the number of times that an object that is equal to the
81
specified object (as determined byt the [-isEqual:] method) has
82
been added to the set and not removed from it.
85
<h3><a name ="method-4">initWithArray:</a></h3>
86
- (id) <b>initWithArray:</b> (NSArray*)anArray;<br>
88
Initialises a newly allocated set by adding all the objects
89
in the supplied array to the set. Each object is added to
90
the set as many times as it occurs in the array.
93
<h3><a name ="method-5">initWithCapacity:</a></h3>
94
- (id) <b>initWithCapacity:</b> (unsigned int)numItems;<br>
96
Initialises a newly allocated set to contain no objects but
97
to have space available to hold the specified number of items.
100
<h3><a name ="method-6">initWithSet:</a></h3>
101
- (id) <b>initWithSet:</b> (NSSet*)aSet;<br>
103
Initialises a newly allocated set by adding all the objects
107
<h3><a name ="method-7">objectEnumerator</a></h3>
108
- (NSEnumerator*) <b>objectEnumerator</b>;<br>
110
Returns an NSEnumerator object able to step through all the
114
<h3><a name ="method-8">purge:</a></h3>
115
- (void) <b>purge:</b> (int)count;<br>
116
Standards: NotOpenStep NotMacOS-X<br>
120
This method removes from the set all objects whose count is
121
less than or equal to the specified value.
126
This is useful where a counted set is used for uniquing objects.
127
The set can be periodically purged of objects that have only
128
been added once - and are therefore simply wasting space.
133
<h3><a name ="method-9">removeObject:</a></h3>
134
- (void) <b>removeObject:</b> (id)anObject;<br>
136
Decrements the count of the number of times that the specified
137
object (or an object qequal to it as determined by the
138
[-isEqual:] method) has been added to the set. If the count
139
becomes zero, the object is removed from the set.
142
<h3><a name ="method-10">unique:</a></h3>
143
- (id) <b>unique:</b> (id)anObject;<br>
144
Standards: NotOpenStep NotMacOS-X<br>
148
If the supplied object (or one equal to it as determined by
149
the [-isEqual:] method) is already present in the set, the
150
count for that object is incremented, the supplied object
151
is released, and the object in the set is retained and returned.
152
Otherwise, the supplied object is added to the set and returned.
157
This method is useful for uniquing objects - the init method of
158
a class need simply end with -
160
return [myUniquingSet unique: self];
166
<h2><a name ="cont-1">NSCountedSet related functions</a></h2>
169
GNUstep provides some functions that may be using to maintain a
170
global NSCountedSet object for usin in uniquing objects. In a
171
multi-threaded application, accesses to this global set are
172
automatically protected by locks.
174
<h2><a name ="function-11">GSUniquing</a></h2>
175
<b>Prototype: </b> void GSUniquing(BOOL flag)<br>
177
This function sets the state of a flag that determines the
178
behavior of the GSUnique() function. If the flag is on,
179
uniquing is performed, if it is off the function has no effect.
180
The default is for uniquing to be turned off.
183
<h2><a name ="function-12">GSUnique</a></h2>
184
<b>Prototype: </b> id GSUnique(id anObject)<br>
186
This function <em>uniques</em> the supplied argument, returning
187
the result. It works by using the [-unique:] method of a global
188
NSCountedSet object. It handles locking as necessary.
189
If uniquing is turned off, it simply returns its argument.
192
<h2><a name ="function-13">GSUPurge</a></h2>
193
<b>Prototype: </b> void GSUPurge(unsigned int count)<br>
195
This function purges the global NSCountedSet object used for
196
uniquing. It handles locking as necessary. It can be used to
197
purge the set even when uniquing is turned off.
200
<h2><a name ="function-14">GSUSet</a></h2>
201
<b>Prototype: </b> id GSUSet(id anObject, unsigned int count)<br>
203
This function sets the count for the specified object. If the
204
count for the object is set to zero then the object is removed
205
from the global uniquing set. The object is added to the set
206
if necessary. The object returned is the one stored in the set.
207
The function handles locking as necessary. It can be used to
208
alter the set even when uniquing is turned off.
added
removed
Documentation/gsdoc/NSCountedSet.html
