libkern/libkern/c++/OSSet.h

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