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