libkern/libkern/c++/OSDictionary.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 /*
  23  * Copyright (c) 1998-1999 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * HISTORY
  26  *
  27  * OSDictionary.h created by rsulack on Wed 17-Sep-1997
  28  * OSDictionary.h converted to C++ by gvdl on Fri 1998-10-30
  29  */
  30
  31 #ifndef _IOKIT_IODICTIONARY_H
  32 #define _IOKIT_IODICTIONARY_H
  33
  34 #include <libkern/c++/OSCollection.h>
  35
  36 class OSArray;
  37 class OSSymbol;
  38 class OSString;
  39
  40 /*!
  41     @class OSDictionary
  42     @abstract A collection class whose instances maintain a list of object references.  Objects in the collection are acquired with unique associative keys.
  43     @discussion
  44     An instance of OSDictionary is a mutable container which contains a list of OSMetaClassBase derived object references and these objects are identified and acquired by unique associative keys.  When an object is placed into a dictionary, a unique identifier or key must provided to identify the object within the collection. The key then must be provided to find the object within the collection.  If an object is not found within the collection, a 0 is returned.  Placing an object into a dictionary for a key, which already identifies an object within that dictionary, will replace the current object with the new object.
  45
  46     Objects placed into a dictionary are automatically retained and objects removed or replaced are automatically released.  All objects are released when the collection is freed.
  47 */
  48 class OSDictionary : public OSCollection
  49 {
  50     OSDeclareDefaultStructors(OSDictionary)
  51
  52 protected:
  53     struct dictEntry {
  54         const OSSymbol *key;
  55         const OSMetaClassBase *value;
  56     };
  57     dictEntry *dictionary;
  58     unsigned int count;
  59     unsigned int capacity;
  60     unsigned int capacityIncrement;
  61
  62     struct ExpansionData { };
  63
  64     /*! @var reserved
  65         Reserved for future use.  (Internal use only)  */
  66     ExpansionData *reserved;
  67
  68     // Member functions used by the OSCollectionIterator class.
  69     virtual unsigned int iteratorSize() const;
  70     virtual bool initIterator(void *iterator) const;
  71     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const;
  72
  73 public:
  74     /*!
  75         @function withCapacity
  76         @abstract A static constructor function to create and initialize an instance of OSDictionary.
  77         @param capacity The initial storage capacity of the dictionary object.
  78         @result Returns an instance of OSDictionary or 0 on failure.
  79     */
  80     static OSDictionary *withCapacity(unsigned int capacity);
  81     /*!
  82         @function withObjects
  83         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
  84         @param objects A static array of OSMetaClassBase derived objects.
  85         @param keys A static array of OSSymbol keys.
  86         @param count The number of items to be placed into the dictionary.
  87         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.
  88         @result Returns an instance of OSDictionary or 0 on failure.
  89     */
  90     static OSDictionary *withObjects(const OSObject *objects[],
  91                                      const OSSymbol *keys[],
  92                                      unsigned int count,
  93                                      unsigned int capacity = 0);
  94     /*!
  95         @function withObjects
  96         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
  97         @param objects A static array of OSMetaClassBase derived objects.
  98         @param keys A static array of OSString keys.
  99         @param count The number of items to be placed into the dictionary.
 100         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.
 101         @result Returns an instance of OSDictionary or 0 on failure.
 102     */
 103     static OSDictionary *withObjects(const OSObject *objects[],
 104                                      const OSString *keys[],
 105                                      unsigned int count,
 106                                      unsigned int capacity = 0);
 107     /*!
 108         @function withDictionary
 109         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects from another dictionary.
 110         @param dict A dictionary whose contents will be placed in the new instance.
 111         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the number of elements in the dictionary object, else the capacity must be greater than or equal to the number of elements in the dictionary.
 112         @result Returns an instance of OSDictionary or 0 on failure.
 113     */
 114     static OSDictionary *withDictionary(const OSDictionary *dict,
 115                                         unsigned int capacity = 0);
 116
 117     /*!
 118         @function initWithCapacity
 119         @abstract A member function to initialize an instance of OSDictionary.
 120         @param capacity The initial storage capacity of the dictionary object.
 121         @result Returns true if initialization succeeded or false on failure.
 122     */
 123     virtual bool initWithCapacity(unsigned int capacity);
 124     /*!
 125         @function initWithObjects
 126         @abstract A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
 127         @param objects A static array of OSMetaClassBase derived objects to be placed into the dictionary.
 128         @param keys A static array of OSSymbol keys which identify the corresponding objects provided in the 'objects' parameter.
 129         @param count The number of objects provided to the dictionary.
 130         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.
 131         @result Returns true if initialization succeeded or false on failure.
 132     */
 133     virtual bool initWithObjects(const OSObject *objects[],
 134                                  const OSSymbol *keys[],
 135                                  unsigned int count,
 136                                  unsigned int capacity = 0);
 137     /*!
 138         @function initWithObjects
 139         @abstract A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
 140         @param objects A static array of OSMetaClassBase derived objects to be placed into the dictionary.
 141         @param keys A static array of OSString keys which identify the corresponding objects provided in the 'objects' parameter.
 142         @param count The number of objects provided to the dictionary.
 143         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.
 144         @result Returns true if initialization succeeded or false on failure.
 145     */
 146     virtual bool initWithObjects(const OSObject *objects[],
 147                                  const OSString *keys[],
 148                                  unsigned int count,
 149                                  unsigned int capacity = 0);
 150     /*!
 151         @function initWithDictionary
 152         @abstract A member function to initialize an instance of OSDictionary and populate it with the contents of another dictionary.
 153         @param dict The dictionary containing the objects to be used to populate the receiving dictionary.
 154         @param capacity The initial storage capacity of the dictionary.  If 0, the value of capacity will be set to the number of elements in the dictionary object, else the value of capacity must be greater than or equal to the number of elements in the dictionary object.
 155         @result Returns true if initialization succeeded or false on failure.
 156     */
 157     virtual bool initWithDictionary(const OSDictionary *dict,
 158                                     unsigned int capacity = 0);
 159     /*!
 160         @function free
 161         @abstract A member functions to deallocate and release all resources used by the OSDictionary instance.
 162         @discussion This function should not be called directly, use release() instead.
 163     */
 164     virtual void free();
 165
 166     /*!
 167         @function getCount
 168         @abstract A member function which returns the current number of objects within the collection.
 169         @result Returns the number of objects contained within the dictionary.
 170     */
 171     virtual unsigned int getCount() const;
 172     /*!
 173         @function getCapacity
 174         @abstract A member function which returns the storage capacity of the collection.
 175         @result Returns the storage capacity of the dictionary.
 176     */
 177     virtual unsigned int getCapacity() const;
 178     /*!
 179         @function getCapacityIncrement
 180         @abstract A member function which returns the growth size for the collection.
 181     */
 182     virtual unsigned int getCapacityIncrement() const;
 183     /*!
 184         @function setCapacityIncrement
 185         @abstract A member function to set the growth size of the collection.
 186         @param increment The new growth size.
 187         @result Returns the new capacity increment.
 188     */
 189     virtual unsigned int setCapacityIncrement(unsigned increment);
 190
 191     /*!
 192         @function ensureCapacity
 193         @abstract Member function to grow the size of the collection.
 194         @param newCapacity The new capacity for the dictionary to expand to.
 195         @result Returns the new capacity of the dictionary or the previous capacity upon error.
 196     */
 197     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 198
 199     /*!
 200         @function flushCollection
 201         @abstract A member function which removes and releases all objects within the collection.
 202     */
 203     virtual void flushCollection();
 204
 205     /*!
 206         @function setObject
 207         @abstract A member function which places an object into the dictionary and identified by a unique key.
 208         @param aKey A unique OSSymbol identifying the object placed within the collection.
 209         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 210         @result Returns true if the addition of an object was successful, false otherwise.
 211     */
 212     virtual bool setObject(const OSSymbol *aKey, const OSMetaClassBase *anObject);
 213     /*!
 214         @function setObject
 215         @abstract A member function which places an object into the dictionary and identified by a unique key.
 216         @param aKey A unique OSString identifying the object placed within the collection.
 217         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 218         @result Returns true if the addition of an object was successful, false otherwise.
 219     */
 220     virtual bool setObject(const OSString *aKey, const OSMetaClassBase *anObject);
 221     /*!
 222         @function setObject
 223         @abstract A member function which places an object into the dictionary and identified by a unique key.
 224         @param aKey A unique string identifying the object placed within the collection.
 225         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 226         @result Returns true if the addition of an object was successful, false otherwise.
 227     */
 228     virtual bool setObject(const char *aKey, const OSMetaClassBase *anObject);
 229
 230     /*!
 231         @function removeObject
 232         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 233         @param aKey A unique OSSymbol identifying the object to be removed from the dictionary.
 234     */
 235     virtual void removeObject(const OSSymbol *aKey);
 236     /*!
 237         @function removeObject
 238         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 239         @param aKey A unique OSString identifying the object to be removed from the dictionary.
 240     */
 241     virtual void removeObject(const OSString *aKey);
 242     /*!
 243         @function removeObject
 244         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 245         @param aKey A unique string identifying the object to be removed from the dictionary.
 246     */
 247     virtual void removeObject(const char *aKey);
 248
 249     /*!
 250         @function merge
 251         @abstract A member function which merges the contents of a dictionary into the receiver.
 252         @param aDictionary The dictionary whose contents are to be merged with the receiver.
 253         @result Returns true if the merger is successful, false otherwise.
 254         @discussion If there are keys in 'aDictionary' which match keys in the receiving dictionary, then the objects in the receiver are replaced by those from 'aDictionary', the replaced objects are released.
 255     */
 256     virtual bool merge(const OSDictionary *aDictionary);
 257
 258     /*!
 259         @function getObject
 260         @abstract A member function to find an object in the dictionary associated by a given key.
 261         @param aKey The unique OSSymbol key identifying the object to be returned to caller.
 262         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 263     */
 264     virtual OSObject *getObject(const OSSymbol *aKey) const;
 265     /*!
 266         @function getObject
 267         @abstract A member function to find an object in the dictionary associated by a given key.
 268         @param aKey The unique OSString key identifying the object to be returned to caller.
 269         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 270     */
 271     virtual OSObject *getObject(const OSString *aKey) const;
 272     /*!
 273         @function getObject
 274         @abstract A member function to find an object in the dictionary associated by a given key.
 275         @param aKey The unique string identifying the object to be returned to caller.
 276         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 277     */
 278     virtual OSObject *getObject(const char *aKey) const;
 279
 280     /*!
 281         @function isEqualTo
 282         @abstract A member function to test the equality of the intersections of two dictionaries.
 283         @param aDictionary The dictionary to be compared against the receiver.
 284         @param keys An OSArray or OSDictionary containing the keys describing the intersection for the comparison.
 285         @result Returns true if the intersections of the two dictionaries are equal.
 286     */
 287     virtual bool isEqualTo(const OSDictionary *aDictionary, const OSCollection *keys) const;
 288     /*!
 289         @function isEqualTo
 290         @abstract A member function to test the equality of two dictionaries.
 291         @param aDictionary The dictionary to be compared against the receiver.
 292         @result Returns true if the dictionaries are equal.
 293     */
 294     virtual bool isEqualTo(const OSDictionary *aDictionary) const;
 295     /*!
 296         @function isEqualTo
 297         @abstract A member function to test the equality between the receiver and an unknown object.
 298         @param anObject An object to be compared against the receiver.
 299         @result Returns true if the objects are equal.
 300     */
 301     virtual bool isEqualTo(const OSMetaClassBase *anObject) const;
 302
 303     /*!
 304         @function serialize
 305         @abstract A member function which archives the receiver.
 306         @param s The OSSerialize object.
 307         @result Returns true if serialization was successful, false if not.
 308     */
 309     virtual bool serialize(OSSerialize *s) const;
 310
 311
 312     OSMetaClassDeclareReservedUnused(OSDictionary, 0);
 313     OSMetaClassDeclareReservedUnused(OSDictionary, 1);
 314     OSMetaClassDeclareReservedUnused(OSDictionary, 2);
 315     OSMetaClassDeclareReservedUnused(OSDictionary, 3);
 316     OSMetaClassDeclareReservedUnused(OSDictionary, 4);
 317     OSMetaClassDeclareReservedUnused(OSDictionary, 5);
 318     OSMetaClassDeclareReservedUnused(OSDictionary, 6);
 319     OSMetaClassDeclareReservedUnused(OSDictionary, 7);
 320 };
 321
 322 #endif /* !_IOKIT_IODICTIONARY_H */