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
  39 /*!
  40  * @header
  41  *
  42  * @abstract
  43  * This header declares the OSString container class.
  44  */
  45
  46
  47  /* Not to be included in headerdoc.
  48   *
  49   * For internal use.
  50   */
  51  enum { kOSStringNoCopy = 0x00000001 };
  52
  53
  54 /*!
  55  * @class OSString
  56  *
  57  * @abstract
  58  * OSString wraps a C string in a C++ object for use in Libkern collections.
  59  *
  60  * @discussion
  61  * OSString is a container class for managing arrays of characters.
  62  * An OSString normally maintains its own character buffer and allows changes,
  63  * but you can create an "immutable" OSString
  64  * that references an external C string
  65  * buffer using the "NoCopy" creator functions.
  66  * Functions called to change the contents of an immutable OSString will fail.
  67  *
  68  * <b>Encodings</b>
  69  *
  70  * OSString makes no provisions for different character encodings and
  71  * assumes that a string is a nul-terminated sequence of single-byte characters.
  72  * User-space code must either assume an encoding (typically ASCII or UTF-8)
  73  * or determine it in some other way (such as an IORegistryEntry property).
  74  *
  75  * <b>Altering Strings</b>
  76  *
  77  * OSString's indended use is as a reference-counted object container
  78  * for a C string and little more.
  79  * While OSString provides full access to the underlying C string,
  80  * it provides little in the way of string object manipulation;
  81  * there are no append or insert functions,
  82  * only a set-character function.
  83  * If you need to manipulate OSStrings,
  84  * it's generally best to get the C strings,
  85  * alter them as necessary, and create a new OSString object
  86  * from the resulting C string.
  87  *
  88  * <b>Use Restrictions</b>
  89  *
  90  * With very few exceptions in the I/O Kit, all Libkern-based C++
  91  * classes, functions, and macros are <b>unsafe</b>
  92  * to use in a primary interrupt context.
  93  * Consult the I/O Kit documentation related to primary interrupts
  94  * for more information.
  95  *
  96  * OSString provides no concurrency protection;
  97  * it's up to the usage context to provide any protection necessary.
  98  * Some portions of the I/O Kit, such as
  99  * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
 100  * handle synchronization via defined member functions for setting
 101  * properties.
 102  */
 103 class OSString : public OSObject
 104 {
 105     OSDeclareDefaultStructors(OSString)
 106
 107 protected:
 108     unsigned int   flags;
 109     unsigned int   length;
 110     char         * string;
 111
 112 public:
 113
 114
 115    /*!
 116     * @function withString
 117     *
 118     * @abstract
 119     * Creates and initializes an OSString from another OSString.
 120     *
 121     * @param aString   The OSString object whose contents to copy.
 122     *
 123     * @result
 124     * An instance of OSString representing
 125     * the same characters as <code>aString</code>,
 126     * and with a reference count of 1;
 127     * <code>NULL</code> on failure.
 128     *
 129     * @discussion
 130     * The new OSString is a distinct instance from <code>aString</code>,
 131     * and is not merely the original object
 132     * with the reference count incremented.
 133     * Changes to one will not be reflected in the other.
 134     */
 135     static OSString * withString(const OSString * aString);
 136
 137
 138    /*!
 139     * @function withCString
 140     *
 141     * @abstract
 142     * Creates and initializes an OSString from a C string.
 143     *
 144     * @param cString   The C string to copy into the new OSString.
 145     *
 146     * @result
 147     * An instance of OSString representing
 148     * the same characters as <code>aString</code>,
 149     * and with a reference count of 1;
 150     * <code>NULL</code> on failure.
 151     */
 152     static OSString * withCString(const char * cString);
 153
 154
 155    /*!
 156     * @function withCStringNoCopy
 157     *
 158     * @abstract
 159     * Creates and initializes an immutable OSString
 160     * that shares the provided C string buffer.
 161     *
 162     * @param cString   The C string to reference.
 163     *
 164     * @result
 165     * An instance of OSString containing <code>cString</code>,
 166     * and with a reference count of 1;
 167     * <code>NULL</code> on failure.
 168     *
 169     * @discussion
 170     * An OSString object created with this function
 171     * does not claim ownership of the C string,
 172     * but shares it with the caller.
 173     * When the caller determines that the OSString object has actually been freed,
 174     * it can safely dispose of the data buffer.
 175     * Conversely, if it frees the shared data buffer,
 176     * it must not attempt to use the OSString object and should release it.
 177     *
 178     * An OSString object created with this function does not
 179     * allow changing the string via <code>@link setChar setChar@/link</code>.
 180     */
 181     static OSString * withCStringNoCopy(const char * cString);
 182
 183     static OSString * withStringOfLength(const char *cString, size_t length);
 184
 185    /*!
 186     * @function initWithString
 187     *
 188     * @abstract
 189     * Initializes an OSString from another OSString.
 190     *
 191     * @param aString   The OSString object whose contents to copy.
 192     *
 193     * @result
 194     * <code>true</code> on success, <code>false</code> on failure.
 195     *
 196     * @discussion
 197     * Not for general use. Use the static instance creation method
 198     * <code>@link withString withString@/link</code> instead.
 199     */
 200     virtual bool initWithString(const OSString * aString);
 201
 202
 203    /*!
 204     * @function initWithCString
 205     *
 206     * @abstract
 207     * Initializes an OSString from a C string.
 208     *
 209     * @param cString   The C string to copy into the new OSString.
 210     *
 211     * @result
 212     * <code>true</code> on success, <code>false</code> on failure.
 213     *
 214     * @discussion
 215     * Not for general use. Use the static instance creation method
 216     * <code>@link withCString withCString@/link</code> instead.
 217     */
 218     virtual bool initWithCString(const char * cString);
 219
 220
 221    /*!
 222     * @function initWithCStringNoCopy
 223     *
 224     * @abstract
 225     * Initializes an immutable OSString
 226     * to share the provided C string buffer.
 227     *
 228     * @param cString   The C string to reference.
 229     *
 230     * @result
 231     * <code>true</code> on success, <code>false</code> on failure.
 232     *
 233     * @discussion
 234     * Not for general use. Use the static instance creation method
 235     * <code>@link withCStringNoCopy withCStringNoCopy@/link</code> instead.
 236     *
 237     * An OSString object initialized with this function
 238     * does not claim ownership of the C string,
 239     * but shares it with the caller.
 240     * When the caller determines that the OSString object has actually been freed,
 241     * it can safely dispose of the data buffer.
 242     * Conversely, if it frees the shared data buffer,
 243     * it must not attempt to use the OSString object and should release it.
 244     *
 245     * An OSString object created with this function does not
 246     * allow changing the string via <code>@link setChar setChar@/link</code>.
 247     */
 248     virtual bool initWithCStringNoCopy(const char * cString);
 249
 250     bool initWithStringOfLength(const char *cString, size_t inlength);
 251
 252    /*!
 253     * @function free
 254     *
 255     * @abstract
 256     * Deallocates or releases any resources
 257     * used by the OSString instance.
 258     *
 259     * @discussion
 260     * This function should not be called directly;
 261     * use
 262     * <code>@link
 263     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 264     * release@/link</code>
 265     * instead.
 266     */
 267     virtual void free();
 268
 269
 270    /*!
 271     * @function getLength
 272     *
 273     * @abstract
 274     * Returns the number of characters in the OSString object.
 275     *
 276     * @result
 277     * The number of characters in the OSString object.
 278     */
 279     virtual unsigned int getLength() const;
 280
 281
 282    /*!
 283     * @function getChar
 284     *
 285     * @abstract
 286     * Returns the character at a given index in the string object.
 287     *
 288     * @param index The index into the string.
 289     *
 290     * @result
 291     * The character at <code>index</code> within the string,
 292     * or <code>'\0'</code> if index is past the end of the string.
 293     */
 294     virtual char getChar(unsigned int index) const;
 295
 296
 297    /*!
 298     * @function setChar
 299     *
 300     * @abstract
 301     * Replaces a character at a given index in the string object.
 302     *
 303     * @param aChar The character value to set.
 304     * @param index The index into the string.
 305     *
 306     * @result
 307     * <code>true</code> if the character was replaced,
 308     * <code>false</code> if the was created "NoCopy"
 309     * or <code>index</code> is past the end of the string.
 310     */
 311     virtual bool setChar(char aChar, unsigned int index);
 312
 313
 314    /*!
 315     * @function getCStringNoCopy
 316     *
 317     * @abstract
 318     * Returns a pointer to the internal C string buffer.
 319     *
 320     * @result
 321     * A pointer to the internal C string buffer.
 322     */
 323     virtual const char * getCStringNoCopy() const;
 324
 325
 326    /*!
 327     * @function isEqualTo
 328     *
 329     * @abstract
 330     * Tests the equality of two OSString objects.
 331     *
 332     * @param aString  The OSString object being compared against the receiver.
 333     *
 334     * @result
 335     * <code>true</code> if the two OSString objects are equivalent,
 336     * <code>false</code> otherwise.
 337     *
 338     * @discussion
 339     * Two OSString objects are considered equal if they have same length
 340     * and if their byte buffers hold the same contents.
 341     */
 342     virtual bool isEqualTo(const OSString * aString) const;
 343
 344
 345    /*!
 346     * @function isEqualTo
 347     *
 348     * @abstract
 349     * Tests the equality of an OSString object with a C string.
 350     *
 351     * @param cString  The C string to compare against the receiver.
 352     *
 353     * @result
 354     * <code>true</code> if the OSString's characters
 355     * are equivalent to the C string's,
 356     * <code>false</code> otherwise.
 357     */
 358     virtual bool isEqualTo(const char * cString) const;
 359
 360
 361    /*!
 362     * @function isEqualTo
 363     *
 364     * @abstract
 365     * Tests the equality of an OSString object to an arbitrary object.
 366     *
 367     * @param anObject The object to be compared against the receiver.
 368     *
 369     * @result
 370     * Returns <code>true</code> if the two objects are equivalent,
 371     * <code>false</code> otherwise.
 372     *
 373     * @discussion
 374     * An OSString is considered equal to another object
 375     * if that object is derived from OSString
 376     * and contains the equivalent bytes of the same length.
 377     */
 378     virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
 379
 380
 381    /*!
 382     * @function isEqualTo
 383     *
 384     * @abstract
 385     * Tests the equality of an OSData object and the OSString instance.
 386     *
 387     * @param aDataObject An OSData object.
 388     *
 389     * @result
 390     * <code>true</code> if the two objects are equivalent, <code>false</code> otherwise.
 391     *
 392     * @discussion
 393     * This function compares the bytes of the OSData object
 394     * against those of the OSString,
 395     * accounting for the possibility that an OSData
 396     * might explicitly include a nul
 397     * character as part of its total length.
 398     * Thus, for example, an OSData object containing
 399     * either the bytes <'u', 's', 'b', '\0'>
 400     * or  <'u', 's', 'b'>
 401     * will compare as equal to the OSString containing "usb".
 402     */
 403     virtual bool isEqualTo(const OSData * aDataObject) const;
 404
 405
 406    /*!
 407     * @function serialize
 408     *
 409     * @abstract
 410     * Archives the receiver into the provided
 411     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 412     *
 413     * @param serializer The OSSerialize object.
 414     *
 415     * @result
 416     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 417     */
 418     virtual bool serialize(OSSerialize * serializer) const;
 419
 420     OSMetaClassDeclareReservedUnused(OSString,  0);
 421     OSMetaClassDeclareReservedUnused(OSString,  1);
 422     OSMetaClassDeclareReservedUnused(OSString,  2);
 423     OSMetaClassDeclareReservedUnused(OSString,  3);
 424     OSMetaClassDeclareReservedUnused(OSString,  4);
 425     OSMetaClassDeclareReservedUnused(OSString,  5);
 426     OSMetaClassDeclareReservedUnused(OSString,  6);
 427     OSMetaClassDeclareReservedUnused(OSString,  7);
 428     OSMetaClassDeclareReservedUnused(OSString,  8);
 429     OSMetaClassDeclareReservedUnused(OSString,  9);
 430     OSMetaClassDeclareReservedUnused(OSString, 10);
 431     OSMetaClassDeclareReservedUnused(OSString, 11);
 432     OSMetaClassDeclareReservedUnused(OSString, 12);
 433     OSMetaClassDeclareReservedUnused(OSString, 13);
 434     OSMetaClassDeclareReservedUnused(OSString, 14);
 435     OSMetaClassDeclareReservedUnused(OSString, 15);
 436 };
 437
 438 #endif /* !_OS_OSSTRING_H */