libkern/libkern/c++/OSArray.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 /* IOArray.h created by rsulack on Thu 11-Sep-1997 */
  31 /* IOArray.h converted to C++ by gvdl on Fri 1998-10-30 */
  32
  33 #ifndef _OS_OSARRAY_H
  34 #define _OS_OSARRAY_H
  35
  36 #include <libkern/c++/OSCollection.h>
  37
  38 class OSSerialize;
  39
  40 /*!
  41     @class OSArray
  42     @abstract A collection class whose instances maintain a list of object references.
  43     @discussion
  44     An instance of an OSArray is a mutable collection which maintains a list of references to OSMetaClassBase derived objects.  Objects are referenced by index, where the index is an integer with a value of 0 to N-1 where N is the number of objects contained within the array.
  45
  46     Objects placed into an array are automatically retained and objects removed or replaced are automatically released. All objects are released when the array is freed.
  47 */
  48
  49 class OSArray : public OSCollection
  50 {
  51     friend class OSSet;
  52
  53     OSDeclareDefaultStructors(OSArray)
  54
  55 protected:
  56     const OSMetaClassBase **array;
  57     unsigned int count;
  58     unsigned int capacity;
  59     unsigned int capacityIncrement;
  60
  61     struct ExpansionData { };
  62
  63     /*! @var reserved
  64         Reserved for future use.  (Internal use only)  */
  65     ExpansionData *reserved;
  66
  67     /*
  68      * OSCollectionIterator interfaces.
  69      */
  70     virtual unsigned int iteratorSize() const;
  71     virtual bool initIterator(void *iterator) const;
  72     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const;
  73
  74 public:
  75     /*!
  76         @function withCapacity
  77         @abstract A static constructor function to create and initialize a new instance of OSArray with a given capacity.
  78         @param capacity The initial capacity (number of refernces) of the OSArray instance.
  79         @result Returns a reference to an instance of OSArray or 0 if an error occurred.
  80     */
  81     static OSArray *withCapacity(unsigned int capacity);
  82     /*!
  83         @function withObjects
  84         @abstract A static constructor function to create and initialize a new instance of OSArray and populates it with a list of objects provided.
  85         @param objects A static array of references to OSMetaClassBase derived objects.
  86         @param count The number of objects provided.
  87         @param capacity The initial storage size of the OSArray instance. If 0, the capacity will be set to the size of count, else the capacity must be greater than or equal to count.
  88         @result Returns a reference to a new instance of OSArray or 0 if an error occurred.
  89     */
  90     static OSArray *withObjects(const OSObject *objects[],
  91                                 unsigned int count,
  92                                 unsigned int capacity = 0);
  93     /*!
  94         @function withArray
  95         @abstract A static constructor function to create and initialize an instance of OSArray of a given capacity and populate it with the contents of the supplied OSArray object.
  96         @param array An instance of OSArray from which the new instance will aquire its contents.
  97         @param capacity The capacity of the new OSArray.  If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.
  98         @result Returns a reference to an new instance of OSArray or 0 if an error occurred.
  99     */
 100     static OSArray *withArray(const OSArray *array,
 101                               unsigned int capacity = 0);
 102
 103     /*!
 104         @function initWithCapacity
 105         @abstract A member function which initializes an instance of OSArray.
 106         @param capacity The initial capacity of the new instance of OSArray.
 107         @result Returns a true if initialization succeeded or false if not.
 108     */
 109     virtual bool initWithCapacity(unsigned int capacity);
 110     /*!
 111         @function initWithObjects
 112         @abstract A member function which initializes an instance of OSArray and populates it with the given list of objects.
 113         @param objects A static array containing references to OSMetaClassBase derived objects.
 114         @param count The number of objects to added to the array.
 115         @param capacity The initial capacity of the new instance of OSArray.  If 0, the capacity will be set to the same value as the 'count' parameter, else capacity must be greater than or equal to the value of 'count'.
 116         @result Returns a true if initialization succeeded or false if not.
 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 which initializes an instance of OSArray and populates it with the contents of the supplied OSArray object.
 124         @param anArray An instance of OSArray containing the references to objects which will be copied to the new instances of OSArray.
 125         @param capacity The initial capacity of the new instance of OSArray.  If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.
 126         @result Returns a true if initialization succeeded or false if not.
 127     */
 128     virtual bool initWithArray(const OSArray *anArray,
 129                                unsigned int theCapacity = 0);
 130     /*!
 131         @function free
 132         @abstract Deallocates and releases all resources used by the OSArray instance.  Normally, this is not called directly.
 133         @discussion This function should not be called directly, use release() instead.
 134     */
 135     virtual void free();
 136
 137     /*!
 138         @function getCount
 139         @abstract A member function which returns the number of references contained within the OSArray object.
 140         @result Returns the number of items within the OSArray object.
 141     */
 142     virtual unsigned int getCount() const;
 143     /*!
 144         @function getCapacity
 145         @abstract A member function which returns the storage capacity of the OSArray object.
 146         @result Returns the storage capacity of the OSArray object.
 147     */
 148     virtual unsigned int getCapacity() const;
 149     /*!
 150         @function getCapacityIncrement
 151         @abstract A member function which returns the size by which the array will grow.
 152         @result Returns the size by which the array will grow.
 153     */
 154     virtual unsigned int getCapacityIncrement() const;
 155     /*!
 156         @function setCapacityIncrement
 157         @abstract A member function which sets the growth size of the array.
 158         @result Returns the new growth size.
 159     */
 160     virtual unsigned int setCapacityIncrement(unsigned increment);
 161
 162     /*!
 163         @function ensureCapacity
 164         @abstract A member function which will expand the size of the collection to a given storage capacity.
 165         @param newCapacity The new capacity for the array.
 166         @result Returns the new capacity of the array or the previous capacity upon error.
 167     */
 168     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 169
 170     /*!
 171         @function flushCollection
 172         @abstract A member function which removes and releases all items within the array.
 173     */
 174     virtual void flushCollection();
 175
 176     /*!
 177         @function setObject
 178         @abstract A member function which appends an object onto the end of the array.
 179         @param anObject The object to add to the OSArray instance.  The object will be retained automatically.
 180         @result Returns true if the addition of 'anObject' was successful, false if not; failure usually results from failing to allocate the necessary memory.
 181     */
 182     virtual bool setObject(const OSMetaClassBase *anObject);
 183     /*!
 184         @function setObject
 185         @abstract A member function which inserts an object into the array at a particular index.
 186         @param index The index into the array to insert the object.
 187         @param anObject The object to add to the OSArray instance.  The object will be retained automatically.
 188         @result Returns true if the addition of 'anObject' was successful, false if not.
 189     */
 190     virtual bool setObject(unsigned int index, const OSMetaClassBase *anObject);
 191
 192     /*!
 193         @function merge
 194         @abstract A member function which appends the contents of an array onto the receiving array.
 195         @param otherArray The array whose contents will be appended to the reveiving array.
 196         @result Returns true when merging was successful, false otherwise.
 197     */
 198     virtual bool merge(const OSArray *otherArray);
 199
 200     /*!
 201         @function replaceObject
 202         @abstract A member function which will replace an object in an array at a given index.  The original object will be released and the new object will be retained.
 203         @param index The index into the array at which the new object will be placed.
 204         @param anObject The object to be placed into the array.
 205     */
 206     virtual void replaceObject(unsigned int index, const OSMetaClassBase *anObject);
 207     /*!
 208         @function removeObject
 209         @abstract A member function which removes an object from the array.
 210         @param index The index of the object to be removed.
 211         @discussion This function removes an object from the array which is located at a given index.  Once removed the contents of the array will shift to fill in the vacated spot. The removed object is automatically released.
 212     */
 213     virtual void removeObject(unsigned int index);
 214
 215     /*!
 216         @function isEqualTo
 217         @abstract A member function which tests the equality of the values of two OSArray objects.
 218         @param anArray The array object being compared against the receiver.
 219         @result Returns true if the two arrays are equivalent or false otherwise.
 220     */
 221     virtual bool isEqualTo(const OSArray *anArray) const;
 222     /*!
 223         @function isEqualTo
 224         @abstract A member function which compares the equality of the values of a receiving array to an arbitrary object.
 225         @param anObject The object to be compared against the receiver.
 226         @result Returns true if the two objects are equivalent, that is they are either the same object or they are both arrays containing the same or equivalent objects, or false otherwise.
 227     */
 228     virtual bool isEqualTo(const OSMetaClassBase *anObject) const;
 229
 230     /*!
 231         @function getObject
 232         @abstract A member function which returns a reference to an object located within the array at a given index.  The caller should not release the returned object.
 233         @param index The index into the array from which the reference to an object is taken.
 234         @result Returns a reference to an object or 0 if the index is beyond the bounds of the array.
 235     */
 236     virtual OSObject *getObject(unsigned int index) const;
 237     /*!
 238         @function getLastObject
 239         @abstract A member function which returns a reference to the last object in the array. The caller should not release the returned object.
 240         @result Returns a reference to the last object in the array or 0 if the array is empty.
 241     */
 242     virtual OSObject *getLastObject() const;
 243
 244     /*!
 245         @function getNextIndexOfObject
 246         @abstract A member function which searches the array for the next instance of a specific object, at or beyond the supplied index.
 247         @result Returns the next index of the object in the array or (-1) if none is found.
 248     */
 249     virtual unsigned int getNextIndexOfObject(const OSMetaClassBase * anObject,
 250                                                unsigned int index) 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 array 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 array and its collections.
 272         @discussion This function copies this array included collections 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(OSArray, 0);
 279     OSMetaClassDeclareReservedUnused(OSArray, 1);
 280     OSMetaClassDeclareReservedUnused(OSArray, 2);
 281     OSMetaClassDeclareReservedUnused(OSArray, 3);
 282     OSMetaClassDeclareReservedUnused(OSArray, 4);
 283     OSMetaClassDeclareReservedUnused(OSArray, 5);
 284     OSMetaClassDeclareReservedUnused(OSArray, 6);
 285     OSMetaClassDeclareReservedUnused(OSArray, 7);
 286 };
 287
 288 #endif /* !_OS_OSARRAY_H */