libkern/libkern/c++/OSSet.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_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. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /* IOSet.h created by rsulack on Thu 11-Jun-1998 */
  24 /* IOSet.h converted to C++ by gvdl on Fri 1998-10-30 */
  25
  26 #ifndef _OS_OSSET_H
  27 #define _OS_OSSET_H
  28
  29 #include <libkern/c++/OSCollection.h>
  30
  31 class OSArray;
  32
  33 /*!
  34     @class OSSet
  35     @abstract A collection class for storing OSMetaClassBase derived objects.
  36     @discussion
  37     Instances of OSSet store unique OSMetaClassBase derived objects in a non-ordered manner.
  38 */
  39 class OSSet : public OSCollection
  40 {
  41     OSDeclareDefaultStructors(OSSet)
  42
  43 private:
  44     OSArray *members;
  45
  46 protected:
  47     /*
  48      * OSCollectionIterator interfaces.
  49      */
  50     virtual unsigned int iteratorSize() const;
  51     virtual bool initIterator(void *iterator) const;
  52     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const;
  53
  54     struct ExpansionData { };
  55
  56     /*! @var reserved
  57         Reserved for future use.  (Internal use only)  */
  58     ExpansionData *reserved;
  59
  60 public:
  61     /*!
  62         @function withCapacity
  63         @abstract A static constructor function to create and initialize an instance of OSSet with a given capacity.
  64         @param capacity The initial capacity of the collection. The capacity is the total number of objects that can be stored in the collection.
  65         @result Returns an instance of OSSet or 0 on failure.
  66     */
  67     static OSSet *withCapacity(unsigned int capacity);
  68     /*!
  69         @function withObjects
  70         @abstract A static constructor function to create and initialize an instance of OSSet and populate it with the objects provided.
  71         @param objects A static array of OSMetaClassBase derived objects which are used to populate the collection.
  72         @param count The number of objects passed to the collection.
  73         @param capacity The initial storage size of the collection.  The capacity is the total number of objects that can be stored in the collection.  This value must be equal to or larger than the count parameter.
  74         @result Returns an instance of OSSet or 0 on failure.
  75     */
  76     static OSSet *withObjects(const OSObject *objects[],
  77                                  unsigned int count,
  78                                  unsigned int capacity = 0);
  79     /*!
  80         @function withArray
  81         @abstract A static constructor function to create and initialize an instance of OSSet and populate it with the objects from an OSSArray object.
  82         @param array An OSArray object containing a list of OSMetaClassBase derived objects which are used to initially populate the OSSet object.
  83         @param capacity The initial storage size of the collection.  This value must be equal to or larger than the number of objects provided by the OSArray object passed as the first parameter.
  84         @result Returns an instance of OSSet or 0 on failure.
  85     */
  86     static OSSet *withArray(const OSArray *array,
  87                             unsigned int capacity = 0);
  88     /*!
  89         @function withSet
  90         @abstract A static constructor function to create an instance of OSSet and populate it with the objects from another OSSet object.
  91         @param array An OSSet object containing OSMetaClassBase derived objects which are used to initially populate the new OSSet object.
  92         @param capacity The initial storage size of the collection.  This value must be equal to or larger than the number of objects provided by the OSSet object passed as the first parameter.
  93         @result Returns an instance of OSSet or 0 on failure.
  94     */
  95     static OSSet *withSet(const OSSet *set,
  96                           unsigned int capacity = 0);
  97
  98     /*!
  99         @function initWithCapacity
 100         @abstract A member function to initialize an instance of OSSet with a given capacity.
 101         @param capacity The initial storage size of the collection.
 102         @result Returns true if initialization successful or false on failure.
 103     */
 104     virtual bool initWithCapacity(unsigned int capacity);
 105     /*!
 106         @function initWithObjects
 107         @abstract A member function to initialize an instance of OSSet with a given capacity and populate the collection with the objects provided.
 108         @param object A static array containing OSMetaClassBase derived objects used to populate the collection.
 109         @param count The number of objects provided.
 110      @param capacity The initial storage size of the collection. This value must be equal to or larger than the 'count' parameter.
 111         @result Returns true if initialization successful or false on failure.
 112     */
 113     virtual bool initWithObjects(const OSObject *objects[],
 114                                  unsigned int count,
 115                                  unsigned int capacity = 0);
 116     /*!
 117         @function initWithArray
 118         @abstract A member function to initialize a new instance of OSSet and populate it with the contents of the OSArray object provided.
 119         @param array The OSArray object containing OSMetaClassBase derived objects used to populate the new OSSet object.
 120         @param capacity The initial storage capacity of the object.  This value must be equal to or larger than the number of objects provided by the OSArray object passed as the first parameter.
 121         @result Returns true if initialization successful or false on failure.
 122     */
 123     virtual bool initWithArray(const OSArray *array,
 124                                unsigned int capacity = 0);
 125     /*!
 126         @function initWithSet
 127         @abstract A member function to initialize a new instance of OSSet and populate it with the contents of the OSSet object provided.
 128         @param array The OSSet object containing OSMetaClassBase derived objects used to populate the new OSSet object.
 129         @param capacity The initial storage capacity of the object.  This value must be equal to or larger than the number of objects provided by the OSSet object passed as the first parameter.
 130         @result Returns true if initialization successful or false on failure.
 131         @discussion This function should not be called directly, use release() instead.
 132     */
 133     virtual bool initWithSet(const OSSet *set,
 134                              unsigned int capacity = 0);
 135     /*!
 136         @function free
 137         @abstract A member function to release all resources created or used by the OSArray instance.
 138     */
 139     virtual void free();
 140
 141     /*!
 142         @function getCount
 143         @abstract A member function which returns the number of objects current in the collection.
 144         @result Returns the number of objects in the collection.
 145     */
 146     virtual unsigned int getCount() const;
 147     /*!
 148         @function getCapacity
 149         @abstract A member function which returns the storage capacity of the collection.
 150         @result Returns the storage size of the collection.
 151     */
 152     virtual unsigned int getCapacity() const;
 153     /*!
 154         @function getCapacityIncrement
 155         @abstract A member function which returns the growth factor of the collection.
 156         @result Returns the size by which the collection will grow.
 157     */
 158     virtual unsigned int getCapacityIncrement() const;
 159     /*!
 160         @function setCapacityIncrement
 161         @abstract A member function which sets the growth factor of the collection.
 162         @result Returns the new increment.
 163     */
 164     virtual unsigned int setCapacityIncrement(unsigned increment);
 165
 166     /*!
 167         @function ensureCapacity
 168         @abstract A member function to grow the size of the collection.
 169         @param newCapacity The new capacity for the collection to expand to.
 170         @result Returns the new capacity of the collection or the previous capacity upon error.
 171     */
 172     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 173
 174     /*!
 175         @function flushCollection
 176         @abstract A member function which removes and releases all objects within the collection.
 177     */
 178     virtual void flushCollection();
 179
 180     /*!
 181         @function setObject
 182         @abstract A member function to place objects into the collection.
 183         @param anObject The OSMetaClassBase derived object to be placed into the collection.
 184         @result Returns true if the object was successfully placed into the collection, false otherwise.
 185         @discussion The object added to the collection is automatically retained.
 186     */
 187     virtual bool setObject(const OSMetaClassBase *anObject);
 188     /*!
 189         @function merge
 190         @abstract A member function to merge the contents of an OSArray object with set.
 191         @param array The OSArray object which contains the objects to be merged.
 192         @result Returns true if the contents of the OSArray were successfully merged into the receiver.
 193     */
 194     virtual bool merge(const OSArray *array);
 195     /*!
 196         @function merge
 197         @abstract A member function to merge the contents of an OSSet object with receiver.
 198         @param set The OSSet object which contains the objects to be merged.
 199         @result Returns true if the contents of the OSSet were successfully merged into the receiver.
 200     */
 201     virtual bool merge(const OSSet *set);
 202
 203     /*!
 204         @function removeObject
 205         @abstract A member function to remove objects from the collection.
 206         @param anObject The OSMetaClassBase derived object to be removed from the collection.
 207         @discussion The object removed from the collection is automatically released.
 208     */
 209     virtual void removeObject(const OSMetaClassBase * anObject);
 210
 211     /*!
 212         @function containsObject
 213         @abstract A member function to query the collection for the presence of an object.
 214         @param anObject The OSMetaClassBase derived object to be queried for in the collecion.
 215         @result Returns true if the object is present within the set, false otherwise.
 216     */
 217     virtual bool containsObject(const OSMetaClassBase *anObject) const;
 218     /*!
 219         @function member
 220         @abstract A member function to query the collection for the presence of an object.
 221         @param anObject The OSMetaClassBase derived object to be queried for in the collecion.
 222         @result Returns true if the object is present within the set, false otherwise.
 223     */
 224     virtual bool member(const OSMetaClassBase *anObject) const;
 225     /*!
 226         @function getAnyObject
 227         @abstract A member function which returns an object from the set.
 228         @result Returns an object if one exists within the set.
 229     */
 230     virtual OSObject *getAnyObject() const;
 231
 232     /*!
 233         @function isEqualTo
 234         @abstract A member function to test the equality between the receiver and an OSSet object.
 235         @param aSet An OSSet object to be compared against the receiver.
 236         @result Returns true if the objects are equivalent.
 237     */
 238     virtual bool isEqualTo(const OSSet *aSet) const;
 239     /*!
 240         @function isEqualTo
 241         @abstract A member function to test the equality between the receiver and an unknown object.
 242         @param anObject An object to be compared against the receiver.
 243         @result Returns true if the objects are equal.
 244     */
 245     virtual bool isEqualTo(const OSMetaClassBase *anObject) const;
 246
 247     /*!
 248         @function serialize
 249         @abstract A member function which archives the receiver.
 250         @param s The OSSerialize object.
 251         @result Returns true if serialization was successful, false if not.
 252     */
 253     virtual bool serialize(OSSerialize *s) const;
 254
 255     /*!
 256         @function setOptions
 257         @abstract This function is used to recursively set option bits in this set and all child collections.
 258         @param options Set the (options & mask) bits.
 259         @param mask The mask of bits which need to be set, 0 to get the current value.
 260         @result The options before the set operation, NB setOptions(?,0) returns the current value of this collection.
 261      */
 262     virtual unsigned setOptions(unsigned options, unsigned mask, void * = 0);
 263
 264     /*!
 265         @function copyCollection
 266         @abstract Do a deep copy of this ordered set.
 267         @discussion This function copies this set and all of included  containers recursively.  Objects that don't derive from OSContainter are NOT copied, that is objects like OSString and OSData.
 268         @param cycleDict Is a dictionary of all of the collections that have been, to start the copy at the top level just leave this field 0.
 269         @result The newly copied collecton or 0 if insufficient memory
 270     */
 271     OSCollection *copyCollection(OSDictionary *cycleDict = 0);
 272
 273     OSMetaClassDeclareReservedUnused(OSSet, 0);
 274     OSMetaClassDeclareReservedUnused(OSSet, 1);
 275     OSMetaClassDeclareReservedUnused(OSSet, 2);
 276     OSMetaClassDeclareReservedUnused(OSSet, 3);
 277     OSMetaClassDeclareReservedUnused(OSSet, 4);
 278     OSMetaClassDeclareReservedUnused(OSSet, 5);
 279     OSMetaClassDeclareReservedUnused(OSSet, 6);
 280     OSMetaClassDeclareReservedUnused(OSSet, 7);
 281 };
 282
 283 #endif /* !_OS_OSSET_H */