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