1 mike 1.38 //%/////////////////////////////////////////////////////////////////////////////
2 //
|
3 kumpf 1.50 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Company, IBM,
4 // The Open Group, Tivoli Systems
|
5 mike 1.38 //
6 // Permission is hereby granted, free of charge, to any person obtaining a copy
|
7 kumpf 1.50 // of this software and associated documentation files (the "Software"), to
8 // deal in the Software without restriction, including without limitation the
9 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
10 mike 1.38 // sell copies of the Software, and to permit persons to whom the Software is
11 // furnished to do so, subject to the following conditions:
12 //
|
13 kumpf 1.50 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
|
14 mike 1.38 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
15 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
|
16 kumpf 1.50 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
17 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
18 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
19 mike 1.38 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 //
22 //==============================================================================
23 //
24 // Author: Mike Brasher (mbrasher@bmc.com)
25 //
|
26 karl 1.43 // Modified By: Karl Schopmeyer(k.schopmeyer@opengroup.org)
|
27 kumpf 1.48 // Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)
|
28 mike 1.38 //
29 //%/////////////////////////////////////////////////////////////////////////////
30
31 #ifndef Pegasus_String_h
32 #define Pegasus_String_h
33
|
34 kumpf 1.71 #ifdef PEGASUS_OS_HPUX
|
35 kumpf 1.72 # ifdef HPUX_IA64_NATIVE_COMPILER
36 # include <iostream>
37 # else
38 # include <iostream.h>
39 # endif
|
40 kumpf 1.71 #else
41 # include <iostream>
42 #endif
|
43 mike 1.38 #include <Pegasus/Common/Config.h>
44 #include <Pegasus/Common/Char16.h>
|
45 kumpf 1.54 #include <Pegasus/Common/Linkage.h>
|
46 mike 1.38
47 PEGASUS_NAMESPACE_BEGIN
48
|
49 kumpf 1.59 class String;
|
50 kumpf 1.51 class StringRep;
51
|
52 kumpf 1.59 /** The CString class provides access to an 8-bit String representation.
53 */
|
54 kumpf 1.60 class PEGASUS_COMMON_LINKAGE CString
|
55 kumpf 1.59 {
56 public:
57
58 CString();
59
60 CString(const CString& cstr);
61
62 ~CString();
63
|
64 kumpf 1.62 CString& operator=(const CString& cstr);
65
|
66 kumpf 1.59 operator const char*() const;
67
68 private:
69
70 CString(char* cstr);
71
72 friend class String;
73
|
74 kumpf 1.64 void* _rep;
|
75 kumpf 1.59 };
76
|
77 mike 1.38 /**
78 The Pegasus String C++ Class implements the CIM string type.
79 This class is based on the general handle/representation pattern
80 defined for all the Pegasus objects. However, it differes from
81 most in that it implements "copy on assign" all of the others implement
82 "no copy on assign" semantics. The string class uses the Array class and
83 implements an array of characters.
84 */
85 class PEGASUS_COMMON_LINKAGE String
86 {
87 public:
88
|
89 kumpf 1.48 /** EMPTY - Represent an empty string.
90 This member is used to represent empty strings. Using this member
91 avoids an expensive construction of an empty string (e.g., String()).
92 */
93 static const String EMPTY;
94
|
95 mike 1.38 /** Default constructor without parameters. This constructor creates a
96 null string
97 <pre>
98 String test;
99 </pre>
100 */
101 String();
102
103 /// Copy constructor.
|
104 kumpf 1.48 String(const String& str);
|
105 mike 1.38
|
106 kumpf 1.48 /// Initialize with first n characters from str.
107 String(const String& str, Uint32 n);
|
108 mike 1.38
|
109 kumpf 1.48 /// Initialize with str.
110 String(const Char16* str);
|
111 mike 1.38
|
112 kumpf 1.48 /// Initialize with first n characters of str.
113 String(const Char16* str, Uint32 n);
|
114 mike 1.38
115 /// Initialize from a plain old C-String:
|
116 kumpf 1.48 String(const char* str);
|
117 mike 1.38
118 /// Initialize from the first n characters of a plain old C-String:
|
119 kumpf 1.48 String(const char* str, Uint32 n);
|
120 mike 1.38
121 /// String destructor. Used by the representation of the String object
122 ~String();
123
|
124 kumpf 1.48 /** Assign this string with str.
|
125 mike 1.38 <pre>
126 String t1 = "abc";
127 String t2 = t1;
128 </pre>
129 */
|
130 kumpf 1.48 String& operator=(const String& str);
|
131 mike 1.38
|
132 kumpf 1.48 /** Assign this string with String str
133 @param str String to assign
|
134 mike 1.38 @return Returns the String
135 */
|
136 kumpf 1.48 String& assign(const String& str);
|
137 mike 1.38
|
138 kumpf 1.48 /// Assign this string with str.
139 String& assign(const Char16* str);
|
140 mike 1.38
|
141 kumpf 1.48 /// Assign this string with first n characters of str.
142 String& assign(const Char16* str, Uint32 n);
|
143 mike 1.38
|
144 kumpf 1.48 /// Assign this string with the plain old C-String str.
145 String& assign(const char* str);
|
146 mike 1.38
|
147 kumpf 1.48 /// Assign this string with first n characters of the plain old C-String str.
148 String& assign(const char* str, Uint32 n);
|
149 mike 1.38
150 /** clear - Clear this string. After calling clear(), size() will return 0.
151 <pre>
152 String test = "abc";
153 test.clear(); // String test is now NULL (length == 0)
154 </pre>
155 */
156 void clear();
157
158
|
159 kumpf 1.53 /** reserveCapacity - Reserves memory for capacity characters. Notice
160 that this does not change the size of the string (size() returns
161 what it did before). If the capacity of the string is already
162 greater or equal to the capacity argument, this method has no
163 effect. The capacity of a String object has no bearing on its
164 external behavior. The capacity of a String is set only for
165 performance reasons.
|
166 mike 1.38 @param capacity defines the capacity in characters to reserve.
167 */
|
168 kumpf 1.51 void reserveCapacity(Uint32 capacity);
|
169 mike 1.38
170 /** Returns the length of the String object.
171 @return Length of the string in characters.
172 <pre>
173 String s = "abcd";
174 assert(s.size() == 4);
175 </pre>
176 */
|
177 kumpf 1.48 Uint32 size() const;
|
178 mike 1.38
|
179 kumpf 1.61 /** getChar16Data Returns a pointer to the first character in the
180 null-terminated Char16 buffer of the String object.
|
181 mike 1.38 @return Pointer to the first character of the String object
182 <pre>
183 String t1 = "abc";
|
184 kumpf 1.61 const Char16* q = t1.getChar16Data();
|
185 mike 1.38 </pre>
186 */
|
187 kumpf 1.61 const Char16* getChar16Data() const;
|
188 mike 1.38
|
189 kumpf 1.59 /** getCString - Create an 8-bit representation of this String object.
190
|
191 kumpf 1.55 @param truncatedCharacters Output parameter specifying whether any
192 characters were truncated in the conversion.
|
193 mike 1.41
|
194 kumpf 1.59 @return CString object that provides access to the 8-bit String
195 representation
196
|
197 mike 1.38 <pre>
198 String test = "abc";
|
199 kumpf 1.59 printf("test = %s\n", (const char*)test.getCString());
|
200 mike 1.38 </pre>
201 */
|
202 kumpf 1.59 CString getCString() const;
|
203 mike 1.38
|
204 kumpf 1.58 /** Returns the specified character of the String object.
205 @param index Index of the character to access
|
206 kumpf 1.57 @exception IndexOutOfBoundsException if the index
|
207 kumpf 1.58 is outside the bounds of the String.
|
208 mike 1.38 <pre>
209 String t1 = "abc;
210 Char16 c = t1[1]; // character b
211 </pre>
212 */
|
213 kumpf 1.58 Char16& operator[](Uint32 index);
|
214 mike 1.38
|
215 kumpf 1.58 /** Returns the specified character of the String object (const version).
216 @param index Index of the character to access
217 @exception IndexOutOfBoundsException if the index
218 is outside the bounds of the String.
|
219 mike 1.38 */
|
220 kumpf 1.58 const Char16 operator[](Uint32 index) const;
|
221 mike 1.38
|
222 kumpf 1.57 /** Append the given character to this String.
223 @param c Character to append.
224 @return This String
225 <pre>
226 String t1 = "abc";
|
227 kumpf 1.73 t1.append (Char16('d'));
|
228 kumpf 1.57 assert(t1 == "abcd");
|
229 mike 1.38 </pre>
230 */
231 String& append(const Char16& c);
232
|
233 kumpf 1.57 /// Append n characters from str to this String.
|
234 mike 1.38 String& append(const Char16* str, Uint32 n);
235
|
236 kumpf 1.57 /** Append the given String to this String.
237 @param str String to append.
|
238 mike 1.38 @return This String
239 <pre>
240 String test = "abc";
|
241 kumpf 1.57 test.append("def");
|
242 mike 1.38 assert(test == "abcdef");
243 </pre>
244 */
|
245 kumpf 1.57 String& append(const String& str);
|
246 mike 1.38
247 /** Remove size characters from the string starting at the given
|
248 kumpf 1.58 index. If size is PEG_NOT_FOUND, then all characters after index are
|
249 mike 1.38 removed.
|
250 kumpf 1.58 @param index Position in string to start remove
|
251 mike 1.38 @param size Number of characters to remove. Default is PEG_NOT_FOUND
|
252 kumpf 1.58 which causes all characters after index to be removed
|
253 mike 1.38 <pre>
254 String s;
255 s = "abc";
256 s.remove(0, 1);
257 assert(String::equal(s, "bc"));
258 assert(s.size() == 2);
259 s.remove(0);
260 assert(String::equal(s, ""));
261 assert(s.size() == 0);
262 </pre>
|
263 kumpf 1.55 @exception IndexOutOfBoundsException if size is greater than
|
264 kumpf 1.58 length of String plus starting index for remove.
|
265 mike 1.38 */
|
266 kumpf 1.58 void remove(Uint32 index, Uint32 size = PEG_NOT_FOUND);
|
267 mike 1.38
268 /** Return a new String which is initialzed with <TT>length</TT>
|
269 kumpf 1.58 characters from this string starting at <TT>index</TT>.
270 @param <TT>index</TT> is the index in string to start getting the
|
271 mike 1.38 substring.
272 @param <TT>length</TT> is the number of characters to get. If length
|
273 kumpf 1.58 is PEG_NOT_FOUND, then all characters after index are added to the new
|
274 mike 1.38 string.
275 @return String with the defined substring.
276 <pre>
277 s = "abcdefg";
278 s.remove(3);
279 assert(String::equal(s, "abc"));
280 </pre>
281 */
|
282 kumpf 1.58 String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const;
|
283 mike 1.38
|
284 kumpf 1.58 /** Find the index of the first occurence of the character c.
|
285 mike 1.38 If the character is not found, PEG_NOT_FOUND is returned.
286 @param c Char to be found in the String
287 @return Position of the character in the string or PEG_NOT_FOUND if not
288 found.
289 */
290 Uint32 find(Char16 c) const;
291
|
292 kumpf 1.58 /** Same as above but starts searching from the given index. */
293 Uint32 find(Uint32 index, Char16 c) const;
|
294 mike 1.38
|
295 kumpf 1.58 /** Find the index of the first occurence of the string object.
|
296 mike 1.38 This function finds one string inside another
297 If the matching substring is not found, PEG_NOT_FOUND is returned.
298 @param s String object to be found in the String
299 @return Position of the substring in the String or PEG_NOT_FOUND if not
300 found.
301 */
302 Uint32 find(const String& s) const;
303
304 /** reverseFind - Same as find() but start looking in reverse (last
305 character first).
306 @param c Char16 character to find in String.
307 @Seealso find
308 @return Position of the character in the string or PEG_NOT_FOUND if not
309 found.
310
311 NOTE: This function is defined only for char* input, not for
312 String.
313 */
314 Uint32 reverseFind(Char16 c) const;
315
316 /** Converts all characters in this string to lower case.
317 mike 1.38 */
318 void toLower();
|
319 kumpf 1.48
|
320 mike 1.38 /** Compare the first n characters of the two strings..
321 @param s1 First null-terminated string for the comparison.
322 @param s2 Second null-terminated string for the comparison.
323 @param n Number of characters to compare.
324 @return Return -1 if s1 is lexographically less than s2. If they are
325 equavalent return 0. Otherwise return 1.
326 */
|
327 kumpf 1.51 static int compare(const String& s1, const String& s2, Uint32 n);
|
328 mike 1.38
329 /** Compare two null-terminated strings.
330 @param s1 First null-terminated string for the comparison.
331 @param s2 Second null-terminated string for the comparison.
332 @return If s1 is less than s2, return -1; if equal return 0;
333 otherwise, return 1.
334
335 NOTE: Use the comparison operators <,<= > >= to compare
336 String objects.
337 */
|
338 kumpf 1.51 static int compare(const String& s1, const String& s2);
|
339 mike 1.38
|
340 kumpf 1.48 /** Just like one above except ignores case differences.
341 */
|
342 kumpf 1.49 static int compareNoCase(const String& s1, const String& s2);
|
343 kumpf 1.48
|
344 mike 1.38 /** Compare two String objects for equality.
345 @param s1 First <TT>String</TT> for comparison.
346 @param s2 Second <TT>String</TT> for comparison.
347
348 @return Boolean true if the two strings are equal.
349 <pre>
350 String s1 = "Hello World";
351 String s2 = s1;
352 String s3(s2);
353 assert(String::equal(s1, s3));
354 </pre>
355 */
|
356 kumpf 1.48 static Boolean equal(const String& str1, const String& str2);
|
357 mike 1.38
|
358 karl 1.47 /** equalNoCase - Compares two strings and returuns true if they
359 are equal indpedent of case of the characters.
|
360 kumpf 1.48 @param str1 First String parameter
361 @param str2 Second String parameter
|
362 karl 1.47 @return true if strings are equal independent of case.
363 */
|
364 kumpf 1.48 static Boolean equalNoCase(const String& str1, const String& str2);
|
365 mike 1.38
366 private:
367
|
368 kumpf 1.51 StringRep* _rep;
|
369 mike 1.38 };
|
370 mike 1.40
|
371 mike 1.38 /** String operator ==. Test for equality between two strings of any of the
372 types String or char*.
373 @return Boolean - True if the strings are equal
374 */
|
375 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(
376 const String& str1,
377 const String& str2);
|
378 mike 1.38
379 /** String operator ==. Test for equality between two strings
380
381 */
|
382 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2);
|
383 mike 1.38
384 /** String operator ==. Test for equality between two strings
385
386 */
|
387 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2);
|
388 mike 1.38
389 /** String operator ==. Test for equality between two strings
390
391 */
|
392 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator!=(
393 const String& str1,
394 const String& str2);
|
395 mike 1.38
396 PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<(
397 PEGASUS_STD(ostream)& os,
|
398 kumpf 1.48 const String& str);
|
399 mike 1.38
400 /** overload operator + - Concatenates String objects.
401
402 <pre>
403 String t1 = "abc";
404 String t2;
405 t2 = t1 + "def"
406 assert(t2 == "abcdef");
407 </pre>
408 */
|
409 kumpf 1.48 PEGASUS_COMMON_LINKAGE String operator+(const String& str1, const String& str2);
|
410 mike 1.38
411 /** overload operator < - Compares String obects.
412 <pre>
413 String t1 = "def";
414 String t2 = "a";
415 assert (t2 < t1);
416 </pre>
417 */
|
418 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<(
419 const String& str1,
420 const String& str2);
|
421 mike 1.38
422 /** overload operator <= compares String objects.
423
424 */
|
425 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<=(
426 const String& str1,
427 const String& str2);
|
428 mike 1.38
429 /** Overload operator > compares String objects
430 */
|
431 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>(
432 const String& str1,
433 const String& str2);
|
434 mike 1.38
435 /** overload operator >= - Compares String objects
436 */
|
437 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>=(
438 const String& str1,
439 const String& str2);
|
440 mike 1.38
|
441 kumpf 1.66 #ifndef PEGASUS_REMOVE_DEPRECATED
|
442 mike 1.38 /** Compare two strings but ignore any case differences.
443 */
444 PEGASUS_COMMON_LINKAGE int CompareNoCase(const char* s1, const char* s2);
|
445 kumpf 1.65 #endif
|
446 mike 1.41
|
447 mike 1.38 PEGASUS_NAMESPACE_END
448
449 #endif /* Pegasus_String_h */
|