← Back to branch summary

~ubuntu-branches/ubuntu/karmic/gnustep-base/karmic

« back to all changes in this revision

Viewing changes to Documentation/gsdoc/NSCountedSet.gsdoc

  • Committer: Bazaar Package Importer
  • Author(s): Eric Heintzmann
  • Date: 2005-04-17 00:14:38 UTC
  • mfrom: (1.2.1 upstream) (2.1.2 hoary)
  • Revision ID: james.westby@ubuntu.com-20050417001438-enf0y07c9tku85z1
Tags: 1.10.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/gsdoc/NSCountedSet.gsdoc
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
 
<gsdoc base="NSCountedSet" prev="NSConnection" next="NSDate" up="Base">
4
 
  <head>
5
 
    <title>NSCountedSet</title>
6
 
    <author name="Richard Frith-Macdonald">
7
 
      <email address="rfm@gnu.org"/>
8
 
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
9
 
    </author>
10
 
    <version>$Revision: 1.11 $</version>
11
 
    <date>$Date: 2001/03/03 09:58:53 $</date>
12
 
  </head>
13
 
  <body>
14
 
    <chapter>
15
 
      <heading>NSCountedSet</heading>
16
 
      <class name="NSCountedSet" super="NSMutableSet">
17
 
        <declared>Foundation/NSSet.h</declared>
18
 
        <conform>NSCoding</conform>
19
 
          <desc>
20
 
            <p>
21
 
              The NSCountedSet class is used to maintain a set of objects where
22
 
              the number of times each object has been added (wiithout a
23
 
              corresponding removal) is kept track of.
24
 
            </p>
25
 
            <p>
26
 
              In GNUstep, extra methods are provided to make use of a counted
27
 
              set for <em>uniquing</em> objects easier.
28
 
            </p>
29
 
          </desc>
30
 
        <method type="void">
31
 
          <sel>addObject:</sel>
32
 
          <arg type="id">anObject</arg>
33
 
          <desc>
34
 
            Adds an object to the set.  If the set already contains an object
35
 
            equal to the specified object (as determined by the [-isEqual:]
36
 
            method) then the count for that object is incremented rather
37
 
            than the new object being added.
38
 
          </desc>
39
 
        </method>
40
 
        <method type="NSArray*">
41
 
          <sel>allObjects</sel>
42
 
          <desc>
43
 
            Returns an array containing all the objects stored in the set.
44
 
          </desc>
45
 
        </method>
46
 
        <method type="unsigned int">
47
 
          <sel>count</sel>
48
 
          <desc>
49
 
            Returns the number of objects stored in the set.
50
 
          </desc>
51
 
        </method>
52
 
        <method type="unsigned int">
53
 
          <sel>countForObject:</sel>
54
 
          <arg type="id">anObject</arg>
55
 
          <desc>
56
 
            Returns the number of times that an object that is equal to the
57
 
            specified object (as determined byt the [-isEqual:] method) has
58
 
            been added to the set and not removed from it.
59
 
          </desc>
60
 
        </method>
61
 
        <method type="id">
62
 
          <sel>initWithArray:</sel>
63
 
          <arg type="NSArray*">anArray</arg>
64
 
          <desc>
65
 
            Initialises a newly allocated set by adding all the objects
66
 
            in the supplied array to the set.  Each object is added to
67
 
            the set as many times as it occurs in the array.
68
 
          </desc>
69
 
        </method>
70
 
        <method type="id">
71
 
          <sel>initWithCapacity:</sel>
72
 
          <arg type="unsigned int">numItems</arg>
73
 
          <desc>
74
 
            Initialises a newly allocated set to contain no objects but
75
 
            to have space available to hold the specified number of items.
76
 
          </desc>
77
 
        </method>
78
 
        <method type="id">
79
 
          <sel>initWithSet:</sel>
80
 
          <arg type="NSSet*">aSet</arg>
81
 
          <desc>
82
 
            Initialises a newly allocated set by adding all the objects
83
 
            in the supplied set.
84
 
          </desc>
85
 
        </method>
86
 
        <method type="NSEnumerator*">
87
 
          <sel>objectEnumerator</sel>
88
 
          <desc>
89
 
            Returns an NSEnumerator object able to step through all the
90
 
            objects in the set.
91
 
          </desc>
92
 
        </method>
93
 
        <method type="void">
94
 
          <sel>purge:</sel>
95
 
          <arg type="int">count</arg>
