libkern/libkern/c++/OSString.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 /* IOString.h created by rsulack on Wed 17-Sep-1997 */
  26 /* IOString.h converted to C++ by gvdl on Fri 1998-10-30 */
  27
  28 #ifndef _OS_OSSTRING_H
  29 #define _OS_OSSTRING_H
  30
  31 #include <libkern/c++/OSObject.h>
  32
  33 class OSData;
  34
  35 enum { kOSStringNoCopy = 0x00000001 };
  36
  37 /*!
  38     @class OSString
  39     @abstract A container class for managing strings.
  40     @discussion
  41     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.
  42 */
  43 class OSString : public OSObject
  44 {
  45     OSDeclareDefaultStructors(OSString)
  46
  47 protected:
  48     unsigned int    flags;
  49     unsigned int    length;
  50     char           *string;
  51
  52 public:
  53     /*!
  54         @function withString
  55         @abstract Static constructor function to create and initialize an instance of OSString from another OSString.
  56         @param aString An OSString object.
  57         @result Returns an instance of OSString or 0 on error.
  58     */
  59     static OSString *withString(const OSString *aString);
  60     /*!
  61         @function withCString
  62         @abstract Static constructor function to create and initialize an instance of OSString.
  63         @param cString A simple c-string.
  64         @result Returns an instance of OSString or 0 on error.
  65     */
  66     static OSString *withCString(const char *cString);
  67     /*!
  68         @function withCStringNoCopy
  69         @abstract Static constructor function to create and initialize an instance of OSString but does not copy the original c-string into container.
  70         @param cString A simple c-string.
  71         @result Returns an instance of OSString or 0 on error.
  72     */
  73     static OSString *withCStringNoCopy(const char *cString);
  74
  75     /*!
  76         @function initWithString
  77         @abstract Member function to initialize an instance of OSString from another OSString object.
  78         @param aString An OSString object.
  79         @result Returns true on success, false otherwise.
  80     */
  81     virtual bool initWithString(const OSString *aString);
  82     /*!
  83         @function initWithCString
  84         @abstract Member function to initialize an instance of OSString with a simple c-string.
  85         @param cString A simple c-string.
  86         @result Returns true on success, false otherwise.
  87     */
  88     virtual bool initWithCString(const char *cString);
  89     /*!
  90         @function initWithCStringNoCopy
  91         @abstract Member function to initialize an instance of OSString with a simple c-string but does not copy the string into the container.
  92         @param cString A simple c-string.
  93         @result Returns true on success, false otherwise.
  94     */
  95     virtual bool initWithCStringNoCopy(const char *cString);
  96     /*!
  97         @function free
  98         @abstract Releases all resources used by the OSString object.
  99         @discussion This function should not be called directly, use release() instead.
 100     */
 101     virtual void free();
 102
 103     /*!
 104         @function getLength
 105         @abstract A member function to return the length of the string.
 106         @result Returns the length of the string.
 107     */
 108     virtual unsigned int getLength() const;
 109     /*!
 110         @function getChar
 111         @abstract Returns a character at a particular index in the string object.
 112         @param index The index into the string.
 113         @result Returns a character.
 114     */
 115     virtual char getChar(unsigned int index) const;
 116     /*!
 117         @function setChar
 118         @abstract Replaces a character at a particular index in the string object.
 119         @param index The index into the string.
 120         @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.
 121     */
 122     virtual bool setChar(char aChar, unsigned int index);
 123
 124     /*!
 125         @function getCStringNoCopy
 126         @abstract Returns a pointer to the internal c-string array.
 127         @result Returns a pointer to the internal c-string array.
 128     */
 129     virtual const char *getCStringNoCopy() const;
 130
 131     /*!
 132         @function isEqualTo
 133         @abstract A member function to test the equality of two OSString objects.
 134         @param aString An OSString object.
 135         @result Returns true if the two strings are equal, false otherwise.
 136     */
 137     virtual bool isEqualTo(const OSString *aString) const;
 138     /*!
 139         @function isEqualTo
 140         @abstract A member function to test the equality of c-string and the internal string array of the receiving OSString object.
 141         @param aCString A simple c-string.
 142         @result Returns true if the two strings are equal, false otherwise.
 143     */
 144     virtual bool isEqualTo(const char *aCString) const;
 145     /*!
 146         @function isEqualTo
 147         @abstract A member function to test the equality of an unknown OSObject derived object and the OSString instance.
 148         @param obj An OSObject derived object.
 149         @result Returns true if the two objects are equivalent, false otherwise.
 150     */
 151     virtual bool isEqualTo(const OSMetaClassBase *obj) const;
 152     /*!
 153         @function isEqualTo
 154         @abstract A member function to test the equality of an unknown OSData object and the OSString instance.
 155         @param obj An OSData object.
 156         @result Returns true if the two objects are equivalent, false otherwise.
 157     */
 158     virtual bool isEqualTo(const OSData *obj) const;
 159
 160     /*!
 161         @function serialize
 162         @abstract A member function which archives the receiver.
 163         @param s The OSSerialize object.
 164         @result Returns true if serialization was successful, false if not.
 165     */
 166     virtual bool serialize(OSSerialize *s) const;
 167
 168     OSMetaClassDeclareReservedUnused(OSString,  0);
 169     OSMetaClassDeclareReservedUnused(OSString,  1);
 170     OSMetaClassDeclareReservedUnused(OSString,  2);
 171     OSMetaClassDeclareReservedUnused(OSString,  3);
 172     OSMetaClassDeclareReservedUnused(OSString,  4);
 173     OSMetaClassDeclareReservedUnused(OSString,  5);
 174     OSMetaClassDeclareReservedUnused(OSString,  6);
 175     OSMetaClassDeclareReservedUnused(OSString,  7);
 176     OSMetaClassDeclareReservedUnused(OSString,  8);
 177     OSMetaClassDeclareReservedUnused(OSString,  9);
 178     OSMetaClassDeclareReservedUnused(OSString, 10);
 179     OSMetaClassDeclareReservedUnused(OSString, 11);
 180     OSMetaClassDeclareReservedUnused(OSString, 12);
 181     OSMetaClassDeclareReservedUnused(OSString, 13);
 182     OSMetaClassDeclareReservedUnused(OSString, 14);
 183     OSMetaClassDeclareReservedUnused(OSString, 15);
 184 };
 185
 186 #endif /* !_OS_OSSTRING_H */