(file) Return to String.h CVS log (file) (dir) 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.76 const char STRING_FLAG_ASCII[] = "ASCII";
 50            const char STRING_FLAG_UTF8[]  = "UTF8";   
 51            
 52 mike  1.38 PEGASUS_NAMESPACE_BEGIN
 53            
 54 kumpf 1.59 class String;
 55 kumpf 1.51 class StringRep;
 56            
 57 kumpf 1.59 /** The CString class provides access to an 8-bit String representation.
 58            */
 59 kumpf 1.60 class PEGASUS_COMMON_LINKAGE CString
 60 kumpf 1.59 {
 61            public:
 62            
 63 karl  1.79     /** Constructs a CString object with null values (default constructor).
 64                */
 65 kumpf 1.59     CString();
 66            
 67 karl  1.79     /** REVIEWERS: Describe method here.
 68                @param cstr Specifies the name of the CString instance.
 69                */
 70 kumpf 1.59     CString(const CString& cstr);
 71            
 72 karl  1.79     /** CString destructor.
 73                */
 74 kumpf 1.59     ~CString();
 75            
 76 karl  1.79     /** Assigns the values of one CString instance to another.
 77                @param cstr Specifies the name of the CString instance whose values 
 78                are assigned to CString.
 79                */
 80 kumpf 1.62     CString& operator=(const CString& cstr);
 81            
 82 karl  1.79     /** REVIEWERS: Describe constructor here.
 83                */
 84 kumpf 1.59     operator const char*() const;
 85            
 86            private:
 87            
 88                CString(char* cstr);
 89            
 90                friend class String;
 91            
 92 kumpf 1.64     void* _rep;
 93 kumpf 1.59 };
 94            
 95 mike  1.38 /**
 96                The Pegasus String C++ Class implements the CIM string type.
 97 karl  1.79     REVIEWERS: We need more definition here.
 98 mike  1.38 */
 99            class PEGASUS_COMMON_LINKAGE String
