1 | /* |
2 | * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | /* IOSet.h created by rsulack on Thu 11-Jun-1998 */ |
29 | /* IOSet.h converted to C++ by gvdl on Fri 1998-10-30 */ |
30 | |
31 | #ifndef _OS_OSSET_H |
32 | #define _OS_OSSET_H |
33 | |
34 | #include <libkern/c++/OSCollection.h> |
35 | |
36 | class OSArray; |
37 | |
38 | /*! |
39 | * @header |
40 | * |
41 | * @abstract |
42 | * This header declares the OSSet collection class. |
43 | */ |
44 | |
45 | |
46 | /*! |
47 | * @class OSSet |
48 | * |
49 | * @abstract |
50 | * OSSet provides an unordered set store of objects. |
51 | * |
52 | * @discussion |
53 | * OSSet is a container for Libkern C++ objects |
54 | * (those derived from |
55 | * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link, |
56 | * in particular @link //apple_ref/doc/class/OSObject OSObject@/link). |
57 | * Storage and access follow basic set logic: you can add or remove an object, |
58 | * and test whether the set contains a particular object. |
59 | * A given object is only stored in the set once, |
60 | * and there is no ordering of objects in the set. |
61 | * A subclass @link //apple_ref/doc/class/OSOrderedSet OSOrderedSet@/link, |
62 | * provides for ordered set logic. |
63 | * |
64 | * As with all Libkern collection classes, |
65 | * OSSet retains objects added to it, |
66 | * and releases objects removed from it. |
67 | * An OSSet also grows as necessary to accommodate new objects, |
68 | * <i>unlike</i> Core Foundation collections (it does not, however, shrink). |
69 | * |
70 | * <b>Use Restrictions</b> |
71 | * |
72 | * With very few exceptions in the I/O Kit, all Libkern-based C++ |
73 | * classes, functions, and macros are <b>unsafe</b> |
74 | * to use in a primary interrupt context. |
75 | * Consult the I/O Kit documentation related to primary interrupts |
76 | * for more information. |
77 | * |
78 | * OSSet provides no concurrency protection; |
79 | * it's up to the usage context to provide any protection necessary. |
80 | * Some portions of the I/O Kit, such as |
81 | * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, |
82 | * handle synchronization via defined member functions for setting |
83 | * properties. |
84 | */ |
85 | class OSSet : public OSCollection |
86 | { |
87 | friend class OSSerialize; |
88 | |
89 | OSDeclareDefaultStructors(OSSet) |
90 | |
91 | #if APPLE_KEXT_ALIGN_CONTAINERS |
92 | |
93 | private: |
94 | OSArray * members; |
95 | |
96 | #else /* APPLE_KEXT_ALIGN_CONTAINERS */ |
97 | |
98 | private: |
99 | OSArray * members; |
100 | |
101 | protected: |
102 | struct ExpansionData { }; |
103 | |
104 | /* Reserved for future use. (Internal use only) */ |
105 | ExpansionData * reserved; |
106 | |
107 | #endif /* APPLE_KEXT_ALIGN_CONTAINERS */ |
108 | |
109 | /* |
110 | * OSCollectionIterator interfaces. |
111 | */ |
112 | virtual unsigned int iteratorSize() const APPLE_KEXT_OVERRIDE; |
113 | virtual bool initIterator(void * iterator) const APPLE_KEXT_OVERRIDE; |
114 | virtual bool getNextObjectForIterator(void * iterator, OSObject ** ret) const APPLE_KEXT_OVERRIDE; |
115 | |
116 | public: |
117 | |
118 | |
119 | /*! |
120 | * @function withCapacity |
121 | * |
122 | * @abstract |
123 | * Creates and initializes an empty OSSet. |
124 | * |
125 | * @param capacity The initial storage capacity of the new set object. |
126 | * |
127 | * @result |
128 | * An empty instance of OSSet |
129 | * with a retain count of 1; |
130 | * <code>NULL</code> on failure. |
131 | * |
132 | * @discussion |
133 | * <code>capacity</code> must be nonzero. |
134 | * The new OSSet will grow as needed to accommodate more key/object pairs |
135 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
136 | * for which the initial capacity is a hard limit). |
137 | */ |
138 | static OSSet * withCapacity(unsigned int capacity); |
139 | |
140 | |
141 | /*! |
142 | * @function withObjects |
143 | * |
144 | * @abstract |
145 | * Creates and initializes an OSSet |
146 | * populated with objects provided. |
147 | * |
148 | * @param objects A C array of OSMetaClassBase-derived objects. |
149 | * @param count The number of objects to be placed into the set. |
150 | * @param capacity The initial storage capacity of the new set object. |
151 | * If 0, <code>count</code> is used; otherwise this value |
152 | * must be greater than or equal to <code>count</code>. |
153 | * |
154 | * @result |
155 | * An instance of OSSet |
156 | * containing the objects provided, |
157 | * with a retain count of 1; |
158 | * <code>NULL</code> on failure. |
159 | * |
160 | * @discussion |
161 | * <code>objects</code> must be non-<code>NULL</code>, |
162 | * and <code>count</code> must be nonzero. |
163 | * If <code>capacity</code> is nonzero, |
164 | * it must be greater than or equal to <code>count</code>. |
165 | * The new OSSet will grow as needed to accommodate more objects |
166 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
167 | * for which the initial capacity is a hard limit). |
168 | * |
169 | * The objects in <code>objects</code> are retained for storage in the new set, |
170 | * not copied. |
171 | */ |
172 | static OSSet * withObjects( |
173 | const OSObject * objects[], |
174 | unsigned int count, |
175 | unsigned int capacity = 0); |
176 | |
177 | |
178 | /*! |
179 | * @function withArray |
180 | * |
181 | * @abstract |
182 | * Creates and initializes an OSSet |
183 | * populated with the contents of an OSArray. |
184 | * |
185 | * @param array An array whose objects will be stored in the new OSSet. |
186 | * @param capacity The initial storage capacity of the new set object. |
187 | * If 0, the capacity is set to the number of objects |
188 | * in <code>array</code>; |
189 | * otherwise <code>capacity</code> must be greater than or equal to |
190 | * the number of objects in <code>array</code>. |
191 | * @result |
192 | * An instance of OSSet containing |
193 | * the objects of <code>array</code>, |
194 | * with a retain count of 1; |
195 | * <code>NULL</code> on failure. |
196 | * |
197 | * @discussion |
198 | * Each distinct object in <code>array</code> is added to the new set. |
199 | * |
200 | * <code>array</code> must be non-<code>NULL</code>. |
201 | * If <code>capacity</code> is nonzero, |
202 | * it must be greater than or equal to <code>count</code>. |
203 | * The new OSSet will grow as needed to accommodate more key-object pairs |
204 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
205 | * for which the initial capacity is a hard limit). |
206 | * |
207 | * The objects in <code>array</code> are retained for storage in the new set, |
208 | * not copied. |
209 | */ |
210 | static OSSet * withArray( |
211 | const OSArray * array, |
212 | unsigned int capacity = 0); |
213 | |
214 | |
215 | /*! |
216 | * @function withSet |
217 | * |
218 | * @abstract |
219 | * Creates and initializes an OSSet |
220 | * populated with the contents of another OSSet. |
221 | * |
222 | * @param set An OSSet whose contents will be stored |
223 | * in the new instance. |
224 | * @param capacity The initial storage capacity of the set object. |
225 | * If 0, the capacity is set to the number of objects |
226 | * in <code>set</code>; |
227 | * otherwise <code>capacity</code> must be greater than or equal to |
228 | * the number of objects in <code>array</code>. |
229 | * @result |
230 | * An instance of OSArray |
231 | * containing the objects of <code>set</code>, |
232 | * with a retain count of 1; |
233 | * <code>NULL</code> on failure. |
234 | * |
235 | * @discussion |
236 | * <code>set</code> must be non-<code>NULL</code>. |
237 | * If <code>capacity</code> is nonzero, |
238 | * it must be greater than or equal to <code>count</code>. |
239 | * The array will grow as needed to accommodate more key-object pairs |
240 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
241 | * for which the initial capacity is a hard limit). |
242 | * |
243 | * The objects in <code>set</code> are retained for storage in the new set, |
244 | * not copied. |
245 | */ |
246 | static OSSet * withSet(const OSSet * set, |
247 | unsigned int capacity = 0); |
248 | |
249 | |
250 | /*! |
251 | * @function initWithCapacity |
252 | * |
253 | * @abstract |
254 | * Initializes a new instance of OSSet. |
255 | * |
256 | * @param capacity The initial storage capacity of the new set object. |
257 | * |
258 | * @result |
259 | * <code>true</code> on success, <code>false</code> on failure. |
260 | * |
261 | * @discussion |
262 | * Not for general use. Use the static instance creation method |
263 | * <code>@link |
264 | * //apple_ref/cpp/clm/OSSet/withCapacity/staticOSSet*\/(unsignedint) |
265 | * withCapacity@/link</code> |
266 | * instead. |
267 | * |
268 | * <code>capacity</code> must be nonzero. |
269 | * The new set will grow as needed to accommodate more key/object pairs |
270 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
271 | * for which the initial capacity is a hard limit). |
272 | */ |
273 | virtual bool initWithCapacity(unsigned int capacity); |
274 | |
275 | |
276 | /*! |
277 | * @function initWithObjects |
278 | * |
279 | * @abstract |
280 | * Initializes a new OSSet populated with objects provided. |
281 | * |
282 | * @param objects A C array of OSObject-derived objects. |
283 | * @param count The number of objects to be placed into the set. |
284 | * @param capacity The initial storage capacity of the new set object. |
285 | * If 0, <code>count</code> is used; otherwise this value |
286 | * must be greater than or equal to <code>count</code>. |
287 | * |
288 | * @result |
289 | * <code>true</code> on success, <code>false</code> on failure. |
290 | * |
291 | * @discussion |
292 | * Not for general use. Use the static instance creation method |
293 | * <code>@link |
294 | * //apple_ref/cpp/clm/OSSet/withObjects/staticOSSet*\/(constOSObject*,unsignedint,unsignedint) |
295 | * withObjects@/link</code> |
296 | * instead. |
297 | * |
298 | * <code>objects</code> must be non-<code>NULL</code>, |
299 | * and <code>count</code> must be nonzero. |
300 | * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>. |
301 | * The new array will grow as needed to accommodate more key-object pairs |
302 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
303 | * for which the initial capacity is a hard limit). |
304 | * |
305 | * The objects in <code>objects</code> are retained for storage in the new set, |
306 | * not copied. |
307 | */ |
308 | virtual bool initWithObjects( |
309 | const OSObject * objects[], |
310 | unsigned int count, |
311 | unsigned int capacity = 0); |
312 | |
313 | |
314 | /*! |
315 | * @function initWithArray |
316 | * |
317 | * @abstract Initializes a new OSSet |
318 | * populated with the contents of an OSArray. |
319 | * |
320 | * @param array An OSAray whose contents will be placed |
321 | * in the new instance. |
322 | * @param capacity The initial storage capacity of the new set object. |
323 | * If 0, the capacity is set |
324 | * to the number of objects in <code>array</code>; |
325 | * otherwise <code>capacity</code> must be greater than or equal to |
326 | * the number of objects in <code>array</code>. |
327 | * |
328 | * @result |
329 | * <code>true</code> on success, <code>false</code> on failure. |
330 | * |
331 | * @discussion |
332 | * Not for general use. Use the static instance creation method |
333 | * <code>@link |
334 | * //apple_ref/cpp/clm/OSSet/withArray/staticOSSet*\/(constOSArray*,unsignedint) |
335 | * withArray@/link</code> |
336 | * instead. |
337 | * |
338 | * <code>array</code> must be non-<code>NULL</code>. |
339 | * If <code>capacity</code> is nonzero, |
340 | * it must be greater than or equal to <code>count</code>. |
341 | * The new array will grow as needed to accommodate more key-object pairs |
342 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
343 | * for which the initial capacity is a hard limit). |
344 | * |
345 | * The objects in <code>array</code> are retained for storage in the new set, |
346 | * not copied. |
347 | */ |
348 | virtual bool initWithArray( |
349 | const OSArray * array, |
350 | unsigned int capacity = 0); |
351 | |
352 | |
353 | /*! |
354 | * @function initWithSet |
355 | * |
356 | * @abstract |
357 | * Initializes a new OSSet |
358 | * populated with the contents of another OSSet. |
359 | * |
360 | * @param set A set whose contents will be placed in the new instance. |
361 | * @param capacity The initial storage capacity of the new set object. |
362 | * If 0, the capacity is set |
363 | * to the number of objects in <code>set</code>; |
364 | * otherwise <code>capacity</code> must be greater than or equal to |
365 | * the number of objects in <code>set</code>. |
366 | * |
367 | * @result |
368 | * <code>true</code> on success, <code>false</code> on failure. |
369 | * |
370 | * @discussion |
371 | * Not for general use. Use the static instance creation method |
372 | * <code>@link withSet withSet@/link</code> instead. |
373 | * |
374 | * <code>set</code> must be non-<code>NULL</code>. |
375 | * If <code>capacity</code> is nonzero, |
376 | * it must be greater than or equal to <code>count</code>. |
377 | * The new set will grow as needed to accommodate more key-object pairs |
378 | * (<i>unlike</i> @link //apple_ref/doc/uid/20001503 CFMutableSet@/link, |
379 | * for which the initial capacity is a hard limit). |
380 | * |
381 | * The objects in <code>set</code> are retained for storage in the new set, |
382 | * not copied. |
383 | */ |
384 | virtual bool initWithSet(const OSSet *set, |
385 | unsigned int capacity = 0); |
386 | |
387 | |
388 | /*! |
389 | * @function free |
390 | * |
391 | * @abstract |
392 | * Deallocates or releases any resources |
393 | * used by the OSSet instance. |
394 | * |
395 | * @discussion |
396 | * This function should not be called directly; |
397 | * use |
398 | * <code>@link |
399 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
400 | * release@/link</code> |
401 | * instead. |
402 | */ |
403 | virtual void free() APPLE_KEXT_OVERRIDE; |
404 | |
405 | |
406 | /*! |
407 | * @function getCount |
408 | * |
409 | * @abstract |
410 | * Returns the current number of objects within the set. |
411 | * |
412 | * @result |
413 | * The current number of objects within the set. |
414 | */ |
415 | virtual unsigned int getCount() const APPLE_KEXT_OVERRIDE; |
416 | |
417 | |
418 | /*! |
419 | * @function getCapacity |
420 | * |
421 | * @abstract |
422 | * Returns the number of objects the set |
423 | * can store without reallocating. |
424 | * |
425 | * @result |
426 | * The number objects the set |
427 | * can store without reallocating. |
428 | * |
429 | * @discussion |
430 | * OSSet objects grow when full to accommodate additional objects. |
431 | * See |
432 | * <code>@link |
433 | * //apple_ref/cpp/instm/OSSet/getCapacityIncrement/virtualunsignedint/() |
434 | * getCapacityIncrement@/link</code> |
435 | * and |
436 | * <code>@link |
437 | * //apple_ref/cpp/instm/OSSet/ensureCapacity/virtualunsignedint/(unsignedint) |
438 | * ensureCapacity@/link</code>. |
439 | */ |
440 | virtual unsigned int getCapacity() const APPLE_KEXT_OVERRIDE; |
441 | |
442 | |
443 | /*! |
444 | * @function getCapacityIncrement |
445 | * |
446 | * @abstract |
447 | * Returns the storage increment of the set. |
448 | * |
449 | * @result |
450 | * The storage increment of the set. |
451 | * |
452 | * @discussion |
453 | * An OSSet allocates storage for objects in multiples |
454 | * of the capacity increment. |
455 | */ |
456 | virtual unsigned int getCapacityIncrement() const APPLE_KEXT_OVERRIDE; |
457 | |
458 | |
459 | /*! |
460 | * @function setCapacityIncrement |
461 | * |
462 | * @abstract |
463 | * Sets the storage increment of the set. |
464 | * |
465 | * @result |
466 | * The new storage increment of the set, |
467 | * which may be different from the number requested. |
468 | * |
469 | * @discussion |
470 | * An OSSet allocates storage for objects in multiples |
471 | * of the capacity increment. |
472 | * Calling this function does not immediately reallocate storage. |
473 | */ |
474 | virtual unsigned int setCapacityIncrement(unsigned increment) APPLE_KEXT_OVERRIDE; |
475 | |
476 | |
477 | /*! |
478 | * @function ensureCapacity |
479 | * |
480 | * @abstract |
481 | * Ensures the set has enough space |
482 | * to store the requested number of distinct objects. |
483 | * |
484 | * @param newCapacity The total number of distinct objects the set |
485 | * should be able to store. |
486 | * @result |
487 | * The new capacity of the set, |
488 | * which may be different from the number requested |
489 | * (if smaller, reallocation of storage failed). |
490 | * |
491 | * @discussion |
492 | * This function immediately resizes the set, if necessary, |
493 | * to accommodate at least <code>newCapacity</code> distinct objects. |
494 | * If <code>newCapacity</code> is not greater than the current capacity, |
495 | * or if an allocation error occurs, the original capacity is returned. |
496 | * |
497 | * There is no way to reduce the capacity of an OSSet. |
498 | */ |
499 | virtual unsigned int ensureCapacity(unsigned int newCapacity) APPLE_KEXT_OVERRIDE; |
500 | |
501 | |
502 | /*! |
503 | * @function flushCollection |
504 | * |
505 | * @abstract |
506 | * Removes and releases all objects within the set. |
507 | * |
508 | * @discussion |
509 | * The set's capacity (and therefore direct memory consumption) |
510 | * is not reduced by this function. |
511 | */ |
512 | virtual void flushCollection() APPLE_KEXT_OVERRIDE; |
513 | |
514 | |
515 | /*! |
516 | * @function setObject |
517 | * |
518 | * @abstract |
519 | * Adds an object to the OSSet if it is not already present. |
520 | * |
521 | * @param anObject The OSMetaClassBase-derived object to be added to the set. |
522 | * |
523 | * @result |
524 | * <code>true</code> if <code>anObject</code> was successfully |
525 | * added to the set, <code>false</code> otherwise |
526 | * (including if it was already in the set). |
527 | * |
528 | * @discussion |
529 | * The set adds storage to accomodate the new object, if necessary. |
530 | * If successfully added, the object is retained. |
531 | * |
532 | * A <code>false</code> return value can mean either |
533 | * that <code>anObject</code> is already present in the set, |
534 | * or that a memory allocation failure occurred. |
535 | * If you need to know whether the object |
536 | * is already present, use |
537 | * <code>@link containsObject containsObject@/link</code>. |
538 | */ |
539 | virtual bool setObject(const OSMetaClassBase * anObject); |
540 | |
541 | |
542 | /*! |
543 | * @function merge |
544 | * |
545 | * @abstract |
546 | * Adds the contents of an OSArray to the set. |
547 | * |
548 | * @param array The OSArray object containing the objects to be added. |
549 | * |
550 | * @result |
551 | * <code>true</code> if all objects from <code>array</code> |
552 | * are successfully added the receiver (or were already present), |
553 | * <code>false</code> otherwise. |
554 | * |
555 | * @discussion |
556 | * This functions adds to the receiving set |
557 | * all objects from <code>array</code> |
558 | * that are not already in the receiving set. |
559 | * Objects added to the receiver are retained. |
560 | * |
561 | * In releases prior to 10.7, this function would return <code>false</code> |
562 | * if an object from <code>array</code> was already present in the set, |
563 | * or if <code>array</code> was empty. |
564 | * This is no longer the case, so this function correctly returns <code>true</code> |
565 | * when the semantic of merging is met. |
566 | */ |
567 | virtual bool merge(const OSArray * array); |
568 | |
569 | |
570 | /*! |
571 | * @function merge |
572 | * |
573 | * @abstract |
574 | * Adds the contents of an OSet to the set. |
575 | * |
576 | * @param set The OSSet object containing the objects to be added. |
577 | * |
578 | * @result |
579 | * <code>true</code> if any object from <code>set</code> |
580 | * are successfully added the receiver (or were already present), |
581 | * <code>false</code> otherwise. |
582 | * |
583 | * @discussion |
584 | * This functions adds to the receiving set |
585 | * all objects from <code>set</code> |
586 | * that are not already in the receiving set. |
587 | * Objects added to the receiver are retained. |
588 | * |
589 | * In releases prior to 10.7, this function would return <code>false</code> |
590 | * if an object from <code>set</code> was already present in the set, |
591 | * or if <code>set</code> was empty. |
592 | * This is no longer the case, so this function correctly returns <code>true</code> |
593 | * when the semantic of merging is met. |
594 | */ |
595 | virtual bool merge(const OSSet * set); |
596 | |
597 | |
598 | /*! |
599 | * @function removeObject |
600 | * |
601 | * @abstract |
602 | * Removes an object from the set. |
603 | * |
604 | * @param anObject The OSMetaClassBase-derived object |
605 | * to be removed from the set. |
606 | * |
607 | * @discussion |
608 | * The object removed from the set is released. |
609 | */ |
610 | virtual void removeObject(const OSMetaClassBase * anObject); |
611 | |
612 | |
613 | /*! |
614 | * @function containsObject |
615 | * |
616 | * @abstract |
617 | * Checks the set for the presence of an object. |
618 | * |
619 | * @param anObject The OSMetaClassBase-derived object |
620 | * to check for in the set. |
621 | * |
622 | * @result |
623 | * <code>true</code> if <code>anObject</code> is present within the set, |
624 | * <code>false</code> otherwise. |
625 | * |
626 | * @discussion |
627 | * Pointer equality is used. |
628 | * This function returns <code>false</code> if passed <code>NULL</code>. |
629 | */ |
630 | virtual bool containsObject(const OSMetaClassBase * anObject) const; |
631 | |
632 | |
633 | /*! |
634 | * @function member |
635 | * |
636 | * @abstract |
637 | * Checks the set for the presence of an object. |
638 | * |
639 | * @param anObject The OSMetaClassBase-derived object |
640 | * to check for in the set. |
641 | * |
642 | * @result |
643 | * <code>true</code> if <code>anObject</code> is present |
644 | * within the set, <code>false</code> otherwise. |
645 | * |
646 | * @discussion |
647 | * Pointer equality is used. This function returns <code>false</code> |
648 | * if passed <code>NULL</code>. |
649 | * |
650 | * <code>@link containsObject containsObject@/link</code> |
651 | * checks for <code>NULL</code> first, |
652 | * and is therefore more efficient than this function. |
653 | */ |
654 | virtual bool member(const OSMetaClassBase * anObject) const; |
655 | |
656 | |
657 | /*! |
658 | * @function getAnyObject |
659 | * |
660 | * @abstract |
661 | * Returns an arbitrary (not random) object from the set. |
662 | * |
663 | * @result |
664 | * An arbitrary (not random) object |
665 | * if one exists within the set. |
666 | * |
667 | * @discussion |
668 | * The returned object will be released if removed from the set; |
669 | * if you plan to store the reference, you should call |
670 | * <code>@link |
671 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
672 | * retain@/link</code> |
673 | * on that object. |
674 | */ |
675 | virtual OSObject * getAnyObject() const; |
676 | |
677 | |
678 | /*! |
679 | * @function isEqualTo |
680 | * |
681 | * @abstract |
682 | * Tests the equality of two OSSet objects. |
683 | * |
684 | * @param aSet The set object being compared against the receiver. |
685 | * @result |
686 | * <code>true</code> if the two sets are equivalent, |
687 | * <code>false</code> otherwise. |
688 | * |
689 | * @discussion |
690 | * Two OSSet objects are considered equal if they have same count |
691 | * and the same object pointer values. |
692 | */ |
693 | virtual bool isEqualTo(const OSSet * aSet) const; |
694 | |
695 | |
696 | /*! |
697 | * @function isEqualTo |
698 | * |
699 | * @abstract |
700 | * Tests the equality of an OSSet against an arbitrary object. |
701 | * |
702 | * @param anObject The object being compared against the receiver. |
703 | * @result |
704 | * <code>true</code> if the two objects are equivalent, |
705 | * <code>false</code> otherwise. |
706 | * |
707 | * @discussion |
708 | * An OSSet object is considered equal to another object if the other object |
709 | * is derived from OSSet and compares equal as a set. |
710 | */ |
711 | virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE; |
712 | |
713 | |
714 | /*! |
715 | * @function serialize |
716 | * |
717 | * @abstract |
718 | * Archives the receiver into the provided |
719 | * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object. |
720 | * |
721 | * @param serializer The OSSerialize object. |
722 | * |
723 | * @result |
724 | * <code>true</code> if serialization succeeds, <code>false</code> if not. |
725 | */ |
726 | virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE; |
727 | |
728 | |
729 | /*! |
730 | * @function setOptions |
731 | * |
732 | * @abstract |
733 | * Recursively sets option bits in the set |
734 | * and all child collections. |
735 | * |
736 | * @param options A bitfield whose values turn the options on (1) or off (0). |
737 | * @param mask A mask indicating which bits |
738 | * in <code>options</code> to change. |
739 | * Pass 0 to get the whole current options bitfield |
740 | * without changing any settings. |
741 | * @param context Unused. |
742 | * |
743 | * @result |
744 | * The options bitfield as it was before the set operation. |
745 | * |
746 | * @discussion |
747 | * Kernel extensions should not call this function. |
748 | * |
749 | * Child collections' options are changed only if the receiving set's |
750 | * options actually change. |
751 | */ |
752 | virtual unsigned setOptions(unsigned options, unsigned mask, void * context = 0) APPLE_KEXT_OVERRIDE; |
753 | |
754 | |
755 | /*! |
756 | * @function copyCollection |
757 | * |
758 | * @abstract |
759 | * Creates a deep copy of this set and its child collections. |
760 | * |
761 | * @param cycleDict A dictionary of all of the collections |
762 | * that have been copied so far, |
763 | * which is used to track circular references. |
764 | * To start the copy at the top level, |
765 | * pass <code>NULL</code>. |
766 | * |
767 | * @result |
768 | * The newly copied set, with a retain count of 1, |
769 | * or <code>NULL</code> if there is insufficient memory to do the copy. |
770 | * |
771 | * @discussion |
772 | * The receiving set, and any collections it contains, |
773 | * recursively, are copied. |
774 | * Objects that are not derived from OSCollection are retained |
775 | * rather than copied. |
776 | */ |
777 | OSCollection *copyCollection(OSDictionary *cycleDict = 0) APPLE_KEXT_OVERRIDE; |
778 | |
779 | OSMetaClassDeclareReservedUnused(OSSet, 0); |
780 | OSMetaClassDeclareReservedUnused(OSSet, 1); |
781 | OSMetaClassDeclareReservedUnused(OSSet, 2); |
782 | OSMetaClassDeclareReservedUnused(OSSet, 3); |
783 | OSMetaClassDeclareReservedUnused(OSSet, 4); |
784 | OSMetaClassDeclareReservedUnused(OSSet, 5); |
785 | OSMetaClassDeclareReservedUnused(OSSet, 6); |
786 | OSMetaClassDeclareReservedUnused(OSSet, 7); |
787 | }; |
788 | |
789 | #endif /* !_OS_OSSET_H */ |
790 | |