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
 184    /*!
 185     * @function initWithString
 186     *
 187     * @abstract
 188     * Initializes an OSString from another OSString.
 189     *
 190     * @param aString   The OSString object whose contents to copy.
 191     *
 192     * @result
 193     * <code>true</code> on success, <code>false</code> on failure.
 194     *
 195     * @discussion
 196     * Not for general use. Use the static instance creation method
 197     * <code>@link withString withString@/link</code> instead.
 198     */
 199     virtual bool initWithString(const OSString * aString);
 200
 201
 202    /*!
 203     * @function initWithCString
 204     *
 205     * @abstract
 206     * Initializes an OSString from a C string.
 207     *
 208     * @param cString   The C string to copy into the new OSString.
 209     *
 210     * @result
 211     * <code>true</code> on success, <code>false</code> on failure.
 212     *
 213     * @discussion
 214     * Not for general use. Use the static instance creation method
 215     * <code>@link withCString withCString@/link</code> instead.
 216     */
 217     virtual bool initWithCString(const char * cString);
 218
 219
 220    /*!
 221     * @function initWithCStringNoCopy
 222     *
 223     * @abstract
 224     * Initializes an immutable OSString
 225     * to share the provided C string buffer.
 226     *
 227     * @param cString   The C string to reference.
 228     *
 229     * @result
 230     * <code>true</code> on success, <code>false</code> on failure.
 231     *
 232     * @discussion
 233     * Not for general use. Use the static instance creation method
 234     * <code>@link withCStringNoCopy withCStringNoCopy@/link</code> instead.
 235     *
 236     * An OSString object initialized with this function
 237     * does not claim ownership of the C string,
 238     * but shares it with the caller.
 239     * When the caller determines that the OSString object has actually been freed,
 240     * it can safely dispose of the data buffer.
 241     * Conversely, if it frees the shared data buffer,
 242     * it must not attempt to use the OSString object and should release it.
 243     *
 244     * An OSString object created with this function does not
 245     * allow changing the string via <code>@link setChar setChar@/link</code>.
 246     */
 247     virtual bool initWithCStringNoCopy(const char * cString);
 248
 249
 250    /*!
 251     * @function free
 252     *
 253     * @abstract
 254     * Deallocates or releases any resources
 255     * used by the OSString instance.
 256     *
 257     * @discussion
 258     * This function should not be called directly;
 259     * use
 260     * <code>@link
 261     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 262     * release@/link</code>
 263     * instead.
 264     */
 265     virtual void free();
 266
 267
 268    /*!
 269     * @function getLength
 270     *
 271     * @abstract
 272     * Returns the number of characters in the OSString object.
 273     *
 274     * @result
 275     * The number of characters in the OSString object.
 276     */
 277     virtual unsigned int getLength() const;
 278
 279
 280    /*!
 281     * @function getChar
 282     *
 283     * @abstract
 284     * Returns the character at a given index in the string object.
 285     *
 286     * @param index The index into the string.
 287     *
 288     * @result
 289     * The character at <code>index</code> within the string,
 290     * or <code>'\0'</code> if index is past the end of the string.
 291     */
 292     virtual char getChar(unsigned int index) const;
 293
 294
 295    /*!
 296     * @function setChar
 297     *
 298     * @abstract
 299     * Replaces a character at a given index in the string object.
 300     *
 301     * @param aChar The character value to set.
 302     * @param index The index into the string.
 303     *
 304     * @result
 305     * <code>true</code> if the character was replaced,
 306     * <code>false</code> if the was created "NoCopy"
 307     * or <code>index</code> is past the end of the string.
 308     */
 309     virtual bool setChar(char aChar, unsigned int index);
 310
 311
 312    /*!
 313     * @function getCStringNoCopy
 314     *
 315     * @abstract
 316     * Returns a pointer to the internal C string buffer.
 317     *
 318     * @result
 319     * A pointer to the internal C string buffer.
 320     */
 321     virtual const char * getCStringNoCopy() const;
 322
 323
 324    /*!
 325     * @function isEqualTo
 326     *
 327     * @abstract
 328     * Tests the equality of two OSString objects.
 329     *
 330     * @param aString  The OSString object being compared against the receiver.
 331     *
 332     * @result
 333     * <code>true</code> if the two OSString objects are equivalent,
 334     * <code>false</code> otherwise.
 335     *
 336     * @discussion
 337     * Two OSString objects are considered equal if they have same length
 338     * and if their byte buffers hold the same contents.
 339     */
 340     virtual bool isEqualTo(const OSString * aString) const;
 341
 342
 343    /*!
 344     * @function isEqualTo
 345     *
 346     * @abstract
 347     * Tests the equality of an OSString object with a C string.
 348     *
 349     * @param cString  The C string to compare against the receiver.
 350     *
 351     * @result
 352     * <code>true</code> if the OSString's characters
 353     * are equivalent to the C string's,
 354     * <code>false</code> otherwise.
 355     */
 356     virtual bool isEqualTo(const char * cString) const;
 357
 358
 359    /*!
 360     * @function isEqualTo
 361     *
 362     * @abstract
 363     * Tests the equality of an OSString object to an arbitrary object.
 364     *
 365     * @param anObject The object to be compared against the receiver.
 366     *
 367     * @result
 368     * Returns <code>true</code> if the two objects are equivalent,
 369     * <code>false</code> otherwise.
 370     *
 371     * @discussion
 372     * An OSString is considered equal to another object
 373     * if that object is derived from OSString
 374     * and contains the equivalent bytes of the same length.
 375     */
 376     virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
 377
 378
 379    /*!
 380     * @function isEqualTo
 381     *
 382     * @abstract
 383     * Tests the equality of an OSData object and the OSString instance.
 384     *
 385     * @param aDataObject An OSData object.
 386     *
 387     * @result
 388     * <code>true</code> if the two objects are equivalent, <code>false</code> otherwise.
 389     *
 390     * @discussion
 391     * This function compares the bytes of the OSData object
 392     * against those of the OSString,
 393     * accounting for the possibility that an OSData
 394     * might explicitly include a nul
 395     * character as part of its total length.
 396     * Thus, for example, an OSData object containing
 397     * either the bytes <'u', 's', 'b', '\0'>
 398     * or  <'u', 's', 'b'>
 399     * will compare as equal to the OSString containing "usb".
 400     */
 401     virtual bool isEqualTo(const OSData * aDataObject) const;
 402
 403
 404    /*!
 405     * @function serialize
 406     *
 407     * @abstract
 408     * Archives the receiver into the provided
 409     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 410     *
 411     * @param serializer The OSSerialize object.
 412     *
 413     * @result
 414     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 415     */
 416     virtual bool serialize(OSSerialize * serializer) const;
 417
 418     OSMetaClassDeclareReservedUnused(OSString,  0);
 419     OSMetaClassDeclareReservedUnused(OSString,  1);
 420     OSMetaClassDeclareReservedUnused(OSString,  2);
 421     OSMetaClassDeclareReservedUnused(OSString,  3);
 422     OSMetaClassDeclareReservedUnused(OSString,  4);
 423     OSMetaClassDeclareReservedUnused(OSString,  5);
 424     OSMetaClassDeclareReservedUnused(OSString,  6);
 425     OSMetaClassDeclareReservedUnused(OSString,  7);
 426     OSMetaClassDeclareReservedUnused(OSString,  8);
 427     OSMetaClassDeclareReservedUnused(OSString,  9);
 428     OSMetaClassDeclareReservedUnused(OSString, 10);
 429     OSMetaClassDeclareReservedUnused(OSString, 11);
 430     OSMetaClassDeclareReservedUnused(OSString, 12);
 431     OSMetaClassDeclareReservedUnused(OSString, 13);
 432     OSMetaClassDeclareReservedUnused(OSString, 14);
 433     OSMetaClassDeclareReservedUnused(OSString, 15);
 434 };
 435
 436 #endif /* !_OS_OSSTRING_H */