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 #include <iostream>
35 #include <fstream>
36 #include <cstring>
37 #include <Pegasus/Common/Config.h>
38 #include <Pegasus/Common/Char16.h>
39
40 PEGASUS_NAMESPACE_BEGIN
41
|
42 kumpf 1.51 class StringRep;
43
|
44 mike 1.38 /**
45 The Pegasus String C++ Class implements the CIM string type.
46 This class is based on the general handle/representation pattern
47 defined for all the Pegasus objects. However, it differes from
48 most in that it implements "copy on assign" all of the others implement
49 "no copy on assign" semantics. The string class uses the Array class and
50 implements an array of characters.
51 */
52 class PEGASUS_COMMON_LINKAGE String
53 {
54 public:
55
|
56 kumpf 1.48 /** EMPTY - Represent an empty string.
57 This member is used to represent empty strings. Using this member
58 avoids an expensive construction of an empty string (e.g., String()).
59 */
60 static const String EMPTY;
61
|
62 mike 1.38 /** Default constructor without parameters. This constructor creates a
63 null string
64 <pre>
65 String test;
66 </pre>
67 */
68 String();
69
70 /// Copy constructor.
|
71 kumpf 1.48 String(const String& str);
|
72 mike 1.38
|
73 kumpf 1.48 /// Initialize with first n characters from str.
74 String(const String& str, Uint32 n);
|
75 mike 1.38
|
76 kumpf 1.48 /// Initialize with str.
77 String(const Char16* str);
|
78 mike 1.38
|
79 kumpf 1.48 /// Initialize with first n characters of str.
80 String(const Char16* str, Uint32 n);
|
81 mike 1.38
82 /// Initialize from a plain old C-String:
|
83 kumpf 1.48 String(const char* str);
|
84 mike 1.38
85 /// Initialize from the first n characters of a plain old C-String:
|
86 kumpf 1.48 String(const char* str, Uint32 n);
|
87 mike 1.38
88 /// String destructor. Used by the representation of the String object
89 ~String();
90
|
91 kumpf 1.48 /** Assign this string with str.
|
92 mike 1.38 <pre>
93 String t1 = "abc";
94 String t2 = t1;
95 </pre>
96 */
|
97 kumpf 1.48 String& operator=(const String& str);
|
98 mike 1.38
|
99 kumpf 1.48 /** Assign this string with String str
100 @param str String to assign
|
101 mike 1.38 @return Returns the String
102 */
|
103 kumpf 1.48 String& assign(const String& str);
|
104 mike 1.38
|
105 kumpf 1.48 /// Assign this string with str.
106 String& assign(const Char16* str);
|
107 mike 1.38
|
108 kumpf 1.48 /// Assign this string with first n characters of str.
109 String& assign(const Char16* str, Uint32 n);
|
110 mike 1.38
|
111 kumpf 1.48 /// Assign this string with the plain old C-String str.
112 String& assign(const char* str);
|
113 mike 1.38
|
114 kumpf 1.48 /// Assign this string with first n characters of the plain old C-String str.
115 String& assign(const char* str, Uint32 n);
|
116 mike 1.38
117 /** clear - Clear this string. After calling clear(), size() will return 0.
118 <pre>
119 String test = "abc";
120 test.clear(); // String test is now NULL (length == 0)
121 </pre>
122 */
123 void clear();
124
125
|
126 kumpf 1.53 /** reserveCapacity - Reserves memory for capacity characters. Notice
127 that this does not change the size of the string (size() returns
128 what it did before). If the capacity of the string is already
129 greater or equal to the capacity argument, this method has no
130 effect. The capacity of a String object has no bearing on its
131 external behavior. The capacity of a String is set only for
132 performance reasons.
|
133 mike 1.38 @param capacity defines the capacity in characters to reserve.
134 */
|
135 kumpf 1.51 void reserveCapacity(Uint32 capacity);
|
136 mike 1.38
137 /** Returns the length of the String object.
138 @return Length of the string in characters.
139 <pre>
140 String s = "abcd";
141 assert(s.size() == 4);
142 </pre>
143 */
|
144 kumpf 1.48 Uint32 size() const;
|
145 mike 1.38
|
146 mike 1.41 /** getData Returns a pointer to the first character in the
147 null-terminated string string of the String object.
|
148 mike 1.38 @return Pointer to the first character of the String object
149 <pre>
150 String t1 = "abc";
151 const Char16* q = t1.getData();
152 </pre>
153 */
|
154 kumpf 1.48 const Char16* getData() const;
|
155 mike 1.38
|
156 kumpf 1.48 /** allocateCString - allocates an 8 bit representation of this String
|
157 mike 1.41 object. The user is responsible for freeing the result. If any
158 characters are truncated, a TruncatedCharacter exception is thrown.
159 This exception may be suppressed by passing true as the noThrow
160 argument. Extra characters may be allocated at the end of the
161 new string by passing a non-zero value to the extraBytes argument.
162
|
163 mike 1.38 @param extraBytes Defines the number of extra characters to be
164 allocated at the end of the new string. Default is zero.
|
165 mike 1.41
|
166 mike 1.38 @param noThrow If true, no exception will be thrown if characters
167 are truncated
|
168 mike 1.41
|
169 mike 1.38 @return pointer to the new representation of the string
|
170 mike 1.41
|
171 mike 1.38 @exception Throws TruncatedCharacter exception if any characters are
172 truncated
173 <pre>
174 String test = "abc";
175 char* p = test.allocateCString();
176 ...
177 delete [] p;
178 </pre>
179 */
180 char* allocateCString(Uint32 extraBytes = 0, Boolean noThrow = false) const;
181
182 /** Returns the Ith character of the String object.
183 @exception - Throws exception "OutofBounds" if the index
184 is outside the length of the string.
185 <pre>
186 String t1 = "abc;
187 Char16 c = t1[1]; // character b
188 </pre>
189 */
190 Char16& operator[](Uint32 i);
191
192 mike 1.38 /** Returns the Ith character of the String (const version).
193 @exception - Throws exception "OutofBounds" if the index
194 is outside the length of the string.
195
196 */
197 const Char16 operator[](Uint32 i) const;
198
199 /** Append the given character to the string.
200 <pre>
201 String s4 = "Hello";
202 s4.append(Char16(0x0000))
203 </pre>
204 */
205 String& append(const Char16& c);
206
207 /// Append n characters from str to this String object.
208 String& append(const Char16* str, Uint32 n);
209
210 /// Append the characters of str to this String object.
|
211 kumpf 1.48 String& append(const String& str);
|
212 mike 1.38
213 /** Overload operator += appends the parameter String to this String.
214 @param String to append.
215 @return This String
216 <pre>
217 String test = "abc";
218 test += "def";
219 assert(test == "abcdef");
220 </pre>
221 */
|
222 kumpf 1.48 String& operator+=(const String& str);
|
223 mike 1.38
224 /** Append the character given by c to this String object.
225 @param c Single character to be appended
226 @return String with appended character
227 */
|
228 kumpf 1.48 String& operator+=(Char16 c);
|
229 mike 1.38
230 /** Append the character given by c to this string.
231 <pre>
232 String t1 = "abc";
233 t1 += 'd'
234 assert(t1 == "abcd");
235 </pre>
236 */
|
237 kumpf 1.48 String& operator+=(char c);
|
238 mike 1.38
239 /** Remove size characters from the string starting at the given
240 position. If size is PEG_NOT_FOUND, then all characters after pos are
241 removed.
242 @param pos Position in string to start remove
243 @param size Number of characters to remove. Default is PEG_NOT_FOUND
244 (Uint32(-1) which causes all characters after pos to be removed
245 <pre>
246 String s;
247 s = "abc";
248 s.remove(0, 1);
249 assert(String::equal(s, "bc"));
250 assert(s.size() == 2);
251 s.remove(0);
252 assert(String::equal(s, ""));
253 assert(s.size() == 0);
254 </pre>
255 @exception throws "OutOfBounds" exception if size is greater than
256 length of String plus starting position for remove.
257 */
258 void remove(Uint32 pos, Uint32 size = PEG_NOT_FOUND);
259 mike 1.38
260 /** Return a new String which is initialzed with <TT>length</TT>
261 characters from this string starting at <TT>pos</TT>.
262 @param <TT>pos</TT> is the positon in string to start getting the
263 substring.
264 @param <TT>length</TT> is the number of characters to get. If length
265 is PEG_NOT_FOUND, then all characters after pos are added to the new
266 string.
267 @return String with the defined substring.
268 <pre>
269 s = "abcdefg";
270 s.remove(3);
271 assert(String::equal(s, "abc"));
272 </pre>
273 */
274 String subString(Uint32 pos, Uint32 length = PEG_NOT_FOUND) const;
275
276 /** Find the position of the first occurence of the character c.
277 If the character is not found, PEG_NOT_FOUND is returned.
278 @param c Char to be found in the String
279 @return Position of the character in the string or PEG_NOT_FOUND if not
280 mike 1.38 found.
281 */
282 Uint32 find(Char16 c) const;
283
|
284 mike 1.41 /** Same as above but starts searching from the given position. */
285 Uint32 find(Uint32 pos, Char16 c) const;
|
286 mike 1.38
287 /** Find the position of the first occurence of the string object.
288 This function finds one string inside another
289 If the matching substring is not found, PEG_NOT_FOUND is returned.
290 @param s String object to be found in the String
291 @return Position of the substring in the String or PEG_NOT_FOUND if not
292 found.
293 */
294 Uint32 find(const String& s) const;
295
296 /** reverseFind - Same as find() but start looking in reverse (last
297 character first).
298 @param c Char16 character to find in String.
299 @Seealso find
300 @return Position of the character in the string or PEG_NOT_FOUND if not
301 found.
302
303 NOTE: This function is defined only for char* input, not for
304 String.
305 */
306 Uint32 reverseFind(Char16 c) const;
307 mike 1.38
|
308 kumpf 1.49 #ifdef PEGASUS_INTERNALONLY
309 // ATTN-RK-P3-20020509: Define case-sensitivity for non-English characters
|
310 mike 1.38 /** Converts all characters in this string to lower case.
311 */
312 void toLower();
|
313 kumpf 1.49 #endif
|
314 kumpf 1.48
|
315 mike 1.38 /** Compare the first n characters of the two strings..
316 @param s1 First null-terminated string for the comparison.
317 @param s2 Second null-terminated string for the comparison.
318 @param n Number of characters to compare.
319 @return Return -1 if s1 is lexographically less than s2. If they are
320 equavalent return 0. Otherwise return 1.
321 */
|
322 kumpf 1.51 static int compare(const String& s1, const String& s2, Uint32 n);
|
323 mike 1.38
324 /** Compare two null-terminated strings.
325 @param s1 First null-terminated string for the comparison.
326 @param s2 Second null-terminated string for the comparison.
327 @return If s1 is less than s2, return -1; if equal return 0;
328 otherwise, return 1.
329
330 NOTE: Use the comparison operators <,<= > >= to compare
331 String objects.
332 */
|
333 kumpf 1.51 static int compare(const String& s1, const String& s2);
|
334 mike 1.38
|
335 kumpf 1.48 /** Just like one above except ignores case differences.
336 */
337 static int compareNoCase(const char* s1, const char* s2, Uint32 n);
338
339 static int compareNoCase(const char* s1, const char* s2);
|
340 kumpf 1.49
341 #ifdef PEGASUS_INTERNALONLY
342 static int compareNoCase(const String& s1, const String& s2);
343 #endif
|
344 kumpf 1.48
|
345 mike 1.38 /** Compare two String objects for equality.
346 @param s1 First <TT>String</TT> for comparison.
347 @param s2 Second <TT>String</TT> for comparison.
348
349 @return Boolean true if the two strings are equal.
350 <pre>
351 String s1 = "Hello World";
352 String s2 = s1;
353 String s3(s2);
354 assert(String::equal(s1, s3));
355 </pre>
356 */
|
357 kumpf 1.48 static Boolean equal(const String& str1, const String& str2);
|
358 mike 1.38
|
359 karl 1.47 /** equalNoCase - Compares two strings and returuns true if they
360 are equal indpedent of case of the characters.
|
361 kumpf 1.48 @param str1 First String parameter
362 @param str2 Second String parameter
|
363 karl 1.47 @return true if strings are equal independent of case.
364 */
|
365 kumpf 1.48 static Boolean equalNoCase(const String& str1, const String& str2);
|
366 mike 1.38
|
367 karl 1.46 /** match matches a string against a GLOB style pattern.
368 Return trues if the String parameter matches the pattern. C-Shell style
369 glob matching is used.
370 @param str String to be matched against the pattern
371 @param pattern Pattern to use in the match
372 @return Boolean true if str matches pattern
373 The pattern definition is as follows:
374 <pre>
375 * Matches any number of any characters
376 ? Match exactly one character
377 [chars] Match any character in chars
378 [chara-charb] Match any character in the range between chara and charb
379 </pre>
380 The literal characters *, ?, [, ] can be included in a string by
381 escaping them with backslash "\". Ranges of characters can be concatenated.
382 <pre>
383 examples:
384 Boolean result = String::match("This is a test", "*is*");
385 Boolean works = String::match("abcdef123", "*[0-9]");
386 </pre>
387 */
388 karl 1.46 static Boolean match(const String& str, const String& pattern);
389
|
390 kumpf 1.48 /** matchNoCase Matches a String against a GLOB style pattern independent
|
391 karl 1.46 of case.
392 Returns true if the str parameter matches the pattern. C-Shell style
393 glob matching is used. Ignore case in all comparisons. Case is
394 ignored in the match.
395 @parm str String containing the string to be matched\
396 @parm pattern GLOB style patterh to use in the match.
397 @return Boolean true if str matches patterh
398 @SeeAlso match
399 */
400 static Boolean matchNoCase(const String& str, const String& pattern);
401
|
402 mike 1.38 private:
403
|
404 kumpf 1.51 StringRep* _rep;
|
405 mike 1.38 };
|
406 mike 1.40
|
407 mike 1.38 /** String operator ==. Test for equality between two strings of any of the
408 types String or char*.
409 @return Boolean - True if the strings are equal
410 */
|
411 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(
412 const String& str1,
413 const String& str2);
|
414 mike 1.38
415 /** String operator ==. Test for equality between two strings
416
417 */
|
418 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2);
|
419 mike 1.38
420 /** String operator ==. Test for equality between two strings
421
422 */
|
423 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2);
|
424 mike 1.38
425 /** String operator ==. Test for equality between two strings
426
427 */
|
428 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator!=(
429 const String& str1,
430 const String& str2);
|
431 mike 1.38
432 PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<(
433 PEGASUS_STD(ostream)& os,
|
434 kumpf 1.48 const String& str);
|
435 mike 1.38
436 /** overload operator + - Concatenates String objects.
437
438 <pre>
439 String t1 = "abc";
440 String t2;
441 t2 = t1 + "def"
442 assert(t2 == "abcdef");
443 </pre>
444 */
|
445 kumpf 1.48 PEGASUS_COMMON_LINKAGE String operator+(const String& str1, const String& str2);
|
446 mike 1.38
447 /** overload operator < - Compares String obects.
448 <pre>
449 String t1 = "def";
450 String t2 = "a";
451 assert (t2 < t1);
452 </pre>
453 */
|
454 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<(
455 const String& str1,
456 const String& str2);
|
457 mike 1.38
458 /** overload operator <= compares String objects.
459
460 */
|
461 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<=(
462 const String& str1,
463 const String& str2);
|
464 mike 1.38
465 /** Overload operator > compares String objects
466 */
|
467 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>(
468 const String& str1,
469 const String& str2);
|
470 mike 1.38
471 /** overload operator >= - Compares String objects
472 */
|
473 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>=(
474 const String& str1,
475 const String& str2);
|
476 mike 1.38
477 /** Compare two strings but ignore any case differences.
478 */
479 PEGASUS_COMMON_LINKAGE int CompareNoCase(const char* s1, const char* s2);
|
480 mike 1.41
|
481 kumpf 1.48 PEGASUS_COMMON_LINKAGE int EqualNoCase(const char* s1, const char* s2);
|
482 mike 1.38
|
483 kumpf 1.48 #ifdef PEGASUS_INTERNALONLY
|
484 mike 1.38 /* This is an internal class to be used by the internal Pegasus
485 components only. It provides an easy way to create an 8-bit string
486 representation on the fly without calling allocateCString() and
487 then worrying about deleting the string. The underscore before the
488 class name denotes that this class is internal, unsupported, undocumented,
489 and may be removed in future releases.
490 */
491 class _CString
492 {
493 public:
494
|
495 kumpf 1.48 _CString(const String& str)
|
496 mike 1.38 {
|
497 kumpf 1.48 _rep = str.allocateCString();
|
498 mike 1.38 }
499
|
500 kumpf 1.48 _CString(const _CString& str)
|
501 mike 1.38 {
|
502 kumpf 1.48 _rep = strcpy(new char[strlen(str._rep) + 1], str._rep);
|
503 mike 1.38 }
504
505 ~_CString()
506 {
507 delete [] _rep;
508 }
509
|
510 kumpf 1.48 _CString& operator=(const _CString& str)
|
511 mike 1.38 {
|
512 kumpf 1.48 if (this != &str)
513 _rep = strcpy(new char[strlen(str._rep) + 1], str._rep);
|
514 mike 1.38
515 return *this;
516 }
517
518 operator const char*() const
519 {
520 return _rep;
521 }
522
523 const char* data() const
524 {
525 return _rep;
526 }
527
528 private:
529
530 char* _rep;
531 };
|
532 kumpf 1.48 #endif
|
533 mike 1.38
534 PEGASUS_NAMESPACE_END
535
536 #endif /* Pegasus_String_h */
|
Return to
String.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common