xref: /aoo42x/main/sal/inc/rtl/ustring.hxx (revision 24c56ab9)
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_USTRING_HXX_
25 #define _RTL_USTRING_HXX_
26 
27 #ifdef __cplusplus
28 
29 #ifndef _RTL_DIAGNOSE_H_
30 #include "osl/diagnose.h"
31 #endif
32 #include <rtl/ustring.h>
33 #include <rtl/string.hxx>
34 #include <rtl/memory.h>
35 
36 #if defined EXCEPTIONS_OFF
37 #include <stdlib.h>
38 #else
39 #include <new>
40 #endif
41 
42 namespace rtl
43 {
44 /* ======================================================================= */
45 
46 /**
47   This String class provide base functionality for C++ like Unicode
48   character array handling. The advantage of this class is, that it
49   handle all the memory managament for you - and it do it
50   more efficient. If you assign a string to another string, the
51   data of both strings are shared (without any copy operation or
52   memory allocation) as long as you do not change the string. This class
53   stores also the length of the string, so that many operations are
54   faster as the C-str-functions.
55 
56   This class provide only readonly string handling. So you could create
57   a string and you could only query the content from this string.
58   It provide also functionality to change the string, but this results
59   in every case in a new string instance (in the most cases with an
60   memory allocation). You don't have functionality to change the
61   content of the string. If you want change the string content, than
62   you should us the OStringBuffer class, which provide these
63   functionality and avoid to much memory allocation.
64 
65   The design of this class is similar to the string classes in Java
66   and so more people should have fewer understanding problems when they
67   use this class.
68 */
69 
70 class OUString
71 {
72 public:
73     /** @internal */
74     rtl_uString * pData;
75 
76 private:
77     /** @internal */
78     class DO_NOT_ACQUIRE{};
79 
80     /** @internal */
81     OUString( rtl_uString * value, DO_NOT_ACQUIRE * )
82     {
83         pData = value;
84     }
85 
86 public:
87     /**
88       New string containing no characters.
89     */
90     OUString() SAL_THROW(())
91     {
92         pData = 0;
93         rtl_uString_new( &pData );
94     }
95 
96     /**
97       New string from OUString.
98 
99       @param    str         a OUString.
100     */
101     OUString( const OUString & str ) SAL_THROW(())
102     {
103         pData = str.pData;
104         rtl_uString_acquire( pData );
105     }
106 
107     /**
108       New string from OUString data.
109 
110       @param    str         a OUString data.
111     */
112     OUString( rtl_uString * str )  SAL_THROW(())
113     {
114         pData = str;
115         rtl_uString_acquire( pData );
116     }
117     /** New OUString from OUString data without acquiring it.  Takeover of ownership.
118 
119         @param str
120                OUString data
121         @param dummy
122                SAL_NO_ACQUIRE to distinguish from other ctors
123     */
124     inline OUString( rtl_uString * str, __sal_NoAcquire ) SAL_THROW( () )
125         { pData = str; }
126 
127 
128     /**
129       New string from a single Unicode character.
130 
131       @param    value       a Unicode character.
132     */
133 	explicit OUString( sal_Unicode value ) SAL_THROW(())
134         : pData (0)
135 	{
136         rtl_uString_newFromStr_WithLength( &pData, &value, 1 );
137 	}
138 
139     /**
140       New string from a Unicode character buffer array.
141 
142       @param    value       a NULL-terminated Unicode character array.
143     */
144     OUString( const sal_Unicode * value ) SAL_THROW(())
145     {
146         pData = 0;
147         rtl_uString_newFromStr( &pData, value );
148     }
149 
150     /**
151       New string from a Uniocde character buffer array.
152 
153       @param    value       a Unicode character array.
154       @param    length      the number of character which should be copied.
155                             The character array length must be greater or
156                             equal than this value.
157     */
158     OUString( const sal_Unicode * value, sal_Int32 length ) SAL_THROW(())
159     {
160         pData = 0;
161         rtl_uString_newFromStr_WithLength( &pData, value, length );
162     }
163 
164     /**
165       New string from a 8-Bit character buffer array.
166 
167       @param    value           a 8-Bit character array.
168       @param    length          the number of character which should be converted.
169                                 The 8-Bit character array length must be
170                                 greater or equal than this value.
171       @param    encoding        the text encoding from which the 8-Bit character
172                                 sequence should be converted.
173       @param    convertFlags    flags which controls the conversion.
174                                 see RTL_TEXTTOUNICODE_FLAGS_...
175 
176       @exception std::bad_alloc is thrown if an out-of-memory condition occurs
177     */
178     OUString( const sal_Char * value, sal_Int32 length,
179               rtl_TextEncoding encoding,
180               sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS )
181     {
182         pData = 0;
183         rtl_string2UString( &pData, value, length, encoding, convertFlags );
184 #if defined EXCEPTIONS_OFF
185         OSL_ASSERT(pData != NULL);
186 #else
187         if (pData == 0) {
188             throw std::bad_alloc();
189         }
190 #endif
191     }
192 
193     /** Create a new string from an array of Unicode code points.
194 
195         @param codePoints
196         an array of at least codePointCount code points, which each must be in
197         the range from 0 to 0x10FFFF, inclusive.  May be null if codePointCount
198         is zero.
199 
200         @param codePointCount
201         the non-negative number of code points.
202 
203         @exception std::bad_alloc
204         is thrown if either an out-of-memory condition occurs or the resulting
205         number of UTF-16 code units would have been larger than SAL_MAX_INT32.
206 
207         @since UDK 3.2.7
208     */
209     inline explicit OUString(
210         sal_uInt32 const * codePoints, sal_Int32 codePointCount):
211         pData(NULL)
212     {
213         rtl_uString_newFromCodePoints(&pData, codePoints, codePointCount);
214         if (pData == NULL) {
215 #if defined EXCEPTIONS_OFF
216             abort();
217 #else
218             throw std::bad_alloc();
219 #endif
220         }
221     }
222 
223     /**
224       Release the string data.
225     */
226     ~OUString() SAL_THROW(())
227     {
228         rtl_uString_release( pData );
229     }
230 
231     /** Provides an OUString const & passing a storage pointer of an
232         rtl_uString * handle.
233         It is more convenient to use C++ OUString member functions when dealing
234         with rtl_uString * handles.  Using this function avoids unnecessary
235         acquire()/release() calls for a temporary OUString object.
236 
237         @param ppHandle
238                pointer to storage
239         @return
240                OUString const & based on given storage
241     */
242     static inline OUString const & unacquired( rtl_uString * const * ppHandle )
243         { return * reinterpret_cast< OUString const * >( ppHandle ); }
244 
245     /**
246       Assign a new string.
247 
248       @param    str         a OUString.
249     */
250     OUString & operator=( const OUString & str ) SAL_THROW(())
251     {
252         rtl_uString_assign( &pData, str.pData );
253         return *this;
254     }
255 
256     /**
257       Append a string to this string.
258 
259       @param    str         a OUString.
260     */
261     OUString & operator+=( const OUString & str ) SAL_THROW(())
262     {
263         rtl_uString_newConcat( &pData, pData, str.pData );
264         return *this;
265     }
266 
267     /**
268       Returns the length of this string.
269 
270       The length is equal to the number of Unicode characters in this string.
271 
272       @return   the length of the sequence of characters represented by this
273                 object.
274     */
275     sal_Int32 getLength() const SAL_THROW(()) { return pData->length; }
276 
277 private:
278     /**
279       Returns a pointer to the Unicode character buffer from this string.
280 
281       NOTE: the implicit cast to a UTF-16 pointer is obsolete
282             because it is too dangerous #i123068#
283 
284       It isn't necessarily NULL terminated.
285 
286       @return   a pointer to the Unicode characters buffer from this object.
287     */
288     operator const sal_Unicode *() const SAL_THROW(()) { return pData->buffer; }
289 public:
290     /** Returns a reference to a UTF-16 element of this string. */
291     sal_Unicode& operator[]( int n ) { return pData->buffer[n]; }
292     /** Returns a const reference to a UTF-16 element of this string. */
293     const sal_Unicode& operator[]( int n ) const { return pData->buffer[n]; }
294     /** Returns a bool indicating whether this string is empty. */
295     bool isEmpty() const { return (pData->length == 0); }
296 
297 
298     /**
299       Returns a pointer to the Unicode character buffer from this string.
300 
301       It isn't necessarily NULL terminated.
302 
303       @return   a pointer to the Unicode characters buffer from this object.
304     */
305     const sal_Unicode * getStr() const SAL_THROW(()) { return pData->buffer; }
306 
307     /**
308       Compares two strings.
309 
310       The comparison is based on the numeric value of each character in
311       the strings and return a value indicating their relationship.
312       This function can't be used for language specific sorting.
313 
314       @param    str         the object to be compared.
315       @return   0 - if both strings are equal
316                 < 0 - if this string is less than the string argument
317                 > 0 - if this string is greater than the string argument
318     */
319     sal_Int32 compareTo( const OUString & str ) const SAL_THROW(())
320     {
321         return rtl_ustr_compare_WithLength( pData->buffer, pData->length,
322                                             str.pData->buffer, str.pData->length );
323     }
324 
325     /**
326       Compares two strings with an maximum count of characters.
327 
328       The comparison is based on the numeric value of each character in
329       the strings and return a value indicating their relationship.
330       This function can't be used for language specific sorting.
331 
332       @param    str         the object to be compared.
333       @param    maxLength   the maximum count of characters to be compared.
334       @return   0 - if both strings are equal
335                 < 0 - if this string is less than the string argument
336                 > 0 - if this string is greater than the string argument
337     */
338     sal_Int32 compareTo( const OUString & str, sal_Int32 maxLength ) const SAL_THROW(())
339     {
340         return rtl_ustr_shortenedCompare_WithLength( pData->buffer, pData->length,
341                                                      str.pData->buffer, str.pData->length, maxLength );
342     }
343 
344     /**
345       Compares two strings in reverse order.
346 
347       The comparison is based on the numeric value of each character in
348       the strings and return a value indicating their relationship.
349       This function can't be used for language specific sorting.
350 
351       @param    str         the object to be compared.
352       @return   0 - if both strings are equal
353                 < 0 - if this string is less than the string argument
354                 > 0 - if this string is greater than the string argument
355     */
356     sal_Int32 reverseCompareTo( const OUString & str ) const SAL_THROW(())
357     {
358         return rtl_ustr_reverseCompare_WithLength( pData->buffer, pData->length,
359                                                    str.pData->buffer, str.pData->length );
360     }
361 
362     /**
363       Perform a comparison of two strings.
364 
365       The result is true if and only if second string
366       represents the same sequence of characters as the first string.
367       This function can't be used for language specific comparison.
368 
369       @param    str         the object to be compared.
370       @return   sal_True if the strings are equal;
371                 sal_False, otherwise.
372     */
373     sal_Bool equals( const OUString & str ) const SAL_THROW(())
374     {
375         if ( pData->length != str.pData->length )
376             return sal_False;
377         if ( pData == str.pData )
378             return sal_True;
379         return rtl_ustr_reverseCompare_WithLength( pData->buffer, pData->length,
380                                                    str.pData->buffer, str.pData->length ) == 0;
381     }
382 
383     /**
384       Perform a ASCII lowercase comparison of two strings.
385 
386       The result is true if and only if second string
387       represents the same sequence of characters as the first string,
388       ignoring the case.
389       Character values between 65 and 90 (ASCII A-Z) are interpreted as
390       values between 97 and 122 (ASCII a-z).
391       This function can't be used for language specific comparison.
392 
393       @param    str         the object to be compared.
394       @return   sal_True if the strings are equal;
395                 sal_False, otherwise.
396     */
397     sal_Bool equalsIgnoreAsciiCase( const OUString & str ) const SAL_THROW(())
398     {
399         if ( pData->length != str.pData->length )
400             return sal_False;
401         if ( pData == str.pData )
402             return sal_True;
403         return rtl_ustr_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
404                                                            str.pData->buffer, str.pData->length ) == 0;
405     }
406 
407     /**
408       Match against a substring appearing in this string.
409 
410       The result is true if and only if the second string appears as a substring
411       of this string, at the given position.
412       This function can't be used for language specific comparison.
413 
414       @param    str         the object (substring) to be compared.
415       @param    fromIndex   the index to start the comparion from.
416                             The index must be greater or equal than 0
417                             and less or equal as the string length.
418       @return   sal_True if str match with the characters in the string
419                 at the given position;
420                 sal_False, otherwise.
421     */
422     sal_Bool match( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
423     {
424         return rtl_ustr_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
425                                                      str.pData->buffer, str.pData->length, str.pData->length ) == 0;
426     }
427 
428     /**
429       Match against a substring appearing in this string, ignoring the case of
430       ASCII letters.
431 
432       The result is true if and only if the second string appears as a substring
433       of this string, at the given position.
434       Character values between 65 and 90 (ASCII A-Z) are interpreted as
435       values between 97 and 122 (ASCII a-z).
436       This function can't be used for language specific comparison.
437 
438       @param    str         the object (substring) to be compared.
439       @param    fromIndex   the index to start the comparion from.
440                             The index must be greater or equal than 0
441                             and less or equal as the string length.
442       @return   sal_True if str match with the characters in the string
443                 at the given position;
444                 sal_False, otherwise.
445     */
446     sal_Bool matchIgnoreAsciiCase( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
447     {
448         return rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
449                                                                     str.pData->buffer, str.pData->length,
450                                                                     str.pData->length ) == 0;
451     }
452 
453     /**
454       Compares two strings.
455 
456       The comparison is based on the numeric value of each character in
457       the strings and return a value indicating their relationship.
458       Since this method is optimized for performance, the ASCII character
459       values are not converted in any way. The caller has to make sure that
460       all ASCII characters are in the allowed range between 0 and
461       127. The ASCII string must be NULL-terminated.
462       This function can't be used for language specific sorting.
463 
464       @param  asciiStr      the 8-Bit ASCII character string to be compared.
465       @return   0 - if both strings are equal
466                 < 0 - if this string is less than the string argument
467                 > 0 - if this string is greater than the string argument
468     */
469     sal_Int32 compareToAscii( const sal_Char* asciiStr ) const SAL_THROW(())
470     {
471         return rtl_ustr_ascii_compare_WithLength( pData->buffer, pData->length, asciiStr );
472     }
473 
474     /**
475       Compares two strings with an maximum count of characters.
476 
477       The comparison is based on the numeric value of each character in
478       the strings and return a value indicating their relationship.
479       Since this method is optimized for performance, the ASCII character
480       values are not converted in any way. The caller has to make sure that
481       all ASCII characters are in the allowed range between 0 and
482       127. The ASCII string must be NULL-terminated.
483       This function can't be used for language specific sorting.
484 
485       @param  asciiStr          the 8-Bit ASCII character string to be compared.
486       @param  maxLength         the maximum count of characters to be compared.
487       @return   0 - if both strings are equal
488                 < 0 - if this string is less than the string argument
489                 > 0 - if this string is greater than the string argument
490     */
491     sal_Int32 compareToAscii( const sal_Char * asciiStr, sal_Int32 maxLength ) const SAL_THROW(())
492     {
493         return rtl_ustr_ascii_shortenedCompare_WithLength( pData->buffer, pData->length,
494                                                            asciiStr, maxLength );
495     }
496 
497     /**
498       Compares two strings in reverse order.
499 
500       This could be useful, if normally both strings start with the same
501       content. The comparison is based on the numeric value of each character
502       in the strings and return a value indicating their relationship.
503       Since this method is optimized for performance, the ASCII character
504       values are not converted in any way. The caller has to make sure that
505       all ASCII characters are in the allowed range between 0 and
506       127. The ASCII string must be NULL-terminated and must be greater or
507       equal as asciiStrLength.
508       This function can't be used for language specific sorting.
509 
510       @param    asciiStr        the 8-Bit ASCII character string to be compared.
511       @param    asciiStrLength  the length of the ascii string
512       @return   0 - if both strings are equal
513                 < 0 - if this string is less than the string argument
514                 > 0 - if this string is greater than the string argument
515     */
516     sal_Int32 reverseCompareToAsciiL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
517     {
518         return rtl_ustr_asciil_reverseCompare_WithLength( pData->buffer, pData->length,
519                                                           asciiStr, asciiStrLength );
520     }
521 
522     /**
523       Perform a comparison of two strings.
524 
525       The result is true if and only if second string
526       represents the same sequence of characters as the first string.
527       Since this method is optimized for performance, the ASCII character
528       values are not converted in any way. The caller has to make sure that
529       all ASCII characters are in the allowed range between 0 and
530       127. The ASCII string must be NULL-terminated.
531       This function can't be used for language specific comparison.
532 
533       @param    asciiStr        the 8-Bit ASCII character string to be compared.
534       @return   sal_True if the strings are equal;
535                 sal_False, otherwise.
536     */
537     sal_Bool equalsAscii( const sal_Char* asciiStr ) const SAL_THROW(())
538     {
539         return rtl_ustr_ascii_compare_WithLength( pData->buffer, pData->length,
540                                                   asciiStr ) == 0;
541     }
542 
543     /**
544       Perform a comparison of two strings.
545 
546       The result is true if and only if second string
547       represents the same sequence of characters as the first string.
548       Since this method is optimized for performance, the ASCII character
549       values are not converted in any way. The caller has to make sure that
550       all ASCII characters are in the allowed range between 0 and
551       127. The ASCII string must be NULL-terminated and must be greater or
552       equal as asciiStrLength.
553       This function can't be used for language specific comparison.
554 
555       @param    asciiStr         the 8-Bit ASCII character string to be compared.
556       @param    asciiStrLength   the length of the ascii string
557       @return   sal_True if the strings are equal;
558                 sal_False, otherwise.
559     */
560     sal_Bool equalsAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
561     {
562         if ( pData->length != asciiStrLength )
563             return sal_False;
564 
565         return rtl_ustr_asciil_reverseEquals_WithLength(
566 					pData->buffer, asciiStr, asciiStrLength );
567     }
568 
569     /**
570       Perform a ASCII lowercase comparison of two strings.
571 
572       The result is true if and only if second string
573       represents the same sequence of characters as the first string,
574       ignoring the case.
575       Character values between 65 and 90 (ASCII A-Z) are interpreted as
576       values between 97 and 122 (ASCII a-z).
577       Since this method is optimized for performance, the ASCII character
578       values are not converted in any way. The caller has to make sure that
579       all ASCII characters are in the allowed range between 0 and
580       127. The ASCII string must be NULL-terminated.
581       This function can't be used for language specific comparison.
582 
583       @param    asciiStr        the 8-Bit ASCII character string to be compared.
584       @return   sal_True if the strings are equal;
585                 sal_False, otherwise.
586     */
587     sal_Bool equalsIgnoreAsciiCaseAscii( const sal_Char * asciiStr ) const SAL_THROW(())
588     {
589         return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, asciiStr ) == 0;
590     }
591 
592     /**
593       Perform a ASCII lowercase comparison of two strings.
594 
595       The result is true if and only if second string
596       represents the same sequence of characters as the first string,
597       ignoring the case.
598       Character values between 65 and 90 (ASCII A-Z) are interpreted as
599       values between 97 and 122 (ASCII a-z).
600       Since this method is optimized for performance, the ASCII character
601       values are not converted in any way. The caller has to make sure that
602       all ASCII characters are in the allowed range between 0 and
603       127. The ASCII string must be NULL-terminated and must be greater or
604       equal as asciiStrLength.
605       This function can't be used for language specific comparison.
606 
607       @param    asciiStr        the 8-Bit ASCII character string to be compared.
608       @param    asciiStrLength  the length of the ascii string
609       @return   sal_True if the strings are equal;
610                 sal_False, otherwise.
611     */
612     sal_Bool equalsIgnoreAsciiCaseAsciiL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
613     {
614         if ( pData->length != asciiStrLength )
615             return sal_False;
616 
617         return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, asciiStr ) == 0;
618     }
619 
620     /**
621       Match against a substring appearing in this string.
622 
623       The result is true if and only if the second string appears as a substring
624       of this string, at the given position.
625       Since this method is optimized for performance, the ASCII character
626       values are not converted in any way. The caller has to make sure that
627       all ASCII characters are in the allowed range between 0 and
628       127. The ASCII string must be NULL-terminated and must be greater or
629       equal as asciiStrLength.
630       This function can't be used for language specific comparison.
631 
632       @param    str         the object (substring) to be compared.
633       @param    fromIndex   the index to start the comparion from.
634                             The index must be greater or equal than 0
635                             and less or equal as the string length.
636       @return   sal_True if str match with the characters in the string
637                 at the given position;
638                 sal_False, otherwise.
639     */
640     sal_Bool matchAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
641     {
642         return rtl_ustr_ascii_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
643                                                            asciiStr, asciiStrLength ) == 0;
644     }
645 
646     /**
647       Match against a substring appearing in this string, ignoring the case of
648       ASCII letters.
649 
650       The result is true if and only if the second string appears as a substring
651       of this string, at the given position.
652       Character values between 65 and 90 (ASCII A-Z) are interpreted as
653       values between 97 and 122 (ASCII a-z).
654       Since this method is optimized for performance, the ASCII character
655       values are not converted in any way. The caller has to make sure that
656       all ASCII characters are in the allowed range between 0 and
657       127. The ASCII string must be NULL-terminated and must be greater or
658       equal as asciiStrLength.
659       This function can't be used for language specific comparison.
660 
661       @param    asciiStr        the 8-Bit ASCII character string to be compared.
662       @param    asciiStrLength  the length of the ascii string
663       @param    fromIndex       the index to start the comparion from.
664                                 The index must be greater or equal than 0
665                                 and less or equal as the string length.
666       @return   sal_True if str match with the characters in the string
667                 at the given position;
668                 sal_False, otherwise.
669     */
670     sal_Bool matchIgnoreAsciiCaseAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
671     {
672         return rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
673                                                                           asciiStr, asciiStrLength ) == 0;
674     }
675 
676     /**
677       Check whether this string ends with a given ASCII string.
678 
679       @param asciiStr a sequence of at least asciiStrLength ASCII characters
680           (bytes in the range 0x00--0x7F)
681       @param asciiStrLen the length of asciiStr; must be non-negative
682       @return true if this string ends with asciiStr; otherwise, false is
683       returned
684 
685       @since UDK 3.2.7
686      */
687     inline bool endsWithAsciiL(char const * asciiStr, sal_Int32 asciiStrLength)
688         const
689     {
690         return asciiStrLength <= pData->length
691             && rtl_ustr_asciil_reverseEquals_WithLength(
692                 pData->buffer + pData->length - asciiStrLength, asciiStr,
693                 asciiStrLength);
694     }
695 
696     /**
697       Check whether this string ends with a given ASCII string, ignoring the
698       case of ASCII letters.
699 
700       @param asciiStr a sequence of at least asciiStrLength ASCII characters
701           (bytes in the range 0x00--0x7F)
702       @param asciiStrLen the length of asciiStr; must be non-negative
703       @return true if this string ends with asciiStr, ignoring the case of ASCII
704       letters ("A"--"Z" and "a"--"z"); otherwise, false is returned
705      */
706     inline bool endsWithIgnoreAsciiCaseAsciiL(
707         char const * asciiStr, sal_Int32 asciiStrLength) const
708     {
709         return asciiStrLength <= pData->length
710             && (rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
711                     pData->buffer + pData->length - asciiStrLength,
712                     asciiStrLength, asciiStr, asciiStrLength)
713                 == 0);
714     }
715 
716     friend sal_Bool     operator == ( const OUString& rStr1,    const OUString& rStr2 ) SAL_THROW(())
717                         { return rStr1.getLength() == rStr2.getLength() && rStr1.compareTo( rStr2 ) == 0; }
718     friend sal_Bool     operator == ( const OUString& rStr1,    const sal_Unicode * pStr2 ) SAL_THROW(())
719                         { return rStr1.compareTo( pStr2 ) == 0; }
720     friend sal_Bool     operator == ( const sal_Unicode * pStr1,    const OUString& rStr2 ) SAL_THROW(())
721                         { return OUString( pStr1 ).compareTo( rStr2 ) == 0; }
722 
723     friend sal_Bool     operator != ( const OUString& rStr1,        const OUString& rStr2 ) SAL_THROW(())
724                         { return !(operator == ( rStr1, rStr2 )); }
725     friend sal_Bool     operator != ( const OUString& rStr1,    const sal_Unicode * pStr2 ) SAL_THROW(())
726                         { return !(operator == ( rStr1, pStr2 )); }
727     friend sal_Bool     operator != ( const sal_Unicode * pStr1,    const OUString& rStr2 ) SAL_THROW(())
728                         { return !(operator == ( pStr1, rStr2 )); }
729 
730     friend sal_Bool     operator <  ( const OUString& rStr1,    const OUString& rStr2 ) SAL_THROW(())
731                         { return rStr1.compareTo( rStr2 ) < 0; }
732     friend sal_Bool     operator >  ( const OUString& rStr1,    const OUString& rStr2 ) SAL_THROW(())
733                         { return rStr1.compareTo( rStr2 ) > 0; }
734     friend sal_Bool     operator <= ( const OUString& rStr1,    const OUString& rStr2 ) SAL_THROW(())
735                         { return rStr1.compareTo( rStr2 ) <= 0; }
736     friend sal_Bool     operator >= ( const OUString& rStr1,    const OUString& rStr2 ) SAL_THROW(())
737                         { return rStr1.compareTo( rStr2 ) >= 0; }
738 
739     /**
740       Returns a hashcode for this string.
741 
742       @return   a hash code value for this object.
743 
744       @see rtl::OUStringHash for convenient use of STLPort's hash_map
745     */
746     sal_Int32 hashCode() const SAL_THROW(())
747     {
748         return rtl_ustr_hashCode_WithLength( pData->buffer, pData->length );
749     }
750 
751     /**
752       Returns the index within this string of the first occurrence of the
753       specified character, starting the search at the specified index.
754 
755       @param    ch          character to be located.
756       @param    fromIndex   the index to start the search from.
757                             The index must be greater or equal than 0
758                             and less or equal as the string length.
759       @return   the index of the first occurrence of the character in the
760                 character sequence represented by this string that is
761                 greater than or equal to fromIndex, or
762                 -1 if the character does not occur.
763     */
764     sal_Int32 indexOf( sal_Unicode ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
765     {
766         sal_Int32 ret = rtl_ustr_indexOfChar_WithLength( pData->buffer+fromIndex, pData->length-fromIndex, ch );
767         return (ret < 0 ? ret : ret+fromIndex);
768     }
769 
770     /**
771       Returns the index within this string of the last occurrence of the
772       specified character, searching backward starting at the end.
773 
774       @param    ch          character to be located.
775       @return   the index of the last occurrence of the character in the
776                 character sequence represented by this string, or
777                 -1 if the character does not occur.
778     */
779     sal_Int32 lastIndexOf( sal_Unicode ch ) const SAL_THROW(())
780     {
781         return rtl_ustr_lastIndexOfChar_WithLength( pData->buffer, pData->length, ch );
782     }
783 
784     /**
785       Returns the index within this string of the last occurrence of the
786       specified character, searching backward starting before the specified
787       index.
788 
789       @param    ch          character to be located.
790       @param    fromIndex   the index before which to start the search.
791       @return   the index of the last occurrence of the character in the
792                 character sequence represented by this string that
793                 is less than fromIndex, or -1
794                 if the character does not occur before that point.
795     */
796     sal_Int32 lastIndexOf( sal_Unicode ch, sal_Int32 fromIndex ) const SAL_THROW(())
797     {
798         return rtl_ustr_lastIndexOfChar_WithLength( pData->buffer, fromIndex, ch );
799     }
800 
801     /**
802       Returns the index within this string of the first occurrence of the
803       specified substring, starting at the specified index.
804 
805       If str doesn't include any character, always -1 is
806       returned. This is also the case, if both strings are empty.
807 
808       @param    str         the substring to search for.
809       @param    fromIndex   the index to start the search from.
810       @return   If the string argument occurs one or more times as a substring
811                 within this string at the starting index, then the index
812                 of the first character of the first such substring is
813                 returned. If it does not occur as a substring starting
814                 at fromIndex or beyond, -1 is returned.
815     */
816     sal_Int32 indexOf( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
817     {
818         sal_Int32 ret = rtl_ustr_indexOfStr_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
819                                                         str.pData->buffer, str.pData->length );
820         return (ret < 0 ? ret : ret+fromIndex);
821     }
822 
823     /**
824        Returns the index within this string of the first occurrence of the
825        specified ASCII substring, starting at the specified index.
826 
827        @param str
828        the substring to be searched for.  Need not be null-terminated, but must
829        be at least as long as the specified len.  Must only contain characters
830        in the ASCII range 0x00--7F.
831 
832        @param len
833        the length of the substring; must be non-negative.
834 
835        @param fromIndex
836        the index to start the search from.  Must be in the range from zero to
837        the length of this string, inclusive.
838 
839        @return
840        the index (starting at 0) of the first character of the first occurrence
841        of the substring within this string starting at the given fromIndex, or
842        -1 if the substring does not occur.  If len is zero, -1 is returned.
843 
844        @since UDK 3.2.7
845     */
846     sal_Int32 indexOfAsciiL(
847         char const * str, sal_Int32 len, sal_Int32 fromIndex = 0) const
848         SAL_THROW(())
849     {
850         sal_Int32 ret = rtl_ustr_indexOfAscii_WithLength(
851             pData->buffer + fromIndex, pData->length - fromIndex, str, len);
852         return ret < 0 ? ret : ret + fromIndex;
853     }
854 
855     /**
856       Returns the index within this string of the last occurrence of
857       the specified substring, searching backward starting at the end.
858 
859       The returned index indicates the starting index of the substring
860       in this string.
861       If str doesn't include any character, always -1 is
862       returned. This is also the case, if both strings are empty.
863 
864       @param    str         the substring to search for.
865       @return   If the string argument occurs one or more times as a substring
866                 within this string, then the index of the first character of
867                 the last such substring is returned. If it does not occur as
868                 a substring, -1 is returned.
869     */
870     sal_Int32 lastIndexOf( const OUString & str ) const SAL_THROW(())
871     {
872         return rtl_ustr_lastIndexOfStr_WithLength( pData->buffer, pData->length,
873                                                    str.pData->buffer, str.pData->length );
874     }
875 
876     /**
877       Returns the index within this string of the last occurrence of
878       the specified substring, searching backward starting before the specified
879       index.
880 
881       The returned index indicates the starting index of the substring
882       in this string.
883       If str doesn't include any character, always -1 is
884       returned. This is also the case, if both strings are empty.
885 
886       @param    str         the substring to search for.
887       @param    fromIndex   the index before which to start the search.
888       @return   If the string argument occurs one or more times as a substring
889                 within this string before the starting index, then the index
890                 of the first character of the last such substring is
891                 returned. Otherwise, -1 is returned.
892     */
893     sal_Int32 lastIndexOf( const OUString & str, sal_Int32 fromIndex ) const SAL_THROW(())
894     {
895         return rtl_ustr_lastIndexOfStr_WithLength( pData->buffer, fromIndex,
896                                                    str.pData->buffer, str.pData->length );
897     }
898 
899     /**
900        Returns the index within this string of the last occurrence of the
901        specified ASCII substring.
902 
903        @param str
904        the substring to be searched for.  Need not be null-terminated, but must
905        be at least as long as the specified len.  Must only contain characters
906        in the ASCII range 0x00--7F.
907 
908        @param len
909        the length of the substring; must be non-negative.
910 
911        @return
912        the index (starting at 0) of the first character of the last occurrence
913        of the substring within this string, or -1 if the substring does not
914        occur.  If len is zero, -1 is returned.
915 
916        @since UDK 3.2.7
917     */
918     sal_Int32 lastIndexOfAsciiL(char const * str, sal_Int32 len) const
919         SAL_THROW(())
920     {
921         return rtl_ustr_lastIndexOfAscii_WithLength(
922             pData->buffer, pData->length, str, len);
923     }
924 
925     /**
926       Returns a new string that is a substring of this string.
927 
928       The substring begins at the specified beginIndex.  It is an error for
929       beginIndex to be negative or to be greater than the length of this string.
930 
931       @param     beginIndex   the beginning index, inclusive.
932       @return    the specified substring.
933     */
934     OUString copy( sal_Int32 beginIndex ) const SAL_THROW(())
935     {
936         OSL_ASSERT(beginIndex >= 0 && beginIndex <= getLength());
937         if ( beginIndex == 0 )
938             return *this;
939         else
940         {
941             rtl_uString* pNew = 0;
942             rtl_uString_newFromStr_WithLength( &pNew, pData->buffer+beginIndex, getLength()-beginIndex );
943             return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
944         }
945     }
946 
947     /**
948       Returns a new string that is a substring of this string.
949 
950       The substring begins at the specified beginIndex and contains count
951       characters.  It is an error for either beginIndex or count to be negative,
952       or for beginIndex + count to be greater than the length of this string.
953 
954       @param     beginIndex   the beginning index, inclusive.
955       @param     count        the number of characters.
956       @return    the specified substring.
957     */
958     OUString copy( sal_Int32 beginIndex, sal_Int32 count ) const SAL_THROW(())
959     {
960         OSL_ASSERT(beginIndex >= 0 && beginIndex <= getLength()
961                    && count >= 0 && count <= getLength() - beginIndex);
962         if ( (beginIndex == 0) && (count == getLength()) )
963             return *this;
964         else
965         {
966             rtl_uString* pNew = 0;
967             rtl_uString_newFromStr_WithLength( &pNew, pData->buffer+beginIndex, count );
968             return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
969         }
970     }
971 
972     /**
973       Concatenates the specified string to the end of this string.
974 
975       @param    str   the string that is concatenated to the end
976                       of this string.
977       @return   a string that represents the concatenation of this string
978                 followed by the string argument.
979     */
980     OUString concat( const OUString & str ) const SAL_THROW(())
981     {
982         rtl_uString* pNew = 0;
983         rtl_uString_newConcat( &pNew, pData, str.pData );
984         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
985     }
986 
987     friend OUString operator+( const OUString& rStr1, const OUString& rStr2  ) SAL_THROW(())
988     {
989         return rStr1.concat( rStr2 );
990     }
991 
992     /**
993       Returns a new string resulting from replacing n = count characters
994       from position index in this string with newStr.
995 
996       @param  index   the replacing index in str.
997                       The index must be greater or equal as 0 and
998                       less or equal as the length of the string.
999       @param  count   the count of charcters that will replaced
1000                       The count must be greater or equal as 0 and
1001                       less or equal as the length of the string minus index.
1002       @param  newStr  the new substring.
1003       @return the new string.
1004     */
1005     OUString replaceAt( sal_Int32 index, sal_Int32 count, const OUString& newStr ) const SAL_THROW(())
1006     {
1007         rtl_uString* pNew = 0;
1008         rtl_uString_newReplaceStrAt( &pNew, pData, index, count, newStr.pData );
1009         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1010     }
1011 
1012     /**
1013       Returns a new string resulting from replacing all occurrences of
1014       oldChar in this string with newChar.
1015 
1016       If the character oldChar does not occur in the character sequence
1017       represented by this object, then the string is assigned with
1018       str.
1019 
1020       @param    oldChar     the old character.
1021       @param    newChar     the new character.
1022       @return   a string derived from this string by replacing every
1023                 occurrence of oldChar with newChar.
1024     */
1025     OUString replace( sal_Unicode oldChar, sal_Unicode newChar ) const SAL_THROW(())
1026     {
1027         rtl_uString* pNew = 0;
1028         rtl_uString_newReplace( &pNew, pData, oldChar, newChar );
1029         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1030     }
1031 
1032     /**
1033       Converts from this string all ASCII uppercase characters (65-90)
1034       to ASCII lowercase characters (97-122).
1035 
1036       This function can't be used for language specific conversion.
1037       If the string doesn't contain characters which must be converted,
1038       then the new string is assigned with str.
1039 
1040       @return   the string, converted to ASCII lowercase.
1041     */
1042     OUString toAsciiLowerCase() const SAL_THROW(())
1043     {
1044         rtl_uString* pNew = 0;
1045         rtl_uString_newToAsciiLowerCase( &pNew, pData );
1046         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1047     }
1048 
1049     /**
1050       Converts from this string all ASCII lowercase characters (97-122)
1051       to ASCII uppercase characters (65-90).
1052 
1053       This function can't be used for language specific conversion.
1054       If the string doesn't contain characters which must be converted,
1055       then the new string is assigned with str.
1056 
1057       @return   the string, converted to ASCII uppercase.
1058     */
1059     OUString toAsciiUpperCase() const SAL_THROW(())
1060     {
1061         rtl_uString* pNew = 0;
1062         rtl_uString_newToAsciiUpperCase( &pNew, pData );
1063         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1064     }
1065 
1066     /**
1067       Returns a new string resulting from removing white space from both ends
1068       of the string.
1069 
1070       All characters that have codes less than or equal to
1071       32 (the space character) are considered to be white space.
1072       If the string doesn't contain white spaces at both ends,
1073       then the new string is assigned with str.
1074 
1075       @return   the string, with white space removed from the front and end.
1076     */
1077     OUString trim() const SAL_THROW(())
1078     {
1079         rtl_uString* pNew = 0;
1080         rtl_uString_newTrim( &pNew, pData );
1081         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1082     }
1083 
1084     /**
1085       Returns a token in the string.
1086 
1087       Example:
1088         sal_Int32 nIndex = 0;
1089         do
1090         {
1091             ...
1092             OUString aToken = aStr.getToken( 0, ';', nIndex );
1093             ...
1094         }
1095         while ( nIndex >= 0 );
1096 
1097       @param    token       the number of the token to return
1098       @param    cTok        the character which seperate the tokens.
1099       @param    index       the position at which the token is searched in the
1100                             string.
1101                             The index must not be greater than the length of the
1102                             string.
1103                             This param is set to the position of the
1104                             next token or to -1, if it is the last token.
1105       @return   the token; if either token or index is negative, an empty token
1106                 is returned (and index is set to -1)
1107     */
1108     OUString getToken( sal_Int32 token, sal_Unicode cTok, sal_Int32& index ) const SAL_THROW(())
1109     {
1110         rtl_uString * pNew = 0;
1111         index = rtl_uString_getToken( &pNew, pData, token, cTok, index );
1112         return OUString( pNew, (DO_NOT_ACQUIRE *)0 );
1113     }
1114 
1115     /**
1116       Returns the Boolean value from this string.
1117 
1118       This function can't be used for language specific conversion.
1119 
1120       @return   sal_True, if the string is 1 or "True" in any ASCII case.
1121                 sal_False in any other case.
1122     */
1123     sal_Bool toBoolean() const SAL_THROW(())
1124     {
1125         return rtl_ustr_toBoolean( pData->buffer );
1126     }
1127 
1128     /**
1129       Returns the first character from this string.
1130 
1131       @return   the first character from this string or 0, if this string
1132                 is emptry.
1133     */
1134     sal_Unicode toChar() const SAL_THROW(())
1135     {
1136         return pData->buffer[0];
1137     }
1138 
1139     /**
1140       Returns the int32 value from this string.
1141 
1142       This function can't be used for language specific conversion.
1143 
1144       @param    radix       the radix (between 2 and 36)
1145       @return   the int32 represented from this string.
1146                 0 if this string represents no number.
1147     */
1148     sal_Int32 toInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
1149     {
1150         return rtl_ustr_toInt32( pData->buffer, radix );
1151     }
1152 
1153     /**
1154       Returns the int64 value from this string.
1155 
1156       This function can't be used for language specific conversion.
1157 
1158       @param    radix       the radix (between 2 and 36)
1159       @return   the int64 represented from this string.
1160                 0 if this string represents no number.
1161     */
1162     sal_Int64 toInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
1163     {
1164         return rtl_ustr_toInt64( pData->buffer, radix );
1165     }
1166 
1167     /**
1168       Returns the float value from this string.
1169 
1170       This function can't be used for language specific conversion.
1171 
1172       @return   the float represented from this string.
1173                 0.0 if this string represents no number.
1174     */
1175     float toFloat() const SAL_THROW(())
1176     {
1177         return rtl_ustr_toFloat( pData->buffer );
1178     }
1179 
1180     /**
1181       Returns the double value from this string.
1182 
1183       This function can't be used for language specific conversion.
1184 
1185       @return   the double represented from this string.
1186                 0.0 if this string represents no number.
1187     */
1188     double toDouble() const SAL_THROW(())
1189     {
1190         return rtl_ustr_toDouble( pData->buffer );
1191     }
1192 
1193 
1194     /**
1195        Return a canonical representation for a string.
1196 
1197        A pool of strings, initially empty is maintained privately
1198        by the string class. On invocation, if present in the pool
1199        the original string will be returned. Otherwise this string,
1200        or a copy thereof will be added to the pool and returned.
1201 
1202        @return
1203        a version of the string from the pool.
1204 
1205        @exception std::bad_alloc is thrown if an out-of-memory condition occurs
1206 
1207        @since UDK 3.2.7
1208     */
1209     OUString intern() const
1210     {
1211         rtl_uString * pNew = 0;
1212         rtl_uString_intern( &pNew, pData );
1213 #if defined EXCEPTIONS_OFF
1214         OSL_ASSERT(pNew != NULL);
1215 #else
1216         if (pNew == 0) {
1217             throw std::bad_alloc();
1218         }
1219 #endif
1220         return OUString( pNew, (DO_NOT_ACQUIRE *)0 );
1221     }
1222 
1223     /**
1224        Return a canonical representation for a converted string.
1225 
1226        A pool of strings, initially empty is maintained privately
1227        by the string class. On invocation, if present in the pool
1228        the original string will be returned. Otherwise this string,
1229        or a copy thereof will be added to the pool and returned.
1230 
1231        @param    value           a 8-Bit character array.
1232        @param    length          the number of character which should be converted.
1233                                  The 8-Bit character array length must be
1234                                  greater or equal than this value.
1235        @param    encoding        the text encoding from which the 8-Bit character
1236                                  sequence should be converted.
1237        @param    convertFlags    flags which controls the conversion.
1238                                  see RTL_TEXTTOUNICODE_FLAGS_...
1239        @param    pInfo           pointer to return conversion status or NULL.
1240 
1241        @return
1242        a version of the converted string from the pool.
1243 
1244        @exception std::bad_alloc is thrown if an out-of-memory condition occurs
1245 
1246        @since UDK 3.2.7
1247     */
1248     static OUString intern( const sal_Char * value, sal_Int32 length,
1249                             rtl_TextEncoding encoding,
1250                             sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS,
1251                             sal_uInt32 *pInfo = NULL )
1252     {
1253         rtl_uString * pNew = 0;
1254         rtl_uString_internConvert( &pNew, value, length, encoding,
1255                                    convertFlags, pInfo );
1256 #if defined EXCEPTIONS_OFF
1257         OSL_ASSERT(pNew != NULL);
1258 #else
1259         if (pNew == 0) {
1260             throw std::bad_alloc();
1261         }
1262 #endif
1263         return OUString( pNew, (DO_NOT_ACQUIRE *)0 );
1264     }
1265 
1266     /**
1267       Converts to an OString, signalling failure.
1268 
1269       @param pTarget
1270       An out parameter receiving the converted OString.  Must not be null; the
1271       contents are not modified if conversion fails (convertToOString returns
1272       false).
1273 
1274       @param nEncoding
1275       The text encoding to convert into.  Must be an octet encoding (i.e.,
1276       rtl_isOctetTextEncoding(nEncoding) must return true).
1277 
1278       @param nFlags
1279       A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the
1280       conversion (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH
1281       need not be included, it is implicitly assumed.  Typical uses are either
1282       RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1283       RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot
1284       be converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS
1285       (make a best efforts conversion).
1286 
1287       @return
1288       True if the conversion succeeded, false otherwise.
1289      */
1290     inline bool convertToString(OString * pTarget, rtl_TextEncoding nEncoding,
1291                                 sal_uInt32 nFlags) const
1292     {
1293         return rtl_convertUStringToString(&pTarget->pData, pData->buffer,
1294                                             pData->length, nEncoding, nFlags);
1295     }
1296 
1297     /** Iterate through this string based on code points instead of UTF-16 code
1298         units.
1299 
1300         See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for
1301         definitions of the various terms used in this description.
1302 
1303         This string is interpreted as a sequence of zero or more UTF-16 code
1304         units.  For each index into this sequence (from zero to one less than
1305         the length of the sequence, inclusive), a code point represented
1306         starting at the given index is computed as follows:
1307 
1308         - If the UTF-16 code unit addressed by the index constitutes a
1309         well-formed UTF-16 code unit sequence, the computed code point is the
1310         scalar value encoded by that UTF-16 code unit sequence.
1311 
1312         - Otherwise, if the index is at least two UTF-16 code units away from
1313         the end of the sequence, and the sequence of two UTF-16 code units
1314         addressed by the index constitutes a well-formed UTF-16 code unit
1315         sequence, the computed code point is the scalar value encoded by that
1316         UTF-16 code unit sequence.
1317 
1318         - Otherwise, the computed code point is the UTF-16 code unit addressed
1319         by the index.  (This last case catches unmatched surrogates as well as
1320         indices pointing into the middle of surrogate pairs.)
1321 
1322         @param indexUtf16
1323         pointer to a UTF-16 based index into this string; must not be null.  On
1324         entry, the index must be in the range from zero to the length of this
1325         string (in UTF-16 code units), inclusive.  Upon successful return, the
1326         index will be updated to address the UTF-16 code unit that is the given
1327         incrementCodePoints away from the initial index.
1328 
1329         @param incrementCodePoints
1330         the number of code points to move the given *indexUtf16.  If
1331         non-negative, moving is done after determining the code point at the
1332         index.  If negative, moving is done before determining the code point
1333         at the (then updated) index.  The value must be such that the resulting
1334         UTF-16 based index is in the range from zero to the length of this
1335         string (in UTF-16 code units), inclusive.
1336 
1337         @return
1338         the code point (an integer in the range from 0 to 0x10FFFF, inclusive)
1339         that is represented within this string starting at the index computed as
1340         follows:  If incrementCodePoints is non-negative, the index is the
1341         initial value of *indexUtf16; if incrementCodePoints is negative, the
1342         index is the updated value of *indexUtf16.  In either case, the computed
1343         index must be in the range from zero to one less than the length of this
1344         string (in UTF-16 code units), inclusive.
1345 
1346         @since UDK 3.2.7
1347     */
1348     inline sal_uInt32 iterateCodePoints(
1349         sal_Int32 * indexUtf16, sal_Int32 incrementCodePoints = 1) const
1350     {
1351         return rtl_uString_iterateCodePoints(
1352             pData, indexUtf16, incrementCodePoints);
1353     }
1354 
1355     /**
1356       Returns the string representation of the sal_Bool argument.
1357 
1358       If the sal_Bool is true, the string "true" is returned.
1359       If the sal_Bool is false, the string "false" is returned.
1360       This function can't be used for language specific conversion.
1361 
1362       @param    b   a sal_Bool.
1363       @return   a string with the string representation of the argument.
1364     */
1365     static OUString valueOf( sal_Bool b ) SAL_THROW(())
1366     {
1367         sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFBOOLEAN];
1368         rtl_uString* pNewData = 0;
1369         rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfBoolean( aBuf, b ) );
1370         return OUString( pNewData, (DO_NOT_ACQUIRE*)0 );
1371     }
1372 
1373     /**
1374       Returns the string representation of the char argument.
1375 
1376       @param    c   a character.
1377       @return   a string with the string representation of the argument.
1378     */
1379     static OUString valueOf( sal_Unicode c ) SAL_THROW(())
1380     {
1381         return OUString( &c, 1 );
1382     }
1383 
1384     /**
1385       Returns the string representation of the int argument.
1386 
1387       This function can't be used for language specific conversion.
1388 
1389       @param    i           a int32.
1390       @param    radix       the radix (between 2 and 36)
1391       @return   a string with the string representation of the argument.
1392     */
1393     static OUString valueOf( sal_Int32 i, sal_Int16 radix = 10 ) SAL_THROW(())
1394     {
1395         sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFINT32];
1396         rtl_uString* pNewData = 0;
1397         rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfInt32( aBuf, i, radix ) );
1398         return OUString( pNewData, (DO_NOT_ACQUIRE*)0 );
1399     }
1400 
1401     /**
1402       Returns the string representation of the long argument.
1403 
1404       This function can't be used for language specific conversion.
1405 
1406       @param    ll          a int64.
1407       @param    radix       the radix (between 2 and 36)
1408       @return   a string with the string representation of the argument.
1409     */
1410     static OUString valueOf( sal_Int64 ll, sal_Int16 radix = 10 ) SAL_THROW(())
1411     {
1412         sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFINT64];
1413         rtl_uString* pNewData = 0;
1414         rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfInt64( aBuf, ll, radix ) );
1415         return OUString( pNewData, (DO_NOT_ACQUIRE*)0 );
1416     }
1417 
1418     /**
1419       Returns the string representation of the float argument.
1420 
1421       This function can't be used for language specific conversion.
1422 
1423       @param    f           a float.
1424       @return   a string with the string representation of the argument.
1425     */
1426     static OUString valueOf( float f ) SAL_THROW(())
1427     {
1428         sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFFLOAT];
1429         rtl_uString* pNewData = 0;
1430         rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfFloat( aBuf, f ) );
1431         return OUString( pNewData, (DO_NOT_ACQUIRE*)0 );
1432     }
1433 
1434     /**
1435       Returns the string representation of the double argument.
1436 
1437       This function can't be used for language specific conversion.
1438 
1439       @param    d           a double.
1440       @return   a string with the string representation of the argument.
1441     */
1442     static OUString valueOf( double d ) SAL_THROW(())
1443     {
1444         sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFDOUBLE];
1445         rtl_uString* pNewData = 0;
1446         rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfDouble( aBuf, d ) );
1447         return OUString( pNewData, (DO_NOT_ACQUIRE*)0 );
1448     }
1449 
1450     /**
1451       Returns a OUString copied without conversion from an ASCII
1452       character string.
1453 
1454       Since this method is optimized for performance, the ASCII character
1455       values are not converted in any way. The caller has to make sure that
1456       all ASCII characters are in the allowed range between 0 and
1457       127. The ASCII string must be NULL-terminated.
1458 
1459       @param    value       the 8-Bit ASCII character string
1460       @return   a string with the string representation of the argument.
1461      */
1462     static OUString createFromAscii( const sal_Char * value ) SAL_THROW(())
1463     {
1464         rtl_uString* pNew = 0;
1465         rtl_uString_newFromAscii( &pNew, value );
1466         return OUString( pNew, (DO_NOT_ACQUIRE*)0 );
1467     }
1468 };
1469 
1470 /* ======================================================================= */
1471 
1472 /** A helper to use OUStrings with hash maps.
1473 
1474     Instances of this class are unary function objects that can be used as
1475     hash function arguments to STLPort's hash_map and similar constructs.
1476  */
1477 struct OUStringHash
1478 {
1479     /** Compute a hash code for a string.
1480 
1481         @param rString
1482         a string.
1483 
1484         @return
1485         a hash code for the string.  This hash code should not be stored
1486         persistently, as its computation may change in later revisions.
1487      */
1488     size_t operator()(const rtl::OUString& rString) const
1489         { return (size_t)rString.hashCode(); }
1490 };
1491 
1492 /* ======================================================================= */
1493 
1494 /** Convert an OString to an OUString, using a specific text encoding.
1495 
1496     The lengths of the two strings may differ (e.g., for double-byte
1497     encodings, UTF-7, UTF-8).
1498 
1499     @param rStr
1500     an OString to convert.
1501 
1502     @param encoding
1503     the text encoding to use for conversion.
1504 
1505     @param convertFlags
1506     flags which control the conversion.  Either use
1507     OSTRING_TO_OUSTRING_CVTFLAGS, or see
1508     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1509     details.
1510  */
1511 inline OUString OStringToOUString( const OString & rStr,
1512                                    rtl_TextEncoding encoding,
1513                                    sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS )
1514 {
1515     return OUString( rStr.getStr(), rStr.getLength(), encoding, convertFlags );
1516 }
1517 
1518 /** Convert an OUString to an OString, using a specific text encoding.
1519 
1520     The lengths of the two strings may differ (e.g., for double-byte
1521     encodings, UTF-7, UTF-8).
1522 
1523     @param rStr
1524     an OUString to convert.
1525 
1526     @param encoding
1527     the text encoding to use for conversion.
1528 
1529     @param convertFlags
1530     flags which control the conversion.  Either use
1531     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1532     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1533     details.
1534  */
1535 inline OString OUStringToOString( const OUString & rUnicode,
1536                                   rtl_TextEncoding encoding,
1537                                   sal_uInt32 convertFlags = OUSTRING_TO_OSTRING_CVTFLAGS )
1538 {
1539     return OString( rUnicode.getStr(), rUnicode.getLength(), encoding, convertFlags );
1540 }
1541 
1542 /* ======================================================================= */
1543 
1544 } /* Namespace */
1545 
1546 #endif /* __cplusplus */
1547 
1548 #endif /* _RTL_USTRING_HXX */
1549