libkern/libkern/c++/OSSet.h

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