libkern/libkern/c++/OSSet.h

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