pegasus/src/Pegasus/Common/String.h - annotate

Return to String.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Common

1 karl 1.78 //%2003////////////////////////////////////////////////////////////////////////
2 mike 1.38 //
3 karl 1.78 // Copyright (c) 2000, 2001, 2002 BMC Software, Hewlett-Packard Development 4 // Company, L. P., IBM Corp., The Open Group, Tivoli Systems. 5 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L. P.; 6 // IBM Corp.; EMC Corporation, The Open Group.
7 mike 1.38 // 8 // Permission is hereby granted, free of charge, to any person obtaining a copy
9 kumpf 1.50 // of this software and associated documentation files (the "Software"), to 10 // deal in the Software without restriction, including without limitation the 11 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
12 mike 1.38 // sell copies of the Software, and to permit persons to whom the Software is 13 // furnished to do so, subject to the following conditions: 14 //
15 kumpf 1.50 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
16 mike 1.38 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED 17 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
18 kumpf 1.50 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 19 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 20 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21 mike 1.38 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 22 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 23 // 24 //============================================================================== 25 // 26 // Author: Mike Brasher (mbrasher@bmc.com) 27 //
28 karl 1.43 // Modified By: Karl Schopmeyer(k.schopmeyer@opengroup.org)
29 kumpf 1.48 // Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)
30 mike 1.38 // 31 //%///////////////////////////////////////////////////////////////////////////// 32 33 #ifndef Pegasus_String_h 34 #define Pegasus_String_h 35
36 kumpf 1.71 #ifdef PEGASUS_OS_HPUX
37 kumpf 1.72 # ifdef HPUX_IA64_NATIVE_COMPILER 38 # include <iostream> 39 # else 40 # include <iostream.h> 41 # endif
42 kumpf 1.71 #else 43 # include <iostream> 44 #endif
45 mike 1.38 #include <Pegasus/Common/Config.h> 46 #include <Pegasus/Common/Char16.h>
47 kumpf 1.54 #include <Pegasus/Common/Linkage.h>
48 mike 1.38
49 david 1.81 // Locale constants 50 // These constants need to be defined as follows: 51 // lower case language; underscore; Uppercase Country 52 const char ENGLISH_US[] = "en_US"; 53
54 david 1.76
55 mike 1.38 PEGASUS_NAMESPACE_BEGIN 56
57 kumpf 1.59 class String;
58 kumpf 1.51 class StringRep; 59
60 kumpf 1.59 /** The CString class provides access to an 8-bit String representation. 61 */
62 kumpf 1.60 class PEGASUS_COMMON_LINKAGE CString
63 kumpf 1.59 { 64 public: 65
66 karl 1.79 /** Constructs a CString object with null values (default constructor). 67 */
68 kumpf 1.59 CString(); 69
70 karl 1.79 /** REVIEWERS: Describe method here. 71 @param cstr Specifies the name of the CString instance. 72 */
73 kumpf 1.59 CString(const CString& cstr); 74
75 karl 1.79 /** CString destructor. 76 */
77 kumpf 1.59 ~CString(); 78
79 karl 1.79 /** Assigns the values of one CString instance to another. 80 @param cstr Specifies the name of the CString instance whose values 81 are assigned to CString. 82 */
83 kumpf 1.62 CString& operator=(const CString& cstr); 84
85 karl 1.79 /** REVIEWERS: Describe constructor here. 86 */
87 kumpf 1.59 operator const char() const; 88 89 private: 90 91 CString(char cstr); 92 93 friend class String; 94
95 kumpf 1.64 void* _rep;
96 kumpf 1.59 }; 97
98 mike 1.38 /** 99 The Pegasus String C++ Class implements the CIM string type.
100 karl 1.79 REVIEWERS: We need more definition here.
101 mike 1.38 */ 102 class PEGASUS_COMMON_LINKAGE String 103 { 104 public: 105
106 kumpf 1.74 /** This member is used to represent an empty string. Using this
107 karl 1.79 member avoids construction of an empty string (for example, String()).
108 kumpf 1.48 */ 109 static const String EMPTY; 110
111 mike 1.38 /** Default constructor without parameters. This constructor creates a
112 karl 1.79 null string. For example,
113 mike 1.38 <pre> 114 String test; 115 </pre> 116 */ 117 String(); 118
119 karl 1.79 /** Copy constructor. 120 @param str Specifies the name of the String instance. 121 */
122 kumpf 1.48 String(const String& str);
123 mike 1.38
124 karl 1.79 /** Initialize with first n characters from str. 125 @param str Specifies the name of the String instance. 126 @param n Specifies the Uint32 size to use for the length of the string object. 127 */
128 kumpf 1.48 String(const String& str, Uint32 n);
129 mike 1.38
130 karl 1.79 /** Initialize with str. 131 @param str Specifies the name of the String instance. 132 */
133 kumpf 1.48 String(const Char16* str);
134 mike 1.38
135 karl 1.79 /** Initialize with first n characters of str. 136 @param str Specifies the name of the String instance. 137 @param n Specifies the Uint32 size. 138 */
139 kumpf 1.48 String(const Char16* str, Uint32 n);
140 mike 1.38
141 karl 1.79 /** Initialize from a plain C-String: 142 @param str Specifies the name of the String instance.
143 david 1.81 API supports UTF8
144 karl 1.79 */
145 kumpf 1.48 String(const char* str);
146 chuck 1.77
147 karl 1.79 /** Initialize from the first n characters of a plain C-String: 148 @param str Specifies the name of the String instance. 149 @param u Specifies the Uint32 size.
150 david 1.81 API supports UTF8
151 karl 1.79 */
152 kumpf 1.48 String(const char* str, Uint32 n);
153 mike 1.38
154 karl 1.79 /** String destructor. 155 */
156 mike 1.38 ~String(); 157
158 karl 1.79 /** Assign this string with str. For example,
159 mike 1.38 <pre> 160 String t1 = "abc"; 161 String t2 = t1; 162 </pre>
163 karl 1.79 String t2 is assigned the value of t1. 164 @param str Specifies the name of the String to assign to another 165 String instance.
166 mike 1.38 */
167 kumpf 1.48 String& operator=(const String& str);
168 mike 1.38
169 kumpf 1.74 /** Assign this string with String str. 170 @param str String to assign. 171 @return Returns the String.
172 david 1.81 API supports UTF8
173 mike 1.38 */
174 kumpf 1.48 String& assign(const String& str);
175 mike 1.38
176 karl 1.79 /** Assign this string with str. 177 */
178 kumpf 1.48 String& assign(const Char16* str);
179 mike 1.38
180 karl 1.79 /** Assign this string with first n characters of str. 181 @param n REVIEWERS: Insert text here. 182 @param str REVIEWERS: Insert text here. 183 */
184 kumpf 1.48 String& assign(const Char16* str, Uint32 n);
185 mike 1.38
186 karl 1.79 /** Assign this string with the plain C-String str. 187 @param str REVIEWERS: Insert text here.
188 david 1.81 API supports UTF8
189 karl 1.79 */
190 kumpf 1.48 String& assign(const char* str);
191 mike 1.38
192 karl 1.79 /** Assign this string with first n characters of the plain C-String str. 193 @param str REVIEWERS: Insert text here. 194 @param n REVIEWERS: Insert text here.
195 david 1.81 API supports UTF8
196 karl 1.79 */
197 kumpf 1.48 String& assign(const char* str, Uint32 n);
198 mike 1.38
199 kumpf 1.74 /** Clear this string. After calling clear(), size() will return 0.
200 mike 1.38 <pre> 201 String test = "abc";
202 kumpf 1.74 test.clear();
203 mike 1.38 </pre> 204 */ 205 void clear(); 206 207
208 kumpf 1.74 /** Reserves memory for capacity characters. Notice
209 kumpf 1.53 that this does not change the size of the string (size() returns 210 what it did before). If the capacity of the string is already 211 greater or equal to the capacity argument, this method has no 212 effect. The capacity of a String object has no bearing on its 213 external behavior. The capacity of a String is set only for 214 performance reasons.
215 karl 1.79 @param capacity Defines the capacity in characters to reserve.
216 mike 1.38 */
217 kumpf 1.51 void reserveCapacity(Uint32 capacity);
218 mike 1.38 219 /** Returns the length of the String object.
220 karl 1.79 @return Length of the String in characters. For example,
221 mike 1.38 <pre> 222 String s = "abcd"; 223 assert(s.size() == 4); 224 </pre>
225 karl 1.79 returns a value of 4 for the length.
226 mike 1.38 */
227 kumpf 1.48 Uint32 size() const;
228 mike 1.38
229 kumpf 1.74 /** Returns a pointer to the first character in the
230 kumpf 1.61 null-terminated Char16 buffer of the String object.
231 karl 1.79 @return Pointer to the first character of the String object. For example,
232 mike 1.38 <pre>
233 kumpf 1.74 String test = "abc"; 234 const Char16* q = test.getChar16Data();
235 mike 1.38 </pre>
236 karl 1.79 points to the first character in the String instance named test.
237 mike 1.38 */
238 kumpf 1.61 const Char16* getChar16Data() const;
239 mike 1.38
240 karl 1.79 /** Create an 8-bit representation of this String object. For example,
241 kumpf 1.59
242 david 1.81 @return CString object that provides access to the UTF8 String
243 kumpf 1.74 representation.
244 kumpf 1.59
245 mike 1.38 <pre> 246 String test = "abc";
247 kumpf 1.59 printf("test = %s\n", (const char*)test.getCString());
248 chuck 1.75 249 NOTE: Do not do the following: 250 const char * p = (const char *)test.getCString(); 251 The pointer p will be invalid. This is because 252 the CString object is destructed, which deletes 253 the heap space for p.
254 mike 1.38 </pre> 255 */
256 kumpf 1.59 CString getCString() const;
257 mike 1.38
258 kumpf 1.58 /** Returns the specified character of the String object.
259 kumpf 1.74 @param index Index of the character to access.
260 karl 1.79 @return Specified character of the String object. 261 @exception IndexOutOfBoundsException If the index
262 kumpf 1.58 is outside the bounds of the String.
263 mike 1.38 <pre>
264 kumpf 1.74 String test = "abc; 265 Char16 c = test[1];
266 mike 1.38 </pre> 267 */
268 kumpf 1.58 Char16& operator[](Uint32 index);
269 mike 1.38
270 kumpf 1.58 /** Returns the specified character of the String object (const version).
271 kumpf 1.74 @param index Index of the character to access.
272 karl 1.79 @return Specified character of the String object. 273 @exception IndexOutOfBoundsException If the index
274 kumpf 1.58 is outside the bounds of the String.
275 mike 1.38 */
276 kumpf 1.58 const Char16 operator[](Uint32 index) const;
277 mike 1.38
278 kumpf 1.57 /** Append the given character to this String. 279 @param c Character to append.
280 kumpf 1.74 @return This String.
281 kumpf 1.57 <pre>
282 kumpf 1.74 String test = "abc"; 283 test.append(Char16('d')); 284 assert(test == "abcd");
285 mike 1.38 </pre> 286 */ 287 String& append(const Char16& c); 288
289 karl 1.79 /** Append n characters from str to this String. 290 @param str REVIEWERS: Insert text here. 291 @param n REVIEWERS: Insert text here. 292 */
293 mike 1.38 String& append(const Char16* str, Uint32 n); 294
295 kumpf 1.57 /** Append the given String to this String. 296 @param str String to append.
297 kumpf 1.74 @return This String.
298 mike 1.38 <pre> 299 String test = "abc";
300 kumpf 1.57 test.append("def");
301 mike 1.38 assert(test == "abcdef"); 302 </pre> 303 */
304 kumpf 1.57 String& append(const String& str);
305 mike 1.38 306 /** Remove size characters from the string starting at the given
307 kumpf 1.58 index. If size is PEG_NOT_FOUND, then all characters after index are
308 mike 1.38 removed.
309 kumpf 1.74 @param index Position in string to start remove.
310 mike 1.38 @param size Number of characters to remove. Default is PEG_NOT_FOUND
311 kumpf 1.74 which causes all characters after index to be removed.
312 mike 1.38 <pre> 313 String s; 314 s = "abc"; 315 s.remove(0, 1); 316 assert(String::equal(s, "bc")); 317 assert(s.size() == 2); 318 s.remove(0); 319 assert(String::equal(s, "")); 320 assert(s.size() == 0); 321 </pre>
322 karl 1.79 @exception IndexOutOfBoundsException If size is greater than
323 kumpf 1.58 length of String plus starting index for remove.
324 mike 1.38 */
325 kumpf 1.58 void remove(Uint32 index, Uint32 size = PEG_NOT_FOUND);
326 mike 1.38 327 /** Return a new String which is initialzed with <TT>length</TT>
328 kumpf 1.58 characters from this string starting at <TT>index</TT>.
329 karl 1.79 @param index Specifies the index in string to start getting the
330 mike 1.38 substring.
331 karl 1.79 @param length Specifies the number of characters to get. If length
332 kumpf 1.58 is PEG_NOT_FOUND, then all characters after index are added to the new
333 mike 1.38 string.
334 karl 1.79 @return String Specifies the Sting with the defined substring.
335 mike 1.38 */
336 kumpf 1.58 String subString(Uint32 index, Uint32 length = PEG_NOT_FOUND) const;
337 mike 1.38
338 karl 1.79 /** Find the index of the first occurrence of the character c.
339 mike 1.38 If the character is not found, PEG_NOT_FOUND is returned.
340 kumpf 1.74 @param c Char to be found in the String.
341 mike 1.38 @return Position of the character in the string or PEG_NOT_FOUND if not 342 found. 343 */ 344 Uint32 find(Char16 c) const; 345
346 karl 1.79 /** Find the index of the first occurence of the character c. 347 If the character is not found, PEG_NOT_FOUND is returned. 348 This begins searching from the given index. 349 @param c Char to be found in the String. 350 @return Position of the character in the string or PEG_NOT_FOUND if not 351 found.
352 kumpf 1.74 */
353 kumpf 1.58 Uint32 find(Uint32 index, Char16 c) const;
354 mike 1.38
355 kumpf 1.58 /** Find the index of the first occurence of the string object.
356 kumpf 1.74 This function finds one string inside another.
357 mike 1.38 If the matching substring is not found, PEG_NOT_FOUND is returned.
358 kumpf 1.74 @param s String object to be found in the String.
359 mike 1.38 @return Position of the substring in the String or PEG_NOT_FOUND if not 360 found. 361 */ 362 Uint32 find(const String& s) const; 363
364 kumpf 1.74 /** Same as find() but start looking in reverse (last character first).
365 mike 1.38 @param c Char16 character to find in String. 366 @return Position of the character in the string or PEG_NOT_FOUND if not 367 found. 368 */ 369 Uint32 reverseFind(Char16 c) const; 370
371 david 1.81 /** Converts all characters in this string to lowercase characters, 372 ICU : Operation will use default locale or the locale provided 373 NON ICU: Operattion will use c runtime function 374 / 375 void toLower(); 376 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES 377 /* @param strLocale const char * is the locale to use for the operation. 378 If NULL will use the default locale for the process. 379 Refer to Locale constants for formating. 380 / 381 void toLower(const char strLocale); 382 #endif 383
384 karl 1.79 /** Converts all characters in this string to lowercase characters.
385 david 1.81 @param strLocale const char * is the locale to use for the operation. 386 If NULL will use the default locale for the process. 387 ICU : Operation will use default locale or the locale provided 388 NON ICU: Operattion will use c runtime function 389 Refer to Locale constants for formating.
390 mike 1.38 */
391 david 1.81 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES 392 void toUpper(const char * strLocale = NULL); 393 #endif
394 kumpf 1.48
395 karl 1.79 /** Compare the first n characters of the two strings.
396 mike 1.38 @param s1 First null-terminated string for the comparison. 397 @param s2 Second null-terminated string for the comparison. 398 @param n Number of characters to compare.
399 karl 1.79 @return Return -1 If s1 is lexographically less than s2; if they are 400 equivalent return 0; otherwise return 1.
401 mike 1.38 */
402 kumpf 1.51 static int compare(const String& s1, const String& s2, Uint32 n);
403 mike 1.38 404 /** Compare two null-terminated strings. 405 @param s1 First null-terminated string for the comparison. 406 @param s2 Second null-terminated string for the comparison.
407 kumpf 1.74 @return Return -1 if s1 is less than s2; if equal return 0; 408 otherwise return 1.
409 mike 1.38 410 NOTE: Use the comparison operators <,<= > >= to compare 411 String objects. 412 */
413 kumpf 1.51 static int compare(const String& s1, const String& s2);
414 mike 1.38
415 karl 1.79 /** Compare two null-terminated strings but ignore case. 416 @param s1 First null-terminated string for the comparison. 417 @param s2 Second null-terminated string for the comparison. 418 @return Return -1 if s1 is less than s2; if equal return 0; 419 otherwise return 1. 420 421 NOTE: Use the comparison operators <,<= > >= to compare 422 String objects.
423 david 1.81 ICU : Operation will use default locale or the locale provided 424 NON ICU: Operattion will use c runtime function
425 kumpf 1.48 */
426 kumpf 1.49 static int compareNoCase(const String& s1, const String& s2);
427 david 1.81 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES 428 /** @param strLocale const char * is the locale to use for the operation. 429 If NULL will use the default locale for the process. 430 Refer to Locale constants for formating. 431 / 432 static int compareNoCase(const String& s1, const String& s2, const char strLocale); 433 #endif
434 kumpf 1.48
435 mike 1.38 /** Compare two String objects for equality. 436 @param s1 First <TT>String</TT> for comparison. 437 @param s2 Second <TT>String</TT> for comparison. 438
439 karl 1.79 @return true If the two strings are equal; otherwise, false. For example,
440 mike 1.38 <pre> 441 String s1 = "Hello World"; 442 String s2 = s1; 443 String s3(s2); 444 assert(String::equal(s1, s3)); 445 </pre> 446 */
447 kumpf 1.48 static Boolean equal(const String& str1, const String& str2);
448 mike 1.38
449 kumpf 1.74 /** Compares two strings and returns true if they 450 are equal indepedent of case of the characters. 451 @param str1 First String parameter. 452 @param str2 Second String parameter.
453 karl 1.79 @return true If strings are equal independent of case, flase
454 kumpf 1.74 otherwise.
455 david 1.81 456 ICU : Operation will use default locale or the locale provided 457 NON ICU: Operation will use c runtime function
458 karl 1.47 */
459 kumpf 1.48 static Boolean equalNoCase(const String& str1, const String& str2);
460 david 1.81 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES 461 /** @param strLocale const char * is the locale to use for the operation. 462 If NULL will use the default locale for the process. 463 Refer to Locale constants for formating. 464 / 465 static Boolean equalNoCase(const String& str1, const String& str2, const char strLocale); 466 #endif
467 david 1.76
468 mike 1.38 private: 469
470 kumpf 1.51 StringRep* _rep;
471 mike 1.38 };
472 mike 1.40
473 karl 1.79 /** String operator == tests for equality between two strings of any of the
474 mike 1.38 types String or char*.
475 karl 1.79 @return true If the strings are equal; otherwise, false. 476 @param str1 REVIEWERS: Insert description here. 477 @param str2 REVIEWERS: Insert description here.
478 mike 1.38 */
479 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==( 480 const String& str1, 481 const String& str2);
482 mike 1.38
483 kumpf 1.74 /** String operator ==. Test for equality between two strings.
484 karl 1.79 @param str1 REVIEWERS: Insert description here. 485 @param str2 REVIEWERS: Insert description here.
486 mike 1.38 */
487 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2);
488 mike 1.38
489 kumpf 1.74 /** String operator ==. Test for equality between two strings.
490 karl 1.79 @param str1 REVIEWERS: Insert description here. 491 @param str2 REVIEWERS: Insert description here.
492 mike 1.38 */
493 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2);
494 mike 1.38
495 kumpf 1.74 /** String operator ==. Test for equality between two strings.
496 karl 1.79 @param str1 REVIEWERS: Insert description here. 497 @param str2 REVIEWERS: Insert description here.
498 mike 1.38 */
499 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator!=( 500 const String& str1, 501 const String& str2);
502 mike 1.38
503 karl 1.79 /** REVIEWERS: Insert description here. 504 @param str REVIEWERS: Insert description here. 505 @param os REVIEWERS: Insert description here. 506 */
507 mike 1.38 PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<( 508 PEGASUS_STD(ostream)& os,
509 kumpf 1.48 const String& str);
510 mike 1.38
511 karl 1.79 /** This overload operator (+) concatenates String objects. For example,
512 mike 1.38 <pre> 513 String t1 = "abc"; 514 String t2; 515 t2 = t1 + "def" 516 assert(t2 == "abcdef"); 517 </pre> 518 */
519 kumpf 1.48 PEGASUS_COMMON_LINKAGE String operator+(const String& str1, const String& str2);
520 mike 1.38
521 karl 1.79 /** The overload operator (<) compares String obects.
522 mike 1.38 <pre> 523 String t1 = "def"; 524 String t2 = "a"; 525 assert (t2 < t1); 526 </pre>
527 karl 1.79 @param str1 REVIEWERS: Insert description here. 528 @param str2 REVIEWERS: Insert description here.
529 mike 1.38 */
530 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<( 531 const String& str1, 532 const String& str2);
533 mike 1.38
534 karl 1.79 /** The overload operator (<=) compares String objects. 535 @param str1 REVIEWERS: Insert description here. 536 @param str2 REVIEWERS: Insert description here.
537 mike 1.38 */
538 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<=( 539 const String& str1, 540 const String& str2);
541 mike 1.38
542 karl 1.79 /** The overload operator (>) compares String objects. 543 @param str1 REVIEWERS: Insert description here. 544 @param str2 REVIEWERS: Insert description here.
545 mike 1.38 */
546 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>( 547 const String& str1, 548 const String& str2);
549 mike 1.38
550 karl 1.79 /** The overload operator (>=) compares String objects. 551 @param str1 REVIEWERS: Insert description here. 552 @param str2 REVIEWERS: Insert description here.
553 mike 1.38 */
554 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>=( 555 const String& str1, 556 const String& str2);
557 mike 1.38 558 PEGASUS_NAMESPACE_END 559 560 #endif /* Pegasus_String_h */

No CVS admin address has been configured