100            {
101            public:
102            
103 kumpf 1.74     /**	This member is used to represent an empty string. Using this 
104 karl  1.79         member avoids construction of an empty string (for example, String()).
105 kumpf 1.48     */
106                static const String EMPTY;
107            
108 mike  1.38     /** Default constructor without parameters. This constructor creates a
109 karl  1.79 	null string. For example, 
110 mike  1.38 	<pre>
111            	    String test;
112            	</pre>
113                */
114                String();
115            
116 karl  1.79     /** Copy constructor.
117                @param str Specifies the name of the String instance.
118                */
119 kumpf 1.48     String(const String& str);
120 mike  1.38 
121 karl  1.79     /** Initialize with first n characters from str.
122                @param str Specifies the name of the String instance.
123                @param n Specifies the Uint32 size to use for the length of the string object.
124                */
125 kumpf 1.48     String(const String& str, Uint32 n);
126 mike  1.38 
127 karl  1.79     /** Initialize with str.
128                @param str Specifies the name of the String instance.
129                */
130 kumpf 1.48     String(const Char16* str);
131 mike  1.38 
132 karl  1.79     /** Initialize with first n characters of str.
133                @param str Specifies the name of the String instance.
134                @param n Specifies the Uint32 size.
135                */
136 kumpf 1.48     String(const Char16* str, Uint32 n);
137 mike  1.38 
138 karl  1.79     /** Initialize from a plain C-String:
139                @param str Specifies the name of the String instance.
140                */
141 kumpf 1.48     String(const char* str);
142 mike  1.38 
143 chuck 1.77 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
144 karl  1.79     /** Initialize from a plain C-String that allows UTF-8:
145                @param str Specifies the name of the String instance.
146                @param utfFlag Specifies the name of the character constructor.
147                */
148 chuck 1.77     String(const char* str, const char* utfFlag);
149            #endif
150            
151 karl  1.79     /** Initialize from the first n characters of a plain C-String:
152                @param str Specifies the name of the String instance.
153                @param u Specifies the Uint32 size.
154                */
155 kumpf 1.48     String(const char* str, Uint32 n);
156 mike  1.38 
157 karl  1.79     /** String destructor. 
158                */
159 mike  1.38     ~String();
160            
161 karl  1.79     /** Assign this string with str. For example,
162 mike  1.38 	<pre>
163            	    String t1 = "abc";
164            	    String t2 = t1;
165            	</pre>
166 karl  1.79 	String t2 is assigned the value of t1.
167                    @param str Specifies the name of the String to assign to another 
168                    String instance.
169 mike  1.38     */
170 kumpf 1.48     String& operator=(const String& str);
171 mike  1.38 
172 kumpf 1.74     /** Assign this string with String str.
173                    @param str String to assign.
174                    @return Returns the String.
175 mike  1.38     */
176 kumpf 1.48     String& assign(const String& str);
177 mike  1.38 
178 karl  1.79     /** Assign this string with str.
179                */
180 kumpf 1.48     String& assign(const Char16* str);
181 mike  1.38 
182 karl  1.79     /** Assign this string with first n characters of str.
183                @param n REVIEWERS: Insert text here.
184                @param str REVIEWERS: Insert text here.
185                */
186 kumpf 1.48     String& assign(const Char16* str, Uint32 n);
187 mike  1.38 
188 karl  1.79     /** Assign this string with the plain C-String str.
189                @param str REVIEWERS: Insert text here.
190                */
191 kumpf 1.48     String& assign(const char* str);
192 mike  1.38 
193 karl  1.79     /** Assign this string with first n characters of the plain C-String str.
194                @param str REVIEWERS: Insert text here.
195                @param n REVIEWERS: Insert text here.
196                */
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                    @return CString object that provides access to the 8-bit 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 karl  1.79     /** Converts all characters in this string to lowercase characters.
372 mike  1.38     */
373                void toLower();
374 kumpf 1.48 
375 karl  1.79     /** Compare the first n characters of the two strings.
376 mike  1.38     	@param s1 First null-terminated string for the comparison.
377            	@param s2 Second null-terminated string for the comparison.
378            	@param n Number of characters to compare.
379 karl  1.79 	@return Return -1 If s1 is lexographically less than s2; if they are
380            	equivalent return 0; otherwise return 1.
381 mike  1.38     */
382 kumpf 1.51     static int compare(const String& s1, const String& s2, Uint32 n);
383 mike  1.38 
384                /** Compare two null-terminated strings.
385                	@param s1 First null-terminated string for the comparison.
386            	@param s2 Second null-terminated string for the comparison.
387 kumpf 1.74 	@return Return -1 if s1 is less than s2; if equal return 0;
388            	otherwise return 1.
389 mike  1.38 
390            	NOTE: Use the comparison operators <,<= > >= to compare
391            	String objects.
392                */
393 kumpf 1.51     static int compare(const String& s1, const String& s2);
394 mike  1.38 
395 karl  1.79     /** Compare two null-terminated strings but ignore case.
396                    @param s1 First null-terminated string for the comparison.
397            	@param s2 Second null-terminated string for the comparison.
398            	@return Return -1 if s1 is less than s2; if equal return 0;
399            	otherwise return 1.
400            
401            	NOTE: Use the comparison operators <,<= > >= to compare
402            	String objects.
403 kumpf 1.48     */
404 kumpf 1.49     static int compareNoCase(const String& s1, const String& s2);
405 kumpf 1.48 
406 mike  1.38     /** Compare two String objects for equality.
407            	@param s1 First <TT>String</TT> for comparison.
408            	@param s2 Second <TT>String</TT> for comparison.
409            
410 karl  1.79 	@return true If the two strings are equal; otherwise, false. For example, 
411 mike  1.38 	<pre>
412            	    String s1 = "Hello World";
413            	    String s2 = s1;
414            	    String s3(s2);
415            	    assert(String::equal(s1, s3));
416            	</pre>
417                */
418 kumpf 1.48     static Boolean equal(const String& str1, const String& str2);
419 mike  1.38 
420 kumpf 1.74     /** Compares two strings and returns true if they
421            	are equal indepedent of case of the characters.
422            	@param str1 First String parameter.
423            	@param str2 Second String parameter.
424 karl  1.79 	@return true If strings are equal independent of case, flase
425 kumpf 1.74         otherwise.
426 karl  1.47     */
427 kumpf 1.48     static Boolean equalNoCase(const String& str1, const String& str2);
428 david 1.76 
429 chuck 1.77 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
430 david 1.76     // UTF8 specific code:
431 chuck 1.77 
432                /** Assign this string with a C string that may contain UTF-8.
433            	@param str The C string
434                */
435 david 1.76     String& assignUTF8(const char* str);
436 chuck 1.77 
437                /** Create an 8-bit UTF-8 representation of this String object.
438                    @return CString object that provides access to the 8-bit UTF-8 String
439                    representation.
440                */
441 david 1.76     CString getCStringUTF8() const;
442 chuck 1.77 
443                /** Tests whether a C string contains valid UTF-8 characters.
444            	@param str The C string
445                */
446 david 1.76     static Boolean isUTF8(const char*);
447 chuck 1.77 #endif
448 mike  1.38 
449            private:
450            
451 kumpf 1.51     StringRep* _rep;
452 mike  1.38 };
453 mike  1.40 
454 karl  1.79 /** String operator == tests for equality between two strings of any of the
455 mike  1.38     types String or char*.
456 karl  1.79     @return true If the strings are equal; otherwise, false.
457                @param str1 REVIEWERS: Insert description here.
458                @param str2 REVIEWERS: Insert description here.
459 mike  1.38 */
460 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(
461                const String& str1,
462                const String& str2);
463 mike  1.38 
464 kumpf 1.74 /** String operator ==. Test for equality between two strings.
465 karl  1.79     @param str1 REVIEWERS: Insert description here.
466                @param str2 REVIEWERS: Insert description here.
467 mike  1.38 */
468 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const String& str1, const char* str2);
469 mike  1.38 
470 kumpf 1.74 /** String operator ==. Test for equality between two strings.
471 karl  1.79     @param str1 REVIEWERS: Insert description here.
472                @param str2 REVIEWERS: Insert description here.
473 mike  1.38 */
474 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator==(const char* str1, const String& str2);
475 mike  1.38 
476 kumpf 1.74 /** String operator ==. Test for equality between two strings.
477 karl  1.79     @param str1 REVIEWERS: Insert description here.
478                @param str2 REVIEWERS: Insert description here.
479 mike  1.38 */
480 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator!=(
481                const String& str1,
482                const String& str2);
483 mike  1.38 
484 karl  1.79 /** REVIEWERS: Insert description here.
485                @param str REVIEWERS: Insert description here.
486                @param os REVIEWERS: Insert description here.
487            */
488 mike  1.38 PEGASUS_COMMON_LINKAGE PEGASUS_STD(ostream)& operator<<(
489                PEGASUS_STD(ostream)& os,
490 kumpf 1.48     const String& str);
491 mike  1.38 
492 karl  1.79 /** This overload operator (+) concatenates String objects. For example, 
493 mike  1.38     <pre>
494            	String t1 = "abc";
495            	String t2;
496            	t2 = t1 + "def"
497            	assert(t2 == "abcdef");
498                </pre>
499            */
500 kumpf 1.48 PEGASUS_COMMON_LINKAGE String operator+(const String& str1, const String& str2);
501 mike  1.38 
502 karl  1.79 /** The overload operator (<) compares String obects.
503 mike  1.38     <pre>
504            	String t1 = "def";
505            	String t2 = "a";
506            	assert (t2 < t1);
507                </pre>
508 karl  1.79     @param str1 REVIEWERS: Insert description here.
509                @param str2 REVIEWERS: Insert description here.
510 mike  1.38 */
511 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<(
512                const String& str1,
513                const String& str2);
514 mike  1.38 
515 karl  1.79 /** The overload operator (<=) compares String objects.
516                @param str1 REVIEWERS: Insert description here.
517                @param str2 REVIEWERS: Insert description here.
518 mike  1.38 */
519 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator<=(
520                const String& str1,
521                const String& str2);
522 mike  1.38 
523 karl  1.79 /** The overload operator (>) compares String objects.
524                @param str1 REVIEWERS: Insert description here.
525                @param str2 REVIEWERS: Insert description here.
526 mike  1.38 */
527 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>(
528                const String& str1,
529                const String& str2);
530 mike  1.38 
531 karl  1.79 /** The overload operator (>=) compares String objects.
532                @param str1 REVIEWERS: Insert description here.
533                @param str2 REVIEWERS: Insert description here.
534 mike  1.38 */
535 kumpf 1.48 PEGASUS_COMMON_LINKAGE Boolean operator>=(
536                const String& str1,
537                const String& str2);
538 mike  1.38 
539 kumpf 1.80 #ifdef PEGASUS_USE_DEPRECATED_INTERFACES
540 karl  1.79 /** Compares two strings but ignores any case differences.
541                @param s1 REVIEWERS: Insert description here.
542                @param s2 REVIEWERS: Insert description here.
543 mike  1.38 */
544            PEGASUS_COMMON_LINKAGE int CompareNoCase(const char* s1, const char* s2);
545 kumpf 1.65 #endif
546 mike  1.41 
547 mike  1.38 PEGASUS_NAMESPACE_END
548            
549            #endif /* Pegasus_String_h */

No CVS admin address has been configured
Powered by
ViewCVS 0.9.2