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