libkern/libkern/c++/OSString.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_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 License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /* IOString.h created by rsulack on Wed 17-Sep-1997 */
  29 /* IOString.h converted to C++ by gvdl on Fri 1998-10-30 */
  30
  31 #ifndef _OS_OSSTRING_H
  32 #define _OS_OSSTRING_H
  33
  34 #include <libkern/c++/OSObject.h>
  35
  36 class OSData;
  37
  38 enum { kOSStringNoCopy = 0x00000001 };
  39
  40 /*!
  41     @class OSString
  42     @abstract A container class for managing strings.
  43     @discussion
  44     OSString is a container class for managing arrays of characters.  Strings come in two varieties, mutable and immutable.  An immutable OSString string is one which was created or initialized with the "NoCopy" functions, all other strings are mutable.  When modifying an immutable string, the function called to perform the action will fail.
  45 */
  46 class OSString : public OSObject
  47 {
  48     OSDeclareDefaultStructors(OSString)
  49
  50 protected:
  51     unsigned int    flags;
  52     unsigned int    length;
  53     char           *string;
  54
  55 public:
  56     /*!
  57         @function withString
  58         @abstract Static constructor function to create and initialize an instance of OSString from another OSString.
  59         @param aString An OSString object.
  60         @result Returns an instance of OSString or 0 on error.
  61     */
  62     static OSString *withString(const OSString *aString);
  63     /*!
  64         @function withCString
  65         @abstract Static constructor function to create and initialize an instance of OSString.
  66         @param cString A simple c-string.
  67         @result Returns an instance of OSString or 0 on error.
  68     */
  69     static OSString *withCString(const char *cString);
  70     /*!
  71         @function withCStringNoCopy
  72         @abstract Static constructor function to create and initialize an instance of OSString but does not copy the original c-string into container.
  73         @param cString A simple c-string.
  74         @result Returns an instance of OSString or 0 on error.
  75     */
  76     static OSString *withCStringNoCopy(const char *cString);
  77
  78     /*!
  79         @function initWithString
  80         @abstract Member function to initialize an instance of OSString from another OSString object.
  81         @param aString An OSString object.
  82         @result Returns true on success, false otherwise.
  83     */
  84     virtual bool initWithString(const OSString *aString);
  85     /*!
  86         @function initWithCString
  87         @abstract Member function to initialize an instance of OSString with a simple c-string.
  88         @param cString A simple c-string.
  89         @result Returns true on success, false otherwise.
  90     */
  91     virtual bool initWithCString(const char *cString);
  92     /*!
  93         @function initWithCStringNoCopy
  94         @abstract Member function to initialize an instance of OSString with a simple c-string but does not copy the string into the container.
  95         @param cString A simple c-string.
  96         @result Returns true on success, false otherwise.
  97     */
  98     virtual bool initWithCStringNoCopy(const char *cString);
  99     /*!
 100         @function free
 101         @abstract Releases all resources used by the OSString object.
 102         @discussion This function should not be called directly, use release() instead.
 103     */
 104     virtual void free();
 105
 106     /*!
 107         @function getLength
 108         @abstract A member function to return the length of the string.
 109         @result Returns the length of the string.
 110     */
 111     virtual unsigned int getLength() const;
 112     /*!
 113         @function getChar
 114         @abstract Returns a character at a particular index in the string object.
 115         @param index The index into the string.
 116         @result Returns a character.
 117     */
 118     virtual char getChar(unsigned int index) const;
 119     /*!
 120         @function setChar
 121         @abstract Replaces a character at a particular index in the string object.
 122         @param index The index into the string.
 123         @result Returns true if the character was successfully replaced or false if the string is immutable or index was beyond the bounds of the character array.
 124     */
 125     virtual bool setChar(char aChar, unsigned int index);
 126
 127     /*!
 128         @function getCStringNoCopy
 129         @abstract Returns a pointer to the internal c-string array.
 130         @result Returns a pointer to the internal c-string array.
 131     */
 132     virtual const char *getCStringNoCopy() const;
 133
 134     /*!
 135         @function isEqualTo
 136         @abstract A member function to test the equality of two OSString objects.
 137         @param aString An OSString object.
 138         @result Returns true if the two strings are equal, false otherwise.
 139     */
 140     virtual bool isEqualTo(const OSString *aString) const;
 141     /*!
 142         @function isEqualTo
 143         @abstract A member function to test the equality of c-string and the internal string array of the receiving OSString object.
 144         @param aCString A simple c-string.
 145         @result Returns true if the two strings are equal, false otherwise.
 146     */
 147     virtual bool isEqualTo(const char *aCString) const;
 148     /*!
 149         @function isEqualTo
 150         @abstract A member function to test the equality of an unknown OSObject derived object and the OSString instance.
 151         @param obj An OSObject derived object.
 152         @result Returns true if the two objects are equivalent, false otherwise.
 153     */
 154     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 155     /*!
 156         @function isEqualTo
 157         @abstract A member function to test the equality of an unknown OSData object and the OSString instance.
 158         @param obj An OSData object.
 159         @result Returns true if the two objects are equivalent, false otherwise.
 160     */
 161     virtual bool isEqualTo(const OSData *obj) const;
 162
 163     /*!
 164         @function serialize
 165         @abstract A member function which archives the receiver.
 166         @param s The OSSerialize object.
 167         @result Returns true if serialization was successful, false if not.
 168     */
 169     virtual bool serialize(OSSerialize *s) const;
 170
 171     OSMetaClassDeclareReservedUnused(OSString,  0);
 172     OSMetaClassDeclareReservedUnused(OSString,  1);
 173     OSMetaClassDeclareReservedUnused(OSString,  2);
 174     OSMetaClassDeclareReservedUnused(OSString,  3);
 175     OSMetaClassDeclareReservedUnused(OSString,  4);
 176     OSMetaClassDeclareReservedUnused(OSString,  5);
 177     OSMetaClassDeclareReservedUnused(OSString,  6);
 178     OSMetaClassDeclareReservedUnused(OSString,  7);
 179     OSMetaClassDeclareReservedUnused(OSString,  8);
 180     OSMetaClassDeclareReservedUnused(OSString,  9);
 181     OSMetaClassDeclareReservedUnused(OSString, 10);
 182     OSMetaClassDeclareReservedUnused(OSString, 11);
 183     OSMetaClassDeclareReservedUnused(OSString, 12);
 184     OSMetaClassDeclareReservedUnused(OSString, 13);
 185     OSMetaClassDeclareReservedUnused(OSString, 14);
 186     OSMetaClassDeclareReservedUnused(OSString, 15);
 187 };
 188
 189 #endif /* !_OS_OSSTRING_H */