libkern/libkern/c++/OSString.h

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