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