1 mike 1.18 //%/////////////////////////////////////////////////////////////////////////////
|
2 mike 1.1 //
3 // Copyright (c) 2000 The Open Group, BMC Software, Tivoli Systems, IBM
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a
6 // copy of this software and associated documentation files (the "Software"),
7 // to deal in the Software without restriction, including without limitation
8 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 // and/or sell copies of the Software, and to permit persons to whom the
10 // Software is furnished to do so, subject to the following conditions:
11 //
12 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
13 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
14 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
15 // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
16 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
17 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
18 // DEALINGS IN THE SOFTWARE.
19 //
|
20 mike 1.18 //==============================================================================
|
21 mike 1.1 //
|
22 mike 1.18 // Author: Mike Brasher (mbrasher@bmc.com)
|
23 mike 1.1 //
|
24 mike 1.18 // Modified By:
|
25 mike 1.17 //
|
26 mike 1.18 //%/////////////////////////////////////////////////////////////////////////////
|
27 mike 1.1
28 #ifndef Pegasus_String_h
29 #define Pegasus_String_h
30
31 #include <iostream>
32 #include <cstring>
33 #include <Pegasus/Common/Config.h>
34 #include <Pegasus/Common/Char16.h>
35 #include <Pegasus/Common/Array.h>
36
37 PEGASUS_NAMESPACE_BEGIN
38
|
39 karl 1.2 /**
|
40 karl 1.12 The Pegasus String C++ Class implements the CIM string type.
41 This class is based on the general handle/representation pattern
42 defined for all the Pegasus objects. However, it differes from
43 most in that it implements "copy on assign" all of the others implement
44 "no copy on assign" semantics. The string class uses the Array class and
45 implements an array of characters.
46 */
|
47 mike 1.1 class PEGASUS_COMMON_LINKAGE String
48 {
49 public:
50
|
51 karl 1.12 /** Default constructor without parameters. This constructor creates a
52 null string
53 <pre>
54 String test;
55 </pre>
56 */
|
57 mike 1.1 String();
|
58 mike 1.6
59 /// Copy constructor.
|
60 mike 1.1 String(const String& x);
|
61 mike 1.6
62 /// Initialize with first n characters from x.
|
63 mike 1.1 String(const String& x, Uint32 n);
|
64 mike 1.6
65 /// Initialize with x.
|
66 mike 1.1 String(const Char16* x);
|
67 mike 1.6
68 /// Initialize with first n characters of x.
|
69 mike 1.1 String(const Char16* x, Uint32 n);
|
70 mike 1.6
71 /// Initialize from a plain old C-String:
|
72 mike 1.1 String(const char* x);
|
73 mike 1.6
74 /// Initialize from the first n characters of a plain old C-String:
|
75 mike 1.1 String(const char* x, Uint32 n);
76
|
77 karl 1.12 /// String destructor. Used by the representation of the String object
|
78 mike 1.6 ~String()
79 {
80 }
81
|
82 karl 1.12 /** Assign this string with x.
83 <pre>
84 String t1 = "abc";
85 String t2 = t1;
86 </pre>
87 */
|
88 mike 1.1 String& operator=(const String& x) { _rep = x._rep; return *this; }
|
89 mike 1.6
90 /// Assign this string with x.
|
91 mike 1.1 String& operator=(const Char16* x) { assign(x); return *this; }
|
92 mike 1.6
|
93 karl 1.8 /// Assign this string with x.
|
94 mike 1.1 String& assign(const String& x) { _rep = x._rep; return *this; }
|
95 mike 1.6
96 /// Assign this string with x.
|
97 mike 1.1 String& assign(const Char16* x);
|
98 mike 1.6
99 /// Assign this string with first n characters of x.
|
100 mike 1.1 String& assign(const Char16* x, Uint32 n);
|
101 mike 1.6
102 /// Assign this string with the plain old C-String x.
|
103 mike 1.1 String& assign(const char* x);
|
104 mike 1.6
105 /// Assign this string with first n characters of the plain old C-String x.
|
106 mike 1.1 String& assign(const char* x, Uint32 n);
|
107 mike 1.6
|
108 karl 1.12 /** Clear this string. After calling clear(), getLength() will return 0.
109 <pre>
110 String test = "abc";
111 test.clear(); // String test is now NULL (length == 0)
112 </pre>
113 */
|
114 mike 1.1 void clear() { _rep.clear(); _rep.append('\0'); }
|
115 mike 1.4
|
116 mike 1.6 /** Reserves memory for capacity characters. Notice that this does not
117 change the size of the string (getSize() returns what it did before).
118 If the capacity of the string is already greater or equal to the
119 capacity argument, this method has no effect. After calling reserve(),
120 getCapicty() returns a value which is greater or equal to the
121 capacity argument.
|
122 karl 1.12 @param capacity defines the capacity in characters to reserve.
|
123 karl 1.2 */
|
124 mike 1.1 void reserve(Uint32 capacity) { _rep.reserve(capacity + 1); }
|
125 mike 1.4
|
126 karl 1.12 /** Returns the length of the String object.
127 @return Length of the string in characters.
128 <pre>
129 String s = "abcd";
130 assert(s.getLength() == 4);
131 </pre>
132 */
|
133 mike 1.1 Uint32 getLength() const { return _rep.getSize() - 1; }
|
134 mike 1.4
|
135 karl 1.12 /** Returns a pointer to the first character in the null-terminated string
136 string.
137 @param
138 @return Pointer to the first character of the String object
139 <pre>
140 String t1 = "abc";
141 const Char16* q = t1.getData();
142 </pre>
143 */
|
144 mike 1.1 const Char16* getData() const { return _rep.getData(); }
145
|
146 mike 1.6 /** Allocates an 8 bit representation of this string. The user is
147 responsible for freeing the result. If any characters are truncated,
148 a TruncatedCharacter exception is thrown. This exception may
149 be suppressed by passing true as the noThrow argument. Extra
150 characters may be allocated at the end of the new string by
151 passing a non-zero value to the extraBytes argument.
|
152 karl 1.12 @param extraBytes - Defines the number of extra characters to be
153 allocated at the end of the new string. Default is zero.
154 @param noThrow - If true, no exception will be thrown if characters
155 are truncated
156 @return pointer to the new representation of the string
157 @exception Throws TruncatedCharacter exception if any characters are
158 truncated
159 <pre>
160 String test = "abc";
161 char* p = test.allocateCString();
162 </pre>
|
163 mike 1.6 */
|
164 mike 1.1 char* allocateCString(Uint32 extraBytes = 0, Boolean noThrow = false) const;
165
|
166 mike 1.6 /** Append the given string to a C-string. If the length is not Uint32(-1),
167 then the lesser of the the length argument and the length of this
168 string is truncated. Otherwise, the entire string is trunctated. The
169 TruncatedCharacter exception is thrown if any characters are truncated.
|
170 karl 1.11 <pre>
171 const char STR0[] = "one two three four";
172 String s = STR0;
173 const char STR1[] = "zero ";
174 char* tmp = new char[strlen(STR1) + s.getLength() + 1];
175 strcpy(tmp, STR1);
176 s.appendToCString(tmp, 7);
177 assert(strcmp(tmp, "zero one two") == 0);
178 </pre>
|
179 karl 1.2 */
|
180 mike 1.1 void appendToCString(
|
181 karl 1.2 char* str,
|
182 mike 1.1 Uint32 length = Uint32(-1),
183 Boolean noThrow = false) const;
184
|
185 karl 1.12 /** Returns the Ith character of the String object.
|
186 mike 1.15 @exception - Throws exception "OutofBounds" if the index
187 is outside the length of the string.
188 <pre>
189 String t1 = "abc;
190 Char16 c = t1[1]; // character b
191 </pre>
|
192 karl 1.12 */
|
193 mike 1.1 Char16& operator[](Uint32 i);
194
|
195 karl 1.12 /** Returns the Ith character of the String (const version).
|
196 mike 1.15 @exception - Throws exception "OutofBounds" if the index
197 is outside the length of the string.
|
198 karl 1.12
199 */
|
200 mike 1.1 const Char16 operator[](Uint32 i) const;
|
201 mike 1.6
|
202 karl 1.11 /** Append the given character to the string.
203 <pre>
204 String s4 = "Hello";
205 s4.append(Char16(0x0000))
206 </pre>
207 */
|
208 karl 1.2 String& append(const Char16& c)
209 {
210 _rep.insert(_rep.getSize() - 1, c);
|
211 mike 1.1 return *this;
212 }
|
213 mike 1.6
|
214 karl 1.12 /// Append n characters from str to this String object.
|
215 mike 1.1 String& append(const Char16* str, Uint32 n);
|
216 mike 1.6
|
217 karl 1.12 /// Append the characters of str to this String object.
|
218 karl 1.2 String& append(const String& str)
|
219 mike 1.1 {
220 return append(str.getData(), str.getLength());
221 }
|
222 mike 1.6
|
223 karl 1.12 /** Overload operator += appends the parameter String to this String.
|
224 mike 1.15 @parm String to append.
225 @return This String
226 <pre>
227 String test = "abc";
228 test += "def";
229 assert(test == "abcdef");
230 </pre>
|
231 karl 1.12 */
|
232 mike 1.1 String& operator+=(const String& x)
233 {
234 return append(x);
235 }
|
236 mike 1.6
|
237 karl 1.12 /** Append the character given by c to this String object.
238 @param c - Single character
239 */
|
240 mike 1.1 String& operator+=(Char16 c)
241 {
242 return append(c);
243 }
|
244 mike 1.6
|
245 karl 1.12 /** Append the character given by c to this string.
|
246 mike 1.15 <pre>
247 String t1 = "abc";
248 t1 += 'd'
249 assert(t1 == "abcd");
250 </pre>
|
251 karl 1.12 */
|
252 mike 1.1 String& operator+=(char c)
253 {
254 return append(Char16(c));
255 }
|
256 mike 1.3
|
257 mike 1.6 /** Remove size characters from the string starting at the given
258 position. If size is -1, then all characters after pos are removed.
|
259 karl 1.12 @param pos - Position in string to start remove
260 @param size - Number of characters to remove. Default is -1 which
261 causes all characters after pos to be removed
262 <pre>
263 String s;
264 s = "abc";
265 s.remove(0, 1);
266 assert(String::equal(s, "bc"));
267 assert(s.getLength() == 2);
268 s.remove(0);
269 assert(String::equal(s, ""));
270 assert(s.getLength() == 0);
271 </pre>
272 @exception throws "OutOfBounds" exception if size is greater than
273 length of String plus starting position for remove.
|
274 mike 1.6 */
|
275 mike 1.1 void remove(Uint32 pos, Uint32 size = Uint32(-1));
|
276 mike 1.3
|
277 karl 1.11 /** Return a new String which is initialzed with <TT>length</TT>
|
278 karl 1.8 characters from this string starting at <TT>pos</TT>.
279 @param <TT>pos</TT> is the positon in string to start getting the
280 substring.
281 @param <TT>length</TT> is the number of characters to get. If length
282 is -1, then all characters after pos are added to the new string.
283 @return String with the defined substring.
|
284 karl 1.11 <pre>
285 s = "abcdefg";
286 s.remove(3);
287 assert(String::equal(s, "abc"));
288 </pre>
|
289 mike 1.6 */
|
290 mike 1.1 String subString(Uint32 pos, Uint32 length = Uint32(-1)) const;
|
291 mike 1.3
|
292 mike 1.7 /** Find the position of the first occurence of the character c.
293 If the character is not found, -1 is returned.
|
294 karl 1.12 @param c - Char to be found in the String
295 @return Position of the character in the string or -1 if not found.
|
296 mike 1.6 */
|
297 mike 1.1 Uint32 find(Char16 c) const;
|
298 mike 1.7
|
299 karl 1.12 /** Find the position of the first occurence of the string object.
300 This function finds one string inside another
301 If the matching substring is not found, -1 is returned.
302 @param s - String object to be found in the String
303 @return Position of the substring in the String or -1 if not
|
304 mike 1.14 found.
305 */
|
306 karl 1.13 Uint32 find(const String& s) const;
|
307 karl 1.12
308 /** Find substring
309 @ param - 16 bit character pointer
310 @seealso find
311 */
312 Uint32 find(const Char16* s) const;
|
313 mike 1.14
|
314 karl 1.12 /** find substring
315 @param char* to substring
316 */
317 Uint32 find(const char* s) const;
318
|
319 mike 1.7 /** Same as find() but start looking in reverse (last character first).
|
320 karl 1.12 @Seealso find
321 @return Position of the character in the string or -1 if not found.
322
323 NOTE: This function is defined only for char* input, not for
324 String.
|
325 mike 1.7 */
326 Uint32 reverseFind(Char16 c) const;
|
327 mike 1.3
|
328 mike 1.19 /** Converts all characters in this string to lower case.
329 */
330 void toLower();
331
|
332 mike 1.21 /** Translate any occurences of fromChar to toChar.
333 */
334 void translate(Char16 fromChar, Char16 toChar);
335
|
336 karl 1.12 /** Compare the first n characters of the two strings.
337 @param s1 - First null-terminated string for the comparison
338 @param s2 - Second null-terminated string for the comparison
339 @param n - Number of characters to compare
340 @return Return -1 if s1 is lexographically less than s2. If they
341 are equavalent return 0. Otherwise return 1.
|
342 mike 1.6 */
|
343 mike 1.1 static int compare(const Char16* s1, const Char16* s2, Uint32 n);
|
344 mike 1.3
|
345 karl 1.12 /** Compare two null-terminated strings.
346 @param s1 - First null-terminated string for the comparison
347 @param s2 - Second null-terminated string for the comparison
348 @return If s1 is less than s2, return -1; if equal return 0;
349 otherwise, return 1.
350
351 NOTE: Use the comparison operators <,<= > >= to compare
352 String objects.
|
353 mike 1.6 */
|
354 mike 1.1 static int compare(const Char16* s1, const Char16* s2);
|
355 mike 1.3
|
356 karl 1.12 /** Compare two String objects for equality.
357 @param s1 - First <TT>String</TT> for comparison.
358 @param s2 - Second <TT>String</TT> for comparison.
359
360 @return Boolean true if the two strings are equal.
|
361 karl 1.11 <pre>
362 String s1 = "Hello World";
363 String s2 = s1;
364 String s3(s2);
365 assert(String::equal(s1, s3));
366 </pre>
367 */
|
368 mike 1.9 static Boolean equal(const String& x, const String& y);
369
|
370 karl 1.12 /// Return true if the two strings are equal.
|
371 mike 1.9 static Boolean equal(const String& x, const Char16* y);
372
|
373 karl 1.12 /// Return true if the two strings are equal.
|
374 mike 1.9 static Boolean equal(const Char16* x, const String& y);
375
|
376 karl 1.12 /// Return true if the two strings are equal.
|
377 mike 1.9 static Boolean equal(const String& x, const char* y);
378
|
379 karl 1.11 /// Return true if the two strings are equal.
|
380 mike 1.9 static Boolean equal(const char* x, const String& y);
381
|
382 mike 1.20 static Boolean equalIgnoreCase(const String& x, const String& y);
383
|
384 mike 1.6 /// Convert the plain old C-string to lower case:
385 static void toLower(char* str);
386
|
387 karl 1.10 /** EMPTY - Represent an empty string.
|
388 mike 1.6 This member is used to represent empty strings. Using this member
|
389 karl 1.10 avoids an expensive construction of an empty string (e.g., String()).
|
390 mike 1.6 */
|
391 mike 1.1 static const String EMPTY;
392
393 private:
394
395 static Uint32 _min(Uint32 x, Uint32 y) { return x < y ? x : y; }
396
|
397 karl 1.2 Array<Char16> _rep;
|
398 mike 1.1 };
399
|
400 karl 1.12 /** String operator ==. Test for equality between two strings of any of the
401 types String or char*.
402 @return Boolean - True if the strings are equal
403
404 */
|
405 mike 1.9 inline Boolean operator==(const String& x, const String& y)
406 {
407 return String::equal(x, y);
408 }
|
409 mike 1.1
|
410 karl 1.12 /** String operator ==. Test for equality between two strings
411
412 */
|
413 mike 1.9 inline Boolean operator==(const String& x, const char* y)
414 {
415 return String::equal(x, y);
416 }
|
417 mike 1.1
|
418 karl 1.12 /** String operator ==. Test for equality between two strings
419
420 */
|
421 mike 1.9 inline Boolean operator==(const char* x, const String& y)
422 {
423 return String::equal(x, y);
424 }
|
425 mike 1.1
|
426 karl 1.12 /** String operator ==. Test for equality between two strings
427
428 */
|
429 mike 1.1 inline Boolean operator!=(const String& x, const String& y)
430 {
|
431 mike 1.9 return !String::equal(x, y);
|
432 mike 1.1 }
433
|
434 mike 1.6 PEGASUS_COMMON_LINKAGE std::ostream& operator<<(
435 std::ostream& os,
436 const String& x);
|
437 mike 1.1
|
438 karl 1.12 /** overload operator + - Concatenates String objects.
439
440 <pre>
441 String t1 = "abc";
442 String t2;
443 t2 = t1 + "def"
444 assert(t2 == "abcdef");
445 </pre>
446 */
|
447 mike 1.1 inline String operator+(const String& x, const String& y)
448 {
449 return String(x).append(y);
450 }
|
451 mike 1.15
|
452 karl 1.12 /** overload operator < - Compares String obects.
453 <pre>
454 String t1 = "def";
455 String t2 = "a";
456 assert (t2 < t1);
457 </pre>
458 */
|
459 mike 1.1 inline Boolean operator<(const String& x, const String& y)
460 {
461 return String::compare(x.getData(), y.getData()) < 0;
462 }
|
463 mike 1.15
464 /** overload operator <= compares String objects.
|
465 mike 1.1
|
466 karl 1.12 */
|
467 mike 1.1 inline Boolean operator<=(const String& x, const String& y)
468 {
469 return String::compare(x.getData(), y.getData()) <= 0;
470 }
|
471 mike 1.15
|
472 karl 1.12 /** Overload operator > compares String objects
473 */
|
474 mike 1.1 inline Boolean operator>(const String& x, const String& y)
475 {
476 return String::compare(x.getData(), y.getData()) > 0;
477 }
|
478 mike 1.15
|
479 karl 1.12 /** overload operator >= - Compares String objects
480 */
|
481 mike 1.1 inline Boolean operator>=(const String& x, const String& y)
482 {
483 return String::compare(x.getData(), y.getData()) >= 0;
484 }
|
485 mike 1.6
486 /** Return a version of this string whose characters have been shifted
487 to lower case.
488 */
489 PEGASUS_COMMON_LINKAGE String ToLower(const String& str);
|
490 mike 1.15
491 /** Compare two strings but ignore any case differences.
492 */
493 PEGASUS_COMMON_LINKAGE int CompareIgnoreCase(const char* s1, const char* s2);
|
494 mike 1.16
495 /** Get the next line from the input file.
496 */
497 PEGASUS_COMMON_LINKAGE Boolean GetLine(std::istream& is, String& line);
|
498 mike 1.6
|
499 mike 1.17 /* This is an internal class not to be used by the internal Pegasus
500 components only. It provides an easy way to create an 8-bit string
501 representation on the fly without calling allocateCString() and
502 then worrying about deleting the string. The underscore before the
503 class name denotes that this class is internal, unsupported, undocumented,
504 and may be removed in future releases.
505 */
506 class _CString
507 {
508 public:
509
510 _CString(const String& x)
511 {
512 _rep = x.allocateCString();
513 }
514
515 _CString(const _CString& x)
516 {
517 _rep = strcpy(new char[strlen(x._rep) + 1], x._rep);
518 }
519
520 mike 1.17 ~_CString()
521 {
522 delete [] _rep;
523 }
524
525 _CString& operator=(const _CString& x)
526 {
527 if (this != &x)
528 _rep = strcpy(new char[strlen(x._rep) + 1], x._rep);
529
530 return *this;
531 }
532
533 operator const char*() const
534 {
535 return _rep;
536 }
537
538 const char* data() const
539 {
540 return _rep;
541 mike 1.17 }
542
543 private:
544
545 char* _rep;
546 };
|
547 mike 1.1
548 PEGASUS_NAMESPACE_END
549
550 #endif /* Pegasus_String_h */
|
Return to
String.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common