libkern/libkern/c++/OSSet.h

   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     @class OSSet
  40     @abstract A collection class for storing OSMetaClassBase derived objects.
  41     @discussion
  42     Instances of OSSet store unique OSMetaClassBase derived objects in a non-ordered manner.
  43 */
  44 class OSSet : public OSCollection
  45 {
  46     OSDeclareDefaultStructors(OSSet)
  47
  48 private:
  49     OSArray *members;
  50
  51 protected:
  52     /*
  53      * OSCollectionIterator interfaces.
  54      */
  55     virtual unsigned int iteratorSize() const;
  56     virtual bool initIterator(void *iterator) const;
  57     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const;
  58
  59     struct ExpansionData { };
  60
  61     /*! @var reserved
  62         Reserved for future use.  (Internal use only)  */
  63     ExpansionData *reserved;
  64
  65 public:
  66     /*!
  67         @function withCapacity
  68         @abstract A static constructor function to create and initialize an instance of OSSet with a given capacity.
  69         @param capacity The initial capacity of the collection. The capacity is the total number of objects that can be stored in the collection.
  70         @result Returns an instance of OSSet or 0 on failure.
  71     */
  72     static OSSet *withCapacity(unsigned int capacity);
  73     /*!
  74         @function withObjects
  75         @abstract A static constructor function to create and initialize an instance of OSSet and populate it with the objects provided.
  76         @param objects A static array of OSMetaClassBase derived objects which are used to populate the collection.
  77         @param count The number of objects passed to the collection.
  78         @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.
  79         @result Returns an instance of OSSet or 0 on failure.
  80     */
  81     static OSSet *withObjects(const OSObject *objects[],
  82                                  unsigned int count,
  83                                  unsigned int capacity = 0);
  84     /*!
  85         @function withArray
  86         @abstract A static constructor function to create and initialize an instance of OSSet and populate it with the objects from an OSSArray object.
  87         @param array An OSArray object containing a list of OSMetaClassBase derived objects which are used to initially populate the OSSet object.
  88         @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.
  89         @result Returns an instance of OSSet or 0 on failure.
  90     */
  91     static OSSet *withArray(const OSArray *array,
  92                             unsigned int capacity = 0);
  93     /*!
  94         @function withSet
  95         @abstract A static constructor function to create an instance of OSSet and populate it with the objects from another OSSet object.
  96         @param array An OSSet object containing OSMetaClassBase derived objects which are used to initially populate the new OSSet object.
  97         @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.
  98         @result Returns an instance of OSSet or 0 on failure.
  99     */
 100     static OSSet *withSet(const OSSet *set,
 101                           unsigned int capacity = 0);
 102
 103     /*!
 104         @function initWithCapacity
 105         @abstract A member function to initialize an instance of OSSet with a given capacity.
 106         @param capacity The initial storage size of the collection.
 107         @result Returns true if initialization successful or false on failure.
 108     */
 109     virtual bool initWithCapacity(unsigned int capacity);
 110     /*!
 111         @function initWithObjects
 112         @abstract A member function to initialize an instance of OSSet with a given capacity and populate the collection with the objects provided.
 113         @param object A static array containing OSMetaClassBase derived objects used to populate the collection.
 114         @param count The number of objects provided.
 115      @param capacity The initial storage size of the collection. This value must be equal to or larger than the 'count' parameter.
 116         @result Returns true if initialization successful or false on failure.
 117     */
 118     virtual bool initWithObjects(const OSObject *objects[],
 119                                  unsigned int count,
 120                                  unsigned int capacity = 0);
 121     /*!
 122         @function initWithArray
 123         @abstract A member function to initialize a new instance of OSSet and populate it with the contents of the OSArray object provided.
 124         @param array The OSArray object containing OSMetaClassBase derived objects used to populate the new OSSet object.
 125         @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.
 126         @result Returns true if initialization successful or false on failure.
 127     */
 128     virtual bool initWithArray(const OSArray *array,
 129                                unsigned int capacity = 0);
 130     /*!
 131         @function initWithSet
 132         @abstract A member function to initialize a new instance of OSSet and populate it with the contents of the OSSet object provided.
 133         @param array The OSSet object containing OSMetaClassBase derived objects used to populate the new OSSet object.
 134         @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.
 135         @result Returns true if initialization successful or false on failure.
 136         @discussion This function should not be called directly, use release() instead.
 137     */
 138     virtual bool initWithSet(const OSSet *set,
 139                              unsigned int capacity = 0);
 140     /*!
 141         @function free
 142         @abstract A member function to release all resources created or used by the OSArray instance.
 143     */
 144     virtual void free();
 145
 146     /*!
 147         @function getCount
 148         @abstract A member function which returns the number of objects current in the collection.
 149         @result Returns the number of objects in the collection.
 150     */
 151     virtual unsigned int getCount() const;
 152     /*!
 153         @function getCapacity
 154         @abstract A member function which returns the storage capacity of the collection.
 155         @result Returns the storage size of the collection.
 156     */
 157     virtual unsigned int getCapacity() const;
 158     /*!
 159         @function getCapacityIncrement
 160         @abstract A member function which returns the growth factor of the collection.
 161         @result Returns the size by which the collection will grow.
 162     */
 163     virtual unsigned int getCapacityIncrement() const;
 164     /*!
 165         @function setCapacityIncrement
 166         @abstract A member function which sets the growth factor of the collection.
 167         @result Returns the new increment.
 168     */
 169     virtual unsigned int setCapacityIncrement(unsigned increment);
 170
 171     /*!
 172         @function ensureCapacity
 173         @abstract A member function to grow the size of the collection.
 174         @param newCapacity The new capacity for the collection to expand to.
 175         @result Returns the new capacity of the collection or the previous capacity upon error.
 176     */
 177     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 178
 179     /*!
 180         @function flushCollection
 181         @abstract A member function which removes and releases all objects within the collection.
 182     */
 183     virtual void flushCollection();
 184
 185     /*!
 186         @function setObject
 187         @abstract A member function to place objects into the collection.
 188         @param anObject The OSMetaClassBase derived object to be placed into the collection.
 189         @result Returns true if the object was successfully placed into the collection, false otherwise.
 190         @discussion The object added to the collection is automatically retained.
 191     */
 192     virtual bool setObject(const OSMetaClassBase *anObject);
 193     /*!
 194         @function merge
 195         @abstract A member function to merge the contents of an OSArray object with set.
 196         @param array The OSArray object which contains the objects to be merged.
 197         @result Returns true if the contents of the OSArray were successfully merged into the receiver.
 198     */
 199     virtual bool merge(const OSArray *array);
 200     /*!
 201         @function merge
 202         @abstract A member function to merge the contents of an OSSet object with receiver.
 203         @param set The OSSet object which contains the objects to be merged.
 204         @result Returns true if the contents of the OSSet were successfully merged into the receiver.
 205     */
 206     virtual bool merge(const OSSet *set);
 207
 208     /*!
 209         @function removeObject
 210         @abstract A member function to remove objects from the collection.
 211         @param anObject The OSMetaClassBase derived object to be removed from the collection.
 212         @discussion The object removed from the collection is automatically released.
 213     */
 214     virtual void removeObject(const OSMetaClassBase * anObject);
 215
 216     /*!
 217         @function containsObject
 218         @abstract A member function to query the collection for the presence of an object.
 219         @param anObject The OSMetaClassBase derived object to be queried for in the collecion.
 220         @result Returns true if the object is present within the set, false otherwise.
 221     */
 222     virtual bool containsObject(const OSMetaClassBase *anObject) const;
 223     /*!
 224         @function member
 225         @abstract A member function to query the collection for the presence of an object.
 226         @param anObject The OSMetaClassBase derived object to be queried for in the collecion.
 227         @result Returns true if the object is present within the set, false otherwise.
 228     */
 229     virtual bool member(const OSMetaClassBase *anObject) const;
 230     /*!
 231         @function getAnyObject
 232         @abstract A member function which returns an object from the set.
 233         @result Returns an object if one exists within the set.
 234     */
 235     virtual OSObject *getAnyObject() const;
 236
 237     /*!
 238         @function isEqualTo
 239         @abstract A member function to test the equality between the receiver and an OSSet object.
 240         @param aSet An OSSet object to be compared against the receiver.
 241         @result Returns true if the objects are equivalent.
 242     */
 243     virtual bool isEqualTo(const OSSet *aSet) const;
 244     /*!
 245         @function isEqualTo
 246         @abstract A member function to test the equality between the receiver and an unknown object.
 247         @param anObject An object to be compared against the receiver.
 248         @result Returns true if the objects are equal.
 249     */
 250     virtual bool isEqualTo(const OSMetaClassBase *anObject) const;
 251
 252     /*!
 253         @function serialize
 254         @abstract A member function which archives the receiver.
 255         @param s The OSSerialize object.
 256         @result Returns true if serialization was successful, false if not.
 257     */
 258     virtual bool serialize(OSSerialize *s) const;
 259
 260     /*!
 261         @function setOptions
 262         @abstract This function is used to recursively set option bits in this set and all child collections.
 263         @param options Set the (options & mask) bits.
 264         @param mask The mask of bits which need to be set, 0 to get the current value.
 265         @result The options before the set operation, NB setOptions(?,0) returns the current value of this collection.
 266      */
 267     virtual unsigned setOptions(unsigned options, unsigned mask, void * = 0);
 268
 269     /*!
 270         @function copyCollection
 271         @abstract Do a deep copy of this ordered set.
 272         @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.
 273         @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.
 274         @result The newly copied collecton or 0 if insufficient memory
 275     */
 276     OSCollection *copyCollection(OSDictionary *cycleDict = 0);
 277
 278     OSMetaClassDeclareReservedUnused(OSSet, 0);
 279     OSMetaClassDeclareReservedUnused(OSSet, 1);
 280     OSMetaClassDeclareReservedUnused(OSSet, 2);
 281     OSMetaClassDeclareReservedUnused(OSSet, 3);
 282     OSMetaClassDeclareReservedUnused(OSSet, 4);
 283     OSMetaClassDeclareReservedUnused(OSSet, 5);
 284     OSMetaClassDeclareReservedUnused(OSSet, 6);
 285     OSMetaClassDeclareReservedUnused(OSSet, 7);
 286 };
 287
 288 #endif /* !_OS_OSSET_H */