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 karl 1.12 /** Compare the first n characters of the two strings.
329 @param s1 - First null-terminated string for the comparison
330 @param s2 - Second null-terminated string for the comparison
331 @param n - Number of characters to compare
332 @return Return -1 if s1 is lexographically less than s2. If they
333 are equavalent return 0. Otherwise return 1.
|
334 mike 1.6 */
|
335 mike 1.1 static int compare(const Char16* s1, const Char16* s2, Uint32 n);
|
336 mike 1.3
|
337 karl 1.12 /** Compare two null-terminated strings.
338 @param s1 - First null-terminated string for the comparison
339 @param s2 - Second null-terminated string for the comparison
340 @return If s1 is less than s2, return -1; if equal return 0;
341 otherwise, return 1.
342
343 NOTE: Use the comparison operators <,<= > >= to compare
344 String objects.
|
345 mike 1.6 */
|
346 mike 1.1 static int compare(const Char16* s1, const Char16* s2);
|
347 mike 1.3
|
348 karl 1.12 /** Compare two String objects for equality.
349 @param s1 - First <TT>String</TT> for comparison.
350 @param s2 - Second <TT>String</TT> for comparison.
351
352 @return Boolean true if the two strings are equal.
|
353 karl 1.11 <pre>
354 String s1 = "Hello World";
355 String s2 = s1;
356 String s3(s2);
357 assert(String::equal(s1, s3));
358 </pre>
359 */
|
360 mike 1.9 static Boolean equal(const String& x, const String& y);
361
|
362 karl 1.12 /// Return true if the two strings are equal.
|
363 mike 1.9 static Boolean equal(const String& x, const Char16* y);
364
|
365 karl 1.12 /// Return true if the two strings are equal.
|
366 mike 1.9 static Boolean equal(const Char16* x, const String& y);
367
|
368 karl 1.12 /// Return true if the two strings are equal.
|
369 mike 1.9 static Boolean equal(const String& x, const char* y);
370
|
371 karl 1.11 /// Return true if the two strings are equal.
|
372 mike 1.9 static Boolean equal(const char* x, const String& y);
373
|
374 mike 1.6 /// Convert the plain old C-string to lower case:
375 static void toLower(char* str);
376
|
377 karl 1.10 /** EMPTY - Represent an empty string.
|
378 mike 1.6 This member is used to represent empty strings. Using this member
|
379 karl 1.10 avoids an expensive construction of an empty string (e.g., String()).
|
380 mike 1.6 */
|
381 mike 1.1 static const String EMPTY;
382
383 private:
384
385 static Uint32 _min(Uint32 x, Uint32 y) { return x < y ? x : y; }
386
|
387 karl 1.2 Array<Char16> _rep;
|
388 mike 1.1 };
389
|
390 karl 1.12 /** String operator ==. Test for equality between two strings of any of the
391 types String or char*.
392 @return Boolean - True if the strings are equal
393
394 */
|
395 mike 1.9 inline Boolean operator==(const String& x, const String& y)
396 {
397 return String::equal(x, y);
398 }
|
399 mike 1.1
|
400 karl 1.12 /** String operator ==. Test for equality between two strings
401
402 */
|
403 mike 1.9 inline Boolean operator==(const String& x, const char* y)
404 {
405 return String::equal(x, y);
406 }
|
407 mike 1.1
|
408 karl 1.12 /** String operator ==. Test for equality between two strings
409
410 */
|
411 mike 1.9 inline Boolean operator==(const char* x, const String& y)
412 {
413 return String::equal(x, y);
414 }
|
415 mike 1.1
|
416 karl 1.12 /** String operator ==. Test for equality between two strings
417
418 */
|
419 mike 1.1 inline Boolean operator!=(const String& x, const String& y)
420 {
|
421 mike 1.9 return !String::equal(x, y);
|
422 mike 1.1 }
423
|
424 mike 1.6 PEGASUS_COMMON_LINKAGE std::ostream& operator<<(
425 std::ostream& os,
426 const String& x);
|
427 mike 1.1
|
428 karl 1.12 /** overload operator + - Concatenates String objects.
429
430 <pre>
431 String t1 = "abc";
432 String t2;
433 t2 = t1 + "def"
434 assert(t2 == "abcdef");
435 </pre>
436 */
|
437 mike 1.1 inline String operator+(const String& x, const String& y)
438 {
439 return String(x).append(y);
440 }
|
441 mike 1.15
|
442 karl 1.12 /** overload operator < - Compares String obects.
443 <pre>
444 String t1 = "def";
445 String t2 = "a";
446 assert (t2 < t1);
447 </pre>
448 */
|
449 mike 1.1 inline Boolean operator<(const String& x, const String& y)
450 {
451 return String::compare(x.getData(), y.getData()) < 0;
452 }
|
453 mike 1.15
454 /** overload operator <= compares String objects.
|
455 mike 1.1
|
456 karl 1.12 */
|
457 mike 1.1 inline Boolean operator<=(const String& x, const String& y)
458 {
459 return String::compare(x.getData(), y.getData()) <= 0;
460 }
|
461 mike 1.15
|
462 karl 1.12 /** Overload operator > compares String objects
463 */
|
464 mike 1.1 inline Boolean operator>(const String& x, const String& y)
465 {
466 return String::compare(x.getData(), y.getData()) > 0;
467 }
|
468 mike 1.15
|
469 karl 1.12 /** overload operator >= - Compares String objects
470 */
|
471 mike 1.1 inline Boolean operator>=(const String& x, const String& y)
472 {
473 return String::compare(x.getData(), y.getData()) >= 0;
474 }
|
475 mike 1.6
476 /** Return a version of this string whose characters have been shifted
477 to lower case.
478 */
479 PEGASUS_COMMON_LINKAGE String ToLower(const String& str);
|
480 mike 1.15
481 /** Compare two strings but ignore any case differences.
482 */
483 PEGASUS_COMMON_LINKAGE int CompareIgnoreCase(const char* s1, const char* s2);
|
484 mike 1.16
485 /** Get the next line from the input file.
486 */
487 PEGASUS_COMMON_LINKAGE Boolean GetLine(std::istream& is, String& line);
|
488 mike 1.6
|
489 mike 1.17 /* This is an internal class not to be used by the internal Pegasus
490 components only. It provides an easy way to create an 8-bit string
491 representation on the fly without calling allocateCString() and
492 then worrying about deleting the string. The underscore before the
493 class name denotes that this class is internal, unsupported, undocumented,
494 and may be removed in future releases.
495 */
496 class _CString
497 {
498 public:
499
500 _CString(const String& x)
501 {
502 _rep = x.allocateCString();
503 }
504
505 _CString(const _CString& x)
506 {
507 _rep = strcpy(new char[strlen(x._rep) + 1], x._rep);
508 }
509
510 mike 1.17 ~_CString()
511 {
512 delete [] _rep;
513 }
514
515 _CString& operator=(const _CString& x)
516 {
517 if (this != &x)
518 _rep = strcpy(new char[strlen(x._rep) + 1], x._rep);
519
520 return *this;
521 }
522
523 operator const char*() const
524 {
525 return _rep;
526 }
527
528 const char* data() const
529 {
530 return _rep;
531 mike 1.17 }
532
533 private:
534
535 char* _rep;
536 };
|
537 mike 1.1
538 PEGASUS_NAMESPACE_END
539
540 #endif /* Pegasus_String_h */
|
Return to
String.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common