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