libkern/libkern/c++/OSSymbol.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 /* IOSymbol.h created by gvdl on Fri 1998-10-30 */
  26 /* IOSymbol must be created through the factory methods and thus is not subclassable. */
  27
  28 #ifndef _OS_OSSYMBOL_H
  29 #define _OS_OSSYMBOL_H
  30
  31 #include <libkern/c++/OSString.h>
  32
  33 /*!
  34     @class OSSymbol
  35     @abstract A container class whose instances represent unique string values.
  36     @discussion
  37     An OSSymbol object represents a unique string value.  When creating an OSSymbol, a string is given and an OSSymbol representing this string is created if none exist for this string.  If a symbol for this string already exists, then a reference to an existing symbol is returned.
  38 */
  39 class OSSymbol : public OSString
  40 {
  41     friend class OSSymbolPool;
  42
  43     OSDeclareAbstractStructors(OSSymbol)
  44
  45 private:
  46     struct ExpansionData { };
  47
  48     /*! @var reserved
  49         Reserved for future use.  (Internal use only)  */
  50     ExpansionData *reserved;
  51
  52     static void initialize();
  53
  54     friend void checkModuleForSymbols(void); /* in catalogue? */
  55
  56     // The string init methods have to be removed from the inheritance.
  57     virtual bool initWithString(const OSString *aString);
  58     virtual bool initWithCString(const char *cString);
  59     virtual bool initWithCStringNoCopy(const char *cString);
  60
  61 protected:
  62     /*!
  63         @function free
  64         @abstract A member function to release all resources created or used by the OSString object.
  65         @discussion This function should not be called directly, use release() instead.
  66     */
  67     virtual void free();
  68
  69 public:
  70     /*!
  71         @function withString
  72         @abstract A static constructor function to create an OSSymbol instance from an OSString object or returns an existing OSSymbol object based on the OSString object given.
  73         @param aString An OSString object.
  74         @result Returns a unique OSSymbol object for the string given.
  75     */
  76     static const OSSymbol *withString(const OSString *aString);
  77     /*!
  78         @function withCString
  79         @abstract A static constructor function to create an OSSymbol instance from a simple c-string returns an existing OSSymbol object based on the string object given.
  80         @param cString A c-string.
  81         @result Returns a unique OSSymbol object for the string given.
  82     */
  83     static const OSSymbol *withCString(const char *cString);
  84     /*!
  85         @function withCStringNoCopy
  86         @abstract A static constructor function to create an OSSymbol instance from a simple c-string, but does not copy the string to the container.
  87         @param cString A c-string.
  88         @result Returns a unique OSSymbol object for the string given.
  89     */
  90     static const OSSymbol *withCStringNoCopy(const char *cString);
  91
  92     /*!
  93         @function isEqualTo
  94         @abstract A member function which tests the equality between two OSSymbol objects.  Two OSSymbol objects are only equivalent when their references are identical
  95         @param aSymbol The OSSymbol object to be compared against the receiver.
  96         @result Returns true if the two objects are equivalent, false otherwise.
  97     */
  98     virtual bool isEqualTo(const OSSymbol *aSymbol) const;
  99     /*!
 100         @function isEqualTo
 101         @abstract A member function which tests the equality between an OSSymbol object and a simple c-string.
 102         @param aCString The c-string to be compared against the receiver.
 103         @result Returns true if the OSSymbol's internal string representation is equivalent to the c-string it is being compared against, false otherwise.
 104     */
 105     virtual bool isEqualTo(const char *aCString) const;
 106     /*!
 107         @function isEqualTo
 108         @abstract A member function which tests the equality between an OSSymbol object and and arbitrary OSObject derived object.
 109         @param obj The OSObject derived object to be compared against the receiver.
 110         @result Returns true if the OSSymbol and the OSObject objects are equivalent.
 111     */
 112     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 113
 114     /* OSRuntime only INTERNAL API - DO NOT USE */
 115     static void checkForPageUnload(void *startAddr, void *endAddr);
 116
 117
 118     OSMetaClassDeclareReservedUnused(OSSymbol, 0);
 119     OSMetaClassDeclareReservedUnused(OSSymbol, 1);
 120     OSMetaClassDeclareReservedUnused(OSSymbol, 2);
 121     OSMetaClassDeclareReservedUnused(OSSymbol, 3);
 122     OSMetaClassDeclareReservedUnused(OSSymbol, 4);
 123     OSMetaClassDeclareReservedUnused(OSSymbol, 5);
 124     OSMetaClassDeclareReservedUnused(OSSymbol, 6);
 125     OSMetaClassDeclareReservedUnused(OSSymbol, 7);
 126 };
 127
 128 #endif /* !_OS_OSSYMBOL_H */