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 36class 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 */ 103class OSString : public OSObject 104{ 105 OSDeclareDefaultStructors(OSString) 106 107protected: 108 unsigned int flags; 109 unsigned int length; 110 char * string; 111 112public: 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 */ 439