xref: /aoo42x/main/sal/inc/rtl/string.hxx (revision b8bbe16f)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_STRING_HXX_
25 #define _RTL_STRING_HXX_
26 
27 #ifdef __cplusplus
28 
29 #ifndef _RTL_DIAGNOSE_H_
30 #include <osl/diagnose.h>
31 #endif
32 #include <rtl/memory.h>
33 #include <rtl/textenc.h>
34 #include <rtl/string.h>
35 #ifdef DBG_UTIL
36 #include <tools/debug.hxx>
37 #endif /* DBG_UTIL */
38 
39 #if !defined EXCEPTIONS_OFF
40 #include <new>
41 #endif
42 
43 namespace rtl
44 {
45 
46 /* ======================================================================= */
47 
48 /**
49   This String class provide base functionality for C++ like 8-Bit
50   character array handling. The advantage of this class is, that it
51   handle all the memory managament for you - and it do it
52   more efficient. If you assign a string to another string, the
53   data of both strings are shared (without any copy operation or
54   memory allocation) as long as you do not change the string. This class
55   stores also the length of the string, so that many operations are
56   faster as the C-str-functions.
57 
58   This class provide only readonly string handling. So you could create
59   a string and you could only query the content from this string.
60   It provide also functionality to change the string, but this results
61   in every case in a new string instance (in the most cases with an
62   memory allocation). You don't have functionality to change the
63   content of the string. If you want change the string content, than
64   you should us the OStringBuffer class, which provide these
65   functionality and avoid to much memory allocation.
66 
67   The design of this class is similar to the string classes in Java
68   and so more people should have fewer understanding problems when they
69   use this class.
70 */
71 
72 class OString
73 {
74 public:
75     /** @internal */
76     rtl_String * pData;
77 
78 private:
79     /** @internal */
80     class DO_NOT_ACQUIRE;
81 
82     /** @internal */
OString(rtl_String * value,DO_NOT_ACQUIRE *)83     OString( rtl_String * value, DO_NOT_ACQUIRE * )
84     {
85         pData = value;
86     }
87 
88 public:
89     /**
90       New string containing no characters.
91     */
92     OString() SAL_THROW(())
93     {
94         pData = 0;
95         rtl_string_new( &pData );
96     }
97 
98     /**
99       New string from OString.
100 
101       @param    str         a OString.
102     */
103     OString( const OString & str ) SAL_THROW(())
104     {
105         pData = str.pData;
106         rtl_string_acquire( pData );
107     }
108 
109     /**
110       New string from OString data.
111 
112       @param    str         a OString data.
113     */
114     OString( rtl_String * str ) SAL_THROW(())
115     {
116         pData = str;
117         rtl_string_acquire( pData );
118     }
119 
120     /**
121       New string from a single character.
122 
123       @param    value       a character.
124     */
125     explicit OString( sal_Char value ) SAL_THROW(())
126         : pData (0)
127     {
128         rtl_string_newFromStr_WithLength( &pData, &value, 1 );
129     }
130 
131     /**
132       New string from a character buffer array.
133 
134       @param    value       a NULL-terminated character array.
135     */
136     OString( const sal_Char * value ) SAL_THROW(())
137     {
138         pData = 0;
139         rtl_string_newFromStr( &pData, value );
140     }
141 
142     /**
143       New string from a character buffer array.
144 
145       @param    value       a character array.
146       @param    length      the number of character which should be copied.
147                             The character array length must be greater or
148                             equal than this value.
149     */
OString(const sal_Char * value,sal_Int32 length)150     OString( const sal_Char * value, sal_Int32 length ) SAL_THROW(())
151     {
152         pData = 0;
153         rtl_string_newFromStr_WithLength( &pData, value, length );
154     }
155 
156     /**
157       New string from a Unicode character buffer array.
158 
159       @param    value           a Unicode character array.
160       @param    length          the number of character which should be converted.
161                                 The Unicode character array length must be
162                                 greater or equal than this value.
163       @param    encoding        the text encoding in which the Unicode character
164                                 sequence should be converted.
165       @param    convertFlags    flags which controls the conversion.
166                                 see RTL_UNICODETOTEXT_FLAGS_...
167 
168       @exception std::bad_alloc is thrown if an out-of-memory condition occurs
169     */
OString(const sal_Unicode * value,sal_Int32 length,rtl_TextEncoding encoding,sal_uInt32 convertFlags=OUSTRING_TO_OSTRING_CVTFLAGS)170     OString( const sal_Unicode * value, sal_Int32 length,
171              rtl_TextEncoding encoding,
172              sal_uInt32 convertFlags = OUSTRING_TO_OSTRING_CVTFLAGS )
173     {
174         pData = 0;
175         rtl_uString2String( &pData, value, length, encoding, convertFlags );
176 #if defined EXCEPTIONS_OFF
177         OSL_ASSERT(pData != NULL);
178 #else
179         if (pData == 0) {
180             throw std::bad_alloc();
181         }
182 #endif
183     }
184 
185     /**
186       Release the string data.
187     */
188     ~OString() SAL_THROW(())
189     {
190         rtl_string_release( pData );
191     }
192 
193     /**
194       Assign a new string.
195 
196       @param    str         a OString.
197     */
operator =(const OString & str)198     OString & operator=( const OString & str ) SAL_THROW(())
199     {
200         rtl_string_assign( &pData, str.pData );
201         return *this;
202     }
203 
204     /**
205       Append a string to this string.
206 
207       @param    str         a OString.
208     */
operator +=(const OString & str)209     OString & operator+=( const OString & str ) SAL_THROW(())
210     {
211         rtl_string_newConcat( &pData, pData, str.pData );
212         return *this;
213     }
214 
215     /**
216       Returns the length of this string.
217 
218       The length is equal to the number of characters in this string.
219 
220       @return   the length of the sequence of characters represented by this
221                 object.
222     */
getLength() const223     sal_Int32 getLength() const SAL_THROW(()) { return pData->length; }
224 
225 private:
226     /**
227       Returns a pointer to the characters of this string.
228 
229       NOTE: the implicit cast to a char pointer is obsolete
230             because it is too dangerous #i123068#
231 
232       <p>The returned pointer is not guaranteed to point to a null-terminated
233       byte string.  Note that this string object may contain embedded null
234       characters, which will thus also be embedded in the returned byte
235       string.</p>
236 
237       @return a pointer to a (not necessarily null-terminated) byte string
238       representing the characters of this string object.
239     */
240 
241 public:
242     operator const sal_Char *() const SAL_THROW(()) { return pData->buffer; }
243     /** Returns a reference to a character of this string. */
operator [](int n)244     sal_Char& operator[]( int n ) { return pData->buffer[n]; }
245     /** Returns a const reference to a character of this string. */
operator [](int n) const246     const sal_Char& operator[]( int n ) const { return pData->buffer[n]; }
247     /** Returns a bool indicating whether this string is empty. */
isEmpty() const248     bool isEmpty() const { return (pData->length == 0); }
249 
250     /**
251       Returns a pointer to the characters of this string.
252 
253       <p>The returned pointer is guaranteed to point to a null-terminated byte
254       string.  But note that this string object may contain embedded null
255       characters, which will thus also be embedded in the returned
256       null-terminated byte string.</p>
257 
258       @return a pointer to a null-terminated byte string representing the
259       characters of this string object.
260     */
getStr() const261     const sal_Char * getStr() const SAL_THROW(()) { return pData->buffer; }
262 
263     /**
264       Compares two strings.
265 
266       The comparison is based on the numeric value of each character in
267       the strings and return a value indicating their relationship.
268       This function can't be used for language specific sorting.
269 
270       @param    str         the object to be compared.
271       @return   0 - if both strings are equal
272                 < 0 - if this string is less than the string argument
273                 > 0 - if this string is greater than the string argument
274     */
compareTo(const OString & str) const275     sal_Int32 compareTo( const OString & str ) const SAL_THROW(())
276     {
277         return rtl_str_compare_WithLength( pData->buffer, pData->length,
278                                            str.pData->buffer, str.pData->length );
279     }
280 
281     /**
282       Compares two strings with an maximum count of characters.
283 
284       The comparison is based on the numeric value of each character in
285       the strings and return a value indicating their relationship.
286       This function can't be used for language specific sorting.
287 
288       @param    str         the object to be compared.
289       @param    maxLength   the maximum count of characters to be compared.
290       @return   0 - if both strings are equal
291                 < 0 - if this string is less than the string argument
292                 > 0 - if this string is greater than the string argument
293     */
compareTo(const OString & rObj,sal_Int32 maxLength) const294     sal_Int32 compareTo( const OString & rObj, sal_Int32 maxLength ) const SAL_THROW(())
295     {
296         return rtl_str_shortenedCompare_WithLength( pData->buffer, pData->length,
297                                                     rObj.pData->buffer, rObj.pData->length, maxLength );
298     }
299 
300     /**
301       Compares two strings in reverse order.
302 
303       The comparison is based on the numeric value of each character in
304       the strings and return a value indicating their relationship.
305       This function can't be used for language specific sorting.
306 
307       @param    str         the object to be compared.
308       @return   0 - if both strings are equal
309                 < 0 - if this string is less than the string argument
310                 > 0 - if this string is greater than the string argument
311     */
reverseCompareTo(const OString & str) const312     sal_Int32 reverseCompareTo( const OString & str ) const SAL_THROW(())
313     {
314         return rtl_str_reverseCompare_WithLength( pData->buffer, pData->length,
315                                                   str.pData->buffer, str.pData->length );
316     }
317 
318     /**
319       Perform a comparison of two strings.
320 
321       The result is true if and only if second string
322       represents the same sequence of characters as the first string.
323       This function can't be used for language specific comparison.
324 
325       @param    str         the object to be compared.
326       @return   sal_True if the strings are equal;
327                 sal_False, otherwise.
328     */
equals(const OString & str) const329     sal_Bool equals( const OString & str ) const SAL_THROW(())
330     {
331         if ( pData->length != str.pData->length )
332             return sal_False;
333         if ( pData == str.pData )
334             return sal_True;
335         return rtl_str_reverseCompare_WithLength( pData->buffer, pData->length,
336                                                   str.pData->buffer, str.pData->length ) == 0;
337     }
338 
339     /**
340       Perform a ASCII lowercase comparison of two strings.
341 
342       The result is true if and only if second string
343       represents the same sequence of characters as the first string,
344       ignoring the case.
345       Character values between 65 and 90 (ASCII A-Z) are interpreted as
346       values between 97 and 122 (ASCII a-z).
347       This function can't be used for language specific comparison.
348 
349       @param    str         the object to be compared.
350       @return   sal_True if the strings are equal;
351                 sal_False, otherwise.
352     */
equalsIgnoreAsciiCase(const OString & str) const353     sal_Bool equalsIgnoreAsciiCase( const OString & str ) const SAL_THROW(())
354     {
355         if ( pData->length != str.pData->length )
356             return sal_False;
357         if ( pData == str.pData )
358             return sal_True;
359         return rtl_str_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
360                                                           str.pData->buffer, str.pData->length ) == 0;
361     }
362 
363     /**
364       Match against a substring appearing in this string.
365 
366       The result is true if and only if the second string appears as a substring
367       of this string, at the given position.
368       This function can't be used for language specific comparison.
369 
370       @param    str         the object (substring) to be compared.
371       @param    fromIndex   the index to start the comparion from.
372                             The index must be greater or equal than 0
373                             and less or equal as the string length.
374       @return   sal_True if str match with the characters in the string
375                 at the given position;
376                 sal_False, otherwise.
377     */
match(const OString & str,sal_Int32 fromIndex=0) const378     sal_Bool match( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
379     {
380         return rtl_str_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
381                                                     str.pData->buffer, str.pData->length, str.pData->length ) == 0;
382     }
383 
384     /**
385       Match against a substring appearing in this string, ignoring the case of
386       ASCII letters.
387 
388       The result is true if and only if the second string appears as a substring
389       of this string, at the given position.
390       Character values between 65 and 90 (ASCII A-Z) are interpreted as
391       values between 97 and 122 (ASCII a-z).
392       This function can't be used for language specific comparison.
393 
394       @param    str         the object (substring) to be compared.
395       @param    fromIndex   the index to start the comparion from.
396                             The index must be greater or equal than 0
397                             and less or equal as the string length.
398       @return   sal_True if str match with the characters in the string
399                 at the given position;
400                 sal_False, otherwise.
401     */
matchIgnoreAsciiCase(const OString & str,sal_Int32 fromIndex=0) const402     sal_Bool matchIgnoreAsciiCase( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
403     {
404         return rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
405                                                                    str.pData->buffer, str.pData->length,
406                                                                    str.pData->length ) == 0;
407     }
408 
operator ==(const OString & rStr1,const OString & rStr2)409     friend sal_Bool     operator == ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
410                         { return rStr1.getLength() == rStr2.getLength() && rStr1.compareTo( rStr2 ) == 0; }
operator ==(const OString & rStr1,const sal_Char * pStr2)411     friend sal_Bool     operator == ( const OString& rStr1, const sal_Char * pStr2 ) SAL_THROW(())
412                         { return rStr1.compareTo( pStr2 ) == 0; }
operator ==(const sal_Char * pStr1,const OString & rStr2)413     friend sal_Bool     operator == ( const sal_Char * pStr1,   const OString& rStr2 ) SAL_THROW(())
414                         { return OString( pStr1 ).compareTo( rStr2 ) == 0; }
415 
operator !=(const OString & rStr1,const OString & rStr2)416     friend sal_Bool     operator != ( const OString& rStr1,     const OString& rStr2 ) SAL_THROW(())
417                         { return !(operator == ( rStr1, rStr2 )); }
operator !=(const OString & rStr1,const sal_Char * pStr2)418     friend sal_Bool     operator != ( const OString& rStr1, const sal_Char * pStr2 ) SAL_THROW(())
419                         { return !(operator == ( rStr1, pStr2 )); }
operator !=(const sal_Char * pStr1,const OString & rStr2)420     friend sal_Bool     operator != ( const sal_Char * pStr1,   const OString& rStr2 ) SAL_THROW(())
421                         { return !(operator == ( pStr1, rStr2 )); }
422 
operator <(const OString & rStr1,const OString & rStr2)423     friend sal_Bool     operator <  ( const OString& rStr1,    const OString& rStr2 ) SAL_THROW(())
424                         { return rStr1.compareTo( rStr2 ) < 0; }
operator >(const OString & rStr1,const OString & rStr2)425     friend sal_Bool     operator >  ( const OString& rStr1,    const OString& rStr2 ) SAL_THROW(())
426                         { return rStr1.compareTo( rStr2 ) > 0; }
operator <=(const OString & rStr1,const OString & rStr2)427     friend sal_Bool     operator <= ( const OString& rStr1,    const OString& rStr2 ) SAL_THROW(())
428                         { return rStr1.compareTo( rStr2 ) <= 0; }
operator >=(const OString & rStr1,const OString & rStr2)429     friend sal_Bool     operator >= ( const OString& rStr1,    const OString& rStr2 ) SAL_THROW(())
430                         { return rStr1.compareTo( rStr2 ) >= 0; }
431 
432     /**
433       Returns a hashcode for this string.
434 
435       @return   a hash code value for this object.
436 
437       @see rtl::OStringHash for convenient use of hash_map / unordered_map
438     */
hashCode() const439     sal_Int32 hashCode() const SAL_THROW(())
440     {
441         return rtl_str_hashCode_WithLength( pData->buffer, pData->length );
442     }
443 
444     /**
445       Returns the index within this string of the first occurrence of the
446       specified character, starting the search at the specified index.
447 
448       @param    ch          character to be located.
449       @param    fromIndex   the index to start the search from.
450                             The index must be greater or equal than 0
451                             and less or equal as the string length.
452       @return   the index of the first occurrence of the character in the
453                 character sequence represented by this string that is
454                 greater than or equal to fromIndex, or
455                 -1 if the character does not occur.
456     */
indexOf(sal_Char ch,sal_Int32 fromIndex=0) const457     sal_Int32 indexOf( sal_Char ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
458     {
459         sal_Int32 ret = rtl_str_indexOfChar_WithLength( pData->buffer+fromIndex, pData->length-fromIndex, ch );
460         return (ret < 0 ? ret : ret+fromIndex);
461     }
462 
463     /**
464       Returns the index within this string of the last occurrence of the
465       specified character, searching backward starting at the end.
466 
467       @param    ch          character to be located.
468       @return   the index of the last occurrence of the character in the
469                 character sequence represented by this string, or
470                 -1 if the character does not occur.
471     */
lastIndexOf(sal_Char ch) const472     sal_Int32 lastIndexOf( sal_Char ch ) const SAL_THROW(())
473     {
474         return rtl_str_lastIndexOfChar_WithLength( pData->buffer, pData->length, ch );
475     }
476 
477     /**
478       Returns the index within this string of the last occurrence of the
479       specified character, searching backward starting before the specified
480       index.
481 
482       @param    ch          character to be located.
483       @param    fromIndex   the index before which to start the search.
484       @return   the index of the last occurrence of the character in the
485                 character sequence represented by this string that
486                 is less than fromIndex, or -1
487                 if the character does not occur before that point.
488     */
lastIndexOf(sal_Char ch,sal_Int32 fromIndex) const489     sal_Int32 lastIndexOf( sal_Char ch, sal_Int32 fromIndex ) const SAL_THROW(())
490     {
491         return rtl_str_lastIndexOfChar_WithLength( pData->buffer, fromIndex, ch );
492     }
493 
494     /**
495       Returns the index within this string of the first occurrence of the
496       specified substring, starting at the specified index.
497 
498       If str doesn't include any character, always -1 is
499       returned. This is also the case, if both strings are empty.
500 
501       @param    str         the substring to search for.
502       @param    fromIndex   the index to start the search from.
503       @return   If the string argument occurs one or more times as a substring
504                 within this string at the starting index, then the index
505                 of the first character of the first such substring is
506                 returned. If it does not occur as a substring starting
507                 at fromIndex or beyond, -1 is returned.
508     */
indexOf(const OString & str,sal_Int32 fromIndex=0) const509     sal_Int32 indexOf( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
510     {
511         sal_Int32 ret = rtl_str_indexOfStr_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
512                                                        str.pData->buffer, str.pData->length );
513         return (ret < 0 ? ret : ret+fromIndex);
514     }
515 
516     /**
517       Returns the index within this string of the last occurrence of
518       the specified substring, searching backward starting at the end.
519 
520       The returned index indicates the starting index of the substring
521       in this string.
522       If str doesn't include any character, always -1 is
523       returned. This is also the case, if both strings are empty.
524 
525       @param    str         the substring to search for.
526       @return   If the string argument occurs one or more times as a substring
527                 within this string, then the index of the first character of
528                 the last such substring is returned. If it does not occur as
529                 a substring, -1 is returned.
530     */
lastIndexOf(const OString & str) const531     sal_Int32 lastIndexOf( const OString & str ) const SAL_THROW(())
532     {
533         return rtl_str_lastIndexOfStr_WithLength( pData->buffer, pData->length,
534                                                   str.pData->buffer, str.pData->length );
535     }
536 
537     /**
538       Returns the index within this string of the last occurrence of
539       the specified substring, searching backward starting before the specified
540       index.
541 
542       The returned index indicates the starting index of the substring
543       in this string.
544       If str doesn't include any character, always -1 is
545       returned. This is also the case, if both strings are empty.
546 
547       @param    str         the substring to search for.
548       @param    fromIndex   the index before which to start the search.
549       @return   If the string argument occurs one or more times as a substring
550                 within this string before the starting index, then the index
551                 of the first character of the last such substring is
552                 returned. Otherwise, -1 is returned.
553     */
lastIndexOf(const OString & str,sal_Int32 fromIndex) const554     sal_Int32 lastIndexOf( const OString & str, sal_Int32 fromIndex ) const SAL_THROW(())
555     {
556         return rtl_str_lastIndexOfStr_WithLength( pData->buffer, fromIndex,
557                                                   str.pData->buffer, str.pData->length );
558     }
559 
560     /**
561       Returns a new string that is a substring of this string.
562 
563       The substring begins at the specified beginIndex.  It is an error for
564       beginIndex to be negative or to be greater than the length of this string.
565 
566       @param     beginIndex   the beginning index, inclusive.
567       @return    the specified substring.
568     */
copy(sal_Int32 beginIndex) const569     OString copy( sal_Int32 beginIndex ) const SAL_THROW(())
570     {
571         OSL_ASSERT(beginIndex >= 0 && beginIndex <= getLength());
572         if ( beginIndex == 0 )
573             return *this;
574         else
575         {
576             rtl_String* pNew = 0;
577             rtl_string_newFromStr_WithLength( &pNew, pData->buffer+beginIndex, getLength()-beginIndex );
578             return OString( pNew, (DO_NOT_ACQUIRE*)0 );
579         }
580     }
581 
582     /**
583       Returns a new string that is a substring of this string.
584 
585       The substring begins at the specified beginIndex and contains count
586       characters.  It is an error for either beginIndex or count to be negative,
587       or for beginIndex + count to be greater than the length of this string.
588 
589       @param     beginIndex   the beginning index, inclusive.
590       @param     count        the number of characters.
591       @return    the specified substring.
592     */
copy(sal_Int32 beginIndex,sal_Int32 count) const593     OString copy( sal_Int32 beginIndex, sal_Int32 count ) const SAL_THROW(())
594     {
595         OSL_ASSERT(beginIndex >= 0 && beginIndex <= getLength()
596                    && count >= 0 && count <= getLength() - beginIndex);
597         if ( (beginIndex == 0) && (count == getLength()) )
598             return *this;
599         else
600         {
601             rtl_String* pNew = 0;
602             rtl_string_newFromStr_WithLength( &pNew, pData->buffer+beginIndex, count );
603             return OString( pNew, (DO_NOT_ACQUIRE*)0 );
604         }
605     }
606 
607     /**
608       Concatenates the specified string to the end of this string.
609 
610       @param    str   the string that is concatenated to the end
611                       of this string.
612       @return   a string that represents the concatenation of this string
613                 followed by the string argument.
614     */
concat(const OString & str) const615     OString concat( const OString & str ) const SAL_THROW(())
616     {
617         rtl_String* pNew = 0;
618         rtl_string_newConcat( &pNew, pData, str.pData );
619         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
620     }
621 
operator +(const OString & str1,const OString & str2)622     friend OString operator+( const OString & str1, const OString & str2  ) SAL_THROW(())
623     {
624         return str1.concat( str2 );
625     }
626 
627     /**
628       Returns a new string resulting from replacing n = count characters
629       from position index in this string with newStr.
630 
631       @param  index   the replacing index in str.
632                       The index must be greater or equal as 0 and
633                       less or equal as the length of the string.
634       @param  count   the count of charcters that will replaced
635                       The count must be greater or equal as 0 and
636                       less or equal as the length of the string minus index.
637       @param  newStr  the new substring.
638       @return the new string.
639     */
replaceAt(sal_Int32 index,sal_Int32 count,const OString & newStr) const640     OString replaceAt( sal_Int32 index, sal_Int32 count, const OString& newStr ) const SAL_THROW(())
641     {
642         rtl_String* pNew = 0;
643         rtl_string_newReplaceStrAt( &pNew, pData, index, count, newStr.pData );
644         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
645     }
646 
647     /**
648       Returns a new string resulting from replacing all occurrences of
649       oldChar in this string with newChar.
650 
651       If the character oldChar does not occur in the character sequence
652       represented by this object, then the string is assigned with
653       str.
654 
655       @param    oldChar     the old character.
656       @param    newChar     the new character.
657       @return   a string derived from this string by replacing every
658                 occurrence of oldChar with newChar.
659     */
replace(sal_Char oldChar,sal_Char newChar) const660     OString replace( sal_Char oldChar, sal_Char newChar ) const SAL_THROW(())
661     {
662         rtl_String* pNew = 0;
663         rtl_string_newReplace( &pNew, pData, oldChar, newChar );
664         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
665     }
666 
667     /**
668       Converts from this string all ASCII uppercase characters (65-90)
669       to ASCII lowercase characters (97-122).
670 
671       This function can't be used for language specific conversion.
672       If the string doesn't contain characters which must be converted,
673       then the new string is assigned with str.
674 
675       @return   the string, converted to ASCII lowercase.
676     */
toAsciiLowerCase() const677     OString toAsciiLowerCase() const SAL_THROW(())
678     {
679         rtl_String* pNew = 0;
680         rtl_string_newToAsciiLowerCase( &pNew, pData );
681         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
682     }
683 
684     /**
685       Converts from this string all ASCII lowercase characters (97-122)
686       to ASCII uppercase characters (65-90).
687 
688       This function can't be used for language specific conversion.
689       If the string doesn't contain characters which must be converted,
690       then the new string is assigned with str.
691 
692       @return   the string, converted to ASCII uppercase.
693     */
toAsciiUpperCase() const694     OString toAsciiUpperCase() const SAL_THROW(())
695     {
696         rtl_String* pNew = 0;
697         rtl_string_newToAsciiUpperCase( &pNew, pData );
698         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
699     }
700 
701     /**
702       Returns a new string resulting from removing white space from both ends
703       of the string.
704 
705       All characters that have codes less than or equal to
706       32 (the space character) are considered to be white space.
707       If the string doesn't contain white spaces at both ends,
708       then the new string is assigned with str.
709 
710       @return   the string, with white space removed from the front and end.
711     */
trim() const712     OString trim() const SAL_THROW(())
713     {
714         rtl_String* pNew = 0;
715         rtl_string_newTrim( &pNew, pData );
716         return OString( pNew, (DO_NOT_ACQUIRE*)0 );
717     }
718 
719     /**
720       Returns a token in the string.
721 
722       Example:
723         sal_Int32 nIndex = 0;
724         do
725         {
726             ...
727             OString aToken = aStr.getToken( 0, ';', nIndex );
728             ...
729         }
730         while ( nIndex >= 0 );
731 
732       @param    token       the number of the token to return.
733       @param    cTok        the character which separate the tokens.
734       @param    index       the position at which the token is searched in the
735                             string.
736                             The index must not be greater thanthe length of the
737                             string.
738                             This param is set to the position of the
739                             next token or to -1, if it is the last token.
740       @return   the token; if either token or index is negative, an empty token
741                 is returned (and index is set to -1)
742     */
getToken(sal_Int32 token,sal_Char cTok,sal_Int32 & index) const743     OString getToken( sal_Int32 token, sal_Char cTok, sal_Int32& index ) const SAL_THROW(())
744     {
745         rtl_String * pNew = 0;
746         index = rtl_string_getToken( &pNew, pData, token, cTok, index );
747         return OString( pNew, (DO_NOT_ACQUIRE *)0 );
748     }
749 
750     /**
751       Returns the Boolean value from this string.
752 
753       This function can't be used for language specific conversion.
754 
755       @return   sal_True, if the string is 1 or "True" in any ASCII case.
756                 sal_False in any other case.
757     */
toBoolean() const758     sal_Bool toBoolean() const SAL_THROW(())
759     {
760         return rtl_str_toBoolean( pData->buffer );
761     }
762 
763     /**
764       Returns the first character from this string.
765 
766       @return   the first character from this string or 0, if this string
767                 is emptry.
768     */
toChar() const769     sal_Char toChar() const SAL_THROW(())
770     {
771         return pData->buffer[0];
772     }
773 
774     /**
775       Returns the int32 value from this string.
776 
777       This function can't be used for language specific conversion.
778 
779       @param    radix       the radix (between 2 and 36)
780       @return   the int32 represented from this string.
781                 0 if this string represents no number.
782     */
toInt32(sal_Int16 radix=10) const783     sal_Int32 toInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
784     {
785         return rtl_str_toInt32( pData->buffer, radix );
786     }
787 
788     /**
789       Returns the int64 value from this string.
790 
791       This function can't be used for language specific conversion.
792 
793       @param    radix       the radix (between 2 and 36)
794       @return   the int64 represented from this string.
795                 0 if this string represents no number.
796     */
toInt64(sal_Int16 radix=10) const797     sal_Int64 toInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
798     {
799         return rtl_str_toInt64( pData->buffer, radix );
800     }
801 
802     /**
803       Returns the float value from this string.
804 
805       This function can't be used for language specific conversion.
806 
807       @return   the float represented from this string.
808                 0.0 if this string represents no number.
809     */
toFloat() const810     float toFloat() const SAL_THROW(())
811     {
812         return rtl_str_toFloat( pData->buffer );
813     }
814 
815     /**
816       Returns the double value from this string.
817 
818       This function can't be used for language specific conversion.
819 
820       @return   the double represented from this string.
821                 0.0 if this string represents no number.
822     */
toDouble() const823     double toDouble() const SAL_THROW(())
824     {
825         return rtl_str_toDouble( pData->buffer );
826     }
827 
828     /**
829       Returns the string representation of the sal_Bool argument.
830 
831       If the sal_Bool is true, the string "true" is returned.
832       If the sal_Bool is false, the string "false" is returned.
833       This function can't be used for language specific conversion.
834 
835       @param    b   a sal_Bool.
836       @return   a string with the string representation of the argument.
837     */
valueOf(sal_Bool b)838     static OString valueOf( sal_Bool b ) SAL_THROW(())
839     {
840         sal_Char aBuf[RTL_STR_MAX_VALUEOFBOOLEAN];
841         rtl_String* pNewData = 0;
842         rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfBoolean( aBuf, b ) );
843         return OString( pNewData, (DO_NOT_ACQUIRE*)0 );
844     }
845 
846     /**
847       Returns the string representation of the char argument.
848 
849       @param    c   a character.
850       @return   a string with the string representation of the argument.
851     */
valueOf(sal_Char c)852     static OString valueOf( sal_Char c ) SAL_THROW(())
853     {
854         return OString( &c, 1 );
855     }
856 
857     /**
858       Returns the string representation of the int argument.
859 
860       This function can't be used for language specific conversion.
861 
862       @param    i           a int32.
863       @param    radix       the radix (between 2 and 36)
864       @return   a string with the string representation of the argument.
865     */
valueOf(sal_Int32 i,sal_Int16 radix=10)866     static OString valueOf( sal_Int32 i, sal_Int16 radix = 10 ) SAL_THROW(())
867     {
868         sal_Char aBuf[RTL_STR_MAX_VALUEOFINT32];
869         rtl_String* pNewData = 0;
870         rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfInt32( aBuf, i, radix ) );
871         return OString( pNewData, (DO_NOT_ACQUIRE*)0 );
872     }
873 
874     /**
875       Returns the string representation of the long argument.
876 
877       This function can't be used for language specific conversion.
878 
879       @param    ll          a int64.
880       @param    radix       the radix (between 2 and 36)
881       @return   a string with the string representation of the argument.
882     */
valueOf(sal_Int64 ll,sal_Int16 radix=10)883     static OString valueOf( sal_Int64 ll, sal_Int16 radix = 10 ) SAL_THROW(())
884     {
885         sal_Char aBuf[RTL_STR_MAX_VALUEOFINT64];
886         rtl_String* pNewData = 0;
887         rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfInt64( aBuf, ll, radix ) );
888         return OString( pNewData, (DO_NOT_ACQUIRE*)0 );
889     }
890 
891     /**
892       Returns the string representation of the float argument.
893 
894       This function can't be used for language specific conversion.
895 
896       @param    f           a float.
897       @return   a string with the string representation of the argument.
898     */
valueOf(float f)899     static OString valueOf( float f ) SAL_THROW(())
900     {
901         sal_Char aBuf[RTL_STR_MAX_VALUEOFFLOAT];
902         rtl_String* pNewData = 0;
903         rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfFloat( aBuf, f ) );
904         return OString( pNewData, (DO_NOT_ACQUIRE*)0 );
905     }
906 
907     /**
908       Returns the string representation of the double argument.
909 
910       This function can't be used for language specific conversion.
911 
912       @param    d           a double.
913       @return   a string with the string representation of the argument.
914     */
valueOf(double d)915     static OString valueOf( double d ) SAL_THROW(())
916     {
917         sal_Char aBuf[RTL_STR_MAX_VALUEOFDOUBLE];
918         rtl_String* pNewData = 0;
919         rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfDouble( aBuf, d ) );
920         return OString( pNewData, (DO_NOT_ACQUIRE*)0 );
921     }
922 };
923 
924 /* ======================================================================= */
925 
926 /** A helper to use OStrings with hash maps.
927 
928     Instances of this class are unary function objects that can be used as
929     hash function arguments to unordered_map, hash_map and similar constructs.
930  */
931 struct OStringHash
932 {
933     /** Compute a hash code for a string.
934 
935         @param rString
936         a string.
937 
938         @return
939         a hash code for the string.  This hash code should not be stored
940         persistently, as its computation may change in later revisions.
941      */
operator ()rtl::OStringHash942     size_t operator()( const rtl::OString& rString ) const
943         { return (size_t)rString.hashCode(); }
944 };
945 
946 /* ======================================================================= */
947 
948 /** Equality functor for classic c-strings (i.e. null-terminated char* strings) */
949 struct CStringEqual
950 {
operator ()rtl::CStringEqual951 	bool operator()( const char* p1, const char* p2) const {
952 		while( *p1 != '\0')
953 			if( *(p1++) != *(p2++))
954 				return false;
955 		return (*p2 == '\0');
956 	}
957 };
958 
959 /** Hashing functor for classic c-strings (i.e. null-terminated char* strings) */
960 struct CStringHash
961 {
operator ()rtl::CStringHash962 	size_t operator()( const char* p) const {
963 		size_t n = 0;
964 		while( *p)
965 			n += 4*n + *reinterpret_cast<const unsigned char*>(p++);
966 		return n;
967 	}
968 };
969 
970 } /* Namespace */
971 
972 /* Helper methods to support OString messages in OSL_ENSURE, DBG_ERROR, DBG_WARN, DBG_TRACE, etc. */
osl_assertFailedLine(const sal_Char * pszFileName,sal_Int32 nLine,const::rtl::OString & rMessage)973 inline sal_Bool SAL_CALL osl_assertFailedLine( const sal_Char* pszFileName, sal_Int32 nLine, const ::rtl::OString& rMessage)
974 	{ return osl_assertFailedLine( pszFileName, nLine, rMessage.getStr()); }
975 #ifdef DBG_UTIL
DbgOut(const rtl::OString & rMessage,sal_uInt16 nOutType,const sal_Char * pFileName,sal_uInt16 nLineNum)976 inline void DbgOut( const rtl::OString& rMessage, sal_uInt16 nOutType, const sal_Char* pFileName, sal_uInt16 nLineNum )
977 	{ DbgOut( rMessage.getStr(), nOutType, pFileName, nLineNum); }
978 #endif /* DBG_UTIL */
979 
980 #endif /* __cplusplus */
981 
982 #endif /* _RTL_STRING_HXX_ */
983 
984