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