96
 
          <desc>
97
 
            <p>
98
 
              This method removes from the set all objects whose count is
99
 
              less than or equal to the specified value.
100
 
            </p>
101
 
            <p>
102
 
              This is useful where a counted set is used for uniquing objects.
103
 
              The set can be periodically purged of objects that have only
104
 
              been added once - and are therefore simply wasting space.
105
 
            </p>
106
 
          </desc>
107
 
          <standards><NotOpenStep/><NotMacOS-X/></standards>
108
 
        </method>
109
 
        <method type="void">
110
 
          <sel>removeObject:</sel>
111
 
          <arg type="id">anObject</arg>
112
 
          <desc>
113
 
            Decrements the count of the number of times that the specified
114
 
            object (or an object qequal to it as determined by the
115
 
            [-isEqual:] method) has been added to the set.  If the count
116
 
            becomes zero, the object is removed from the set.
117
 
          </desc>
118
 
        </method>
119
 
        <method type="id">
120
 
          <sel>unique:</sel>
121
 
          <arg type="id">anObject</arg>
122
 
          <desc>
123
 
            <p>
124
 
              If the supplied object (or one equal to it as determined by
125
 
              the [-isEqual:] method) is already present in the set, the
126
 
              count for that object is incremented, the supplied object
127
 
              is released, and the object in the set is retained and returned.
128
 
              Otherwise, the supplied object is added to the set and returned.
129
 
            </p>
130
 
            <p>
131
 
              This method is useful for uniquing objects - the init method of
132
 
              a class need simply end with -
133
 
              <code>
134
 
                return [myUniquingSet unique: self];
135
 
              </code>
136
 
            </p>
137
 
          </desc>
138
 
          <standards><NotOpenStep/><NotMacOS-X/></standards>
139
 
        </method>
140
 
      </class>
141
 
    </chapter>
142
 
    <chapter>
143
 
      <heading>NSCountedSet related functions</heading>
144
 
      <p>
145
 
        GNUstep provides some functions that may be using to maintain a
146
 
        global NSCountedSet object for usin in uniquing objects.  In a
147
 
        multi-threaded application, accesses to this global set are
148
 
        automatically protected by locks.
149
 
      </p>
150
 
      <function name="GSUniquing" type="void">
151
 
        <arg type="BOOL">flag</arg>
152
 
        <desc>
153
 
          This function sets the state of a flag that determines the
154
 
          behavior of the GSUnique() function.  If the flag is on,
155
 
          uniquing is performed, if it is off the function has no effect.
156
 
          The default is for uniquing to be turned off.
157
 
        </desc>
158
 
        <standards><GNUstep/><NotOpenStep/><NotMacOS-X/></standards>
159
 
      </function>
160
 
      <function name="GSUnique" type="id">
161
 
        <arg type="id">anObject</arg>
162
 
        <desc>
163
 
          This function <em>uniques</em> the supplied argument, returning
164
 
          the result.  It works by using the [-unique:] method of a global
165
 
          NSCountedSet object.  It handles locking as necessary.
166
 
          If uniquing is turned off, it simply returns its argument.
167
 
        </desc>
168
 
        <standards><GNUstep/><NotOpenStep/><NotMacOS-X/></standards>
169
 
      </function>
170
 
      <function name="GSUPurge" type="void">
171
 
        <arg type="unsigned int">count</arg>
172
 
        <desc>
173
 
          This function purges the global NSCountedSet object used for
174
 
          uniquing.  It handles locking as necessary.  It can be used to
175
 
          purge the set even when uniquing is turned off.
176
 
        </desc>
177
 
        <standards><GNUstep/><NotOpenStep/><NotMacOS-X/></standards>
178
 
      </function>
179
 
      <function name="GSUSet" type="id">
180
 
        <arg type="id">anObject</arg>
181
 
        <arg type="unsigned int">count</arg>
182
 
        <desc>
183
 
          This function sets the count for the specified object.  If the
184
 
          count for the object is set to zero then the object is removed
185
 
          from the global uniquing set.  The object is added to the set
186
 
          if necessary.  The object returned is the one stored in the set.
187
 
          The function handles locking as necessary.  It can be used to
188
 
          alter the set even when uniquing is turned off.
189
 
        </desc>
190
 
        <standards><GNUstep/><NotOpenStep/><NotMacOS-X/></standards>
191
 
      </function>
192
 
    </chapter>
193
 
  </body>
194
 
</gsdoc>