1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2/*
3 * This file is part of the LibreOffice project.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 * This file incorporates work covered by the following license notice:
10 *
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 */
19
20#ifndef INCLUDED_RTL_STRING_HXX
21#define INCLUDED_RTL_STRING_HXX
22
23#include <sal/config.h>
24
25#include <cassert>
26#include <new>
27#include <ostream>
28#include <string.h>
29
30#include <osl/diagnose.h>
31#include <rtl/textenc.h>
32#include <rtl/string.h>
33#include <rtl/stringutils.hxx>
34
35#ifdef RTL_FAST_STRING
36#include <rtl/stringconcat.hxx>
37#endif
38
39#include <sal/log.hxx>
40
41// The unittest uses slightly different code to help check that the proper
42// calls are made. The class is put into a different namespace to make
43// sure the compiler generates a different (if generating also non-inline)
44// copy of the function and does not merge them together. The class
45// is "brought" into the proper rtl namespace by a typedef below.
46#ifdef RTL_STRING_UNITTEST
47#define rtl rtlunittest
48#endif
49
50namespace rtl
51{
52
53/// @cond INTERNAL
54#ifdef RTL_STRING_UNITTEST
55#undef rtl
56// helper macro to make functions appear more readable
57#define RTL_STRING_CONST_FUNCTION rtl_string_unittest_const_literal_function = true;
58#else
59#define RTL_STRING_CONST_FUNCTION
60#endif
61/// @endcond
62
63/* ======================================================================= */
64
65/**
66 This String class provide base functionality for C++ like 8-Bit
67 character array handling. The advantage of this class is, that it
68 handle all the memory managament for you - and it do it
69 more efficient. If you assign a string to another string, the
70 data of both strings are shared (without any copy operation or
71 memory allocation) as long as you do not change the string. This class
72 stores also the length of the string, so that many operations are
73 faster as the C-str-functions.
74
75 This class provide only readonly string handling. So you could create
76 a string and you could only query the content from this string.
77 It provide also functionality to change the string, but this results
78 in every case in a new string instance (in the most cases with an
79 memory allocation). You don't have functionality to change the
80 content of the string. If you want change the string content, than
81 you should us the OStringBuffer class, which provide these
82 functionality and avoid to much memory allocation.
83
84 The design of this class is similar to the string classes in Java
85 and so more people should have fewer understanding problems when they
86 use this class.
87*/
88
89class SAL_WARN_UNUSED OString
90{
91public:
92 /// @cond INTERNAL
93 rtl_String * pData;
94 /// @endcond
95
96 /**
97 New string containing no characters.
98 */
99 OString() SAL_THROW(())
100 {
101 pData = 0;
102 rtl_string_new( &pData );
103 }
104
105 /**
106 New string from OString.
107
108 @param str a OString.
109 */
110 OString( const OString & str ) SAL_THROW(())
111 {
112 pData = str.pData;
113 rtl_string_acquire( pData );
114 }
115
116 /**
117 New string from OString data.
118
119 @param str a OString data.
120 */
121 OString( rtl_String * str ) SAL_THROW(())
122 {
123 pData = str;
124 rtl_string_acquire( pData );
125 }
126
127 /** New string from OString data without acquiring it. Takeover of ownership.
128
129 The SAL_NO_ACQUIRE dummy parameter is only there to distinguish this
130 from other constructors.
131
132 @param str a OString data.
133 */
134 inline OString( rtl_String * str, __sal_NoAcquire ) SAL_THROW(())
135 {
136 pData = str;
137 }
138
139 /**
140 New string from a single character.
141
142 @param value a character.
143 */
144 explicit OString( sal_Char value ) SAL_THROW(())
145 : pData (0)
146 {
147 rtl_string_newFromStr_WithLength( &pData, &value, 1 );
148 }
149
150 /**
151 New string from a character buffer array.
152
153 Note: The argument type is always either char* or const char*. The template is
154 used only for technical reasons, as is the second argument.
155
156 @param value a NULL-terminated character array.
157 */
158 template< typename T >
159 OString( const T& value, typename internal::CharPtrDetector< T, internal::Dummy >::Type = internal::Dummy() ) SAL_THROW(())
160 {
161 pData = 0;
162 rtl_string_newFromStr( &pData, value );
163 }
164
165 template< typename T >
166 OString( T& value, typename internal::NonConstCharArrayDetector< T, internal::Dummy >::Type = internal::Dummy() ) SAL_THROW(())
167 {
168 pData = 0;
169 rtl_string_newFromStr( &pData, value );
170 }
171
172 /**
173 New string from a string literal.
174
175 If there are any embedded \0's in the string literal, the result is undefined.
176 Use the overload that explicitly accepts length.
177
178 @since LibreOffice 3.6
179
180 @param literal a string literal
181 */
182 template< typename T >
183 OString( T& literal, typename internal::ConstCharArrayDetector< T, internal::Dummy >::Type = internal::Dummy() ) SAL_THROW(())
184 {
185 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
186 pData = 0;
187 if( internal::ConstCharArrayDetector< T, void >::size - 1 == 0 ) // empty string
188 rtl_string_new( &pData );
189 else
190 rtl_string_newFromLiteral( &pData, literal, internal::ConstCharArrayDetector< T, void >::size - 1, 0 );
191#ifdef RTL_STRING_UNITTEST
192 rtl_string_unittest_const_literal = true;
193#endif
194 }
195
196 /**
197 New string from a character buffer array.
198
199 @param value a character array.
200 @param length the number of character which should be copied.
201 The character array length must be greater or
202 equal than this value.
203 */
204 OString( const sal_Char * value, sal_Int32 length ) SAL_THROW(())
205 {
206 pData = 0;
207 rtl_string_newFromStr_WithLength( &pData, value, length );
208 }
209
210 /**
211 New string from a Unicode character buffer array.
212
213 @param value a Unicode character array.
214 @param length the number of character which should be converted.
215 The Unicode character array length must be
216 greater or equal than this value.
217 @param encoding the text encoding in which the Unicode character
218 sequence should be converted.
219 @param convertFlags flags which controls the conversion.
220 see RTL_UNICODETOTEXT_FLAGS_...
221
222 @exception std::bad_alloc is thrown if an out-of-memory condition occurs
223 */
224 OString( const sal_Unicode * value, sal_Int32 length,
225 rtl_TextEncoding encoding,
226 sal_uInt32 convertFlags = OUSTRING_TO_OSTRING_CVTFLAGS )
227 {
228 pData = 0;
229 rtl_uString2String( &pData, value, length, encoding, convertFlags );
230 if (pData == 0) {
231 throw std::bad_alloc();
232 }
233 }
234
235#ifdef RTL_FAST_STRING
236 /**
237 @overload
238 @internal
239 */
240 template< typename T1, typename T2 >
241 OString( const OStringConcat< T1, T2 >& c )
242 {
243 const sal_Int32 l = c.length();
244 pData = rtl_string_alloc( l );
245 if (l != 0)
246 {
247 char* end = c.addData( pData->buffer );
248 pData->length = end - pData->buffer;
249 *end = '\0';
250 }
251 }
252#endif
253
254 /**
255 Release the string data.
256 */
257 ~OString() SAL_THROW(())
258 {
259 rtl_string_release( pData );
260 }
261
262 /**
263 Assign a new string.
264
265 @param str a OString.
266 */
267 OString & operator=( const OString & str ) SAL_THROW(())
268 {
269 rtl_string_assign( &pData, str.pData );
270 return *this;
271 }
272
273 /**
274 @overload
275 This function accepts an ASCII string literal as its argument.
276 @since LibreOffice 3.6
277 */
278 template< typename T >
279 typename internal::ConstCharArrayDetector< T, OString& >::Type operator=( T& literal ) SAL_THROW(())
280 {
281 RTL_STRING_CONST_FUNCTION
282 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
283 if( internal::ConstCharArrayDetector< T, void >::size - 1 == 0 ) // empty string
284 rtl_string_new( &pData );
285 else
286 rtl_string_newFromLiteral( &pData, literal, internal::ConstCharArrayDetector< T, void >::size - 1, 0 );
287 return *this;
288 }
289
290 /**
291 Append a string to this string.
292
293 @param str a OString.
294 */
295 OString & operator+=( const OString & str ) SAL_THROW(())
296 {
297 rtl_string_newConcat( &pData, pData, str.pData );
298 return *this;
299 }
300
301#ifdef RTL_FAST_STRING
302 /**
303 @overload
304 @internal
305 */
306 template< typename T1, typename T2 >
307 OString& operator+=( const OStringConcat< T1, T2 >& c )
308 {
309 const int l = c.length();
310 if( l == 0 )
311 return *this;
312 rtl_string_ensureCapacity( &pData, pData->length + l );
313 char* end = c.addData( pData->buffer + pData->length );
314 *end = '\0';
315 pData->length = end - pData->buffer;
316 return *this;
317 }
318#endif
319 /**
320 Returns the length of this string.
321
322 The length is equal to the number of characters in this string.
323
324 @return the length of the sequence of characters represented by this
325 object.
326 */
327 sal_Int32 getLength() const SAL_THROW(()) { return pData->length; }
328
329 /**
330 Checks if a string is empty.
331
332 @return true if the string is empty;
333 false, otherwise.
334
335 @since LibreOffice 3.4
336 */
337 bool isEmpty() const SAL_THROW(())
338 {
339 return pData->length == 0;
340 }
341
342 /**
343 Returns a pointer to the characters of this string.
344
345 <p>The returned pointer is guaranteed to point to a null-terminated byte
346 string. But note that this string object may contain embedded null
347 characters, which will thus also be embedded in the returned
348 null-terminated byte string.</p>
349
350 @return a pointer to a null-terminated byte string representing the
351 characters of this string object.
352 */
353 const sal_Char * getStr() const SAL_THROW(()) { return pData->buffer; }
354
355 /**
356 Access to individual characters.
357
358 @param index must be non-negative and less than length.
359
360 @return the character at the given index.
361
362 @since LibreOffice 3.5
363 */
364 sal_Char operator [](sal_Int32 index) const {
365 // silence spurious -Werror=strict-overflow warnings from GCC 4.8.2
366 assert(index >= 0 && static_cast<sal_uInt32>(index) < static_cast<sal_uInt32>(getLength()));
367 return getStr()[index];
368 }
369
370 /**
371 Compares two strings.
372
373 The comparison is based on the numeric value of each character in
374 the strings and return a value indicating their relationship.
375 This function can't be used for language specific sorting.
376
377 @param str the object to be compared.
378 @return 0 - if both strings are equal
379 < 0 - if this string is less than the string argument
380 > 0 - if this string is greater than the string argument
381 */
382 sal_Int32 compareTo( const OString & str ) const SAL_THROW(())
383 {
384 return rtl_str_compare_WithLength( pData->buffer, pData->length,
385 str.pData->buffer, str.pData->length );
386 }
387
388 /**
389 Compares two strings with an maximum count of characters.
390
391 The comparison is based on the numeric value of each character in
392 the strings and return a value indicating their relationship.
393 This function can't be used for language specific sorting.
394
395 @param rObj the object to be compared.
396 @param maxLength the maximum count of characters to be compared.
397 @return 0 - if both strings are equal
398 < 0 - if this string is less than the string argument
399 > 0 - if this string is greater than the string argument
400 */
401 sal_Int32 compareTo( const OString & rObj, sal_Int32 maxLength ) const SAL_THROW(())
402 {
403 return rtl_str_shortenedCompare_WithLength( pData->buffer, pData->length,
404 rObj.pData->buffer, rObj.pData->length, maxLength );
405 }
406
407 /**
408 Compares two strings in reverse order.
409
410 The comparison is based on the numeric value of each character in
411 the strings and return a value indicating their relationship.
412 This function can't be used for language specific sorting.
413
414 @param str the object to be compared.
415 @return 0 - if both strings are equal
416 < 0 - if this string is less than the string argument
417 > 0 - if this string is greater than the string argument
418 */
419 sal_Int32 reverseCompareTo( const OString & str ) const SAL_THROW(())
420 {
421 return rtl_str_reverseCompare_WithLength( pData->buffer, pData->length,
422 str.pData->buffer, str.pData->length );
423 }
424
425 /**
426 Perform a comparison of two strings.
427
428 The result is true if and only if second string
429 represents the same sequence of characters as the first string.
430 This function can't be used for language specific comparison.
431
432 @param str the object to be compared.
433 @return true if the strings are equal;
434 false, otherwise.
435 */
436 bool equals( const OString & str ) const SAL_THROW(())
437 {
438 if ( pData->length != str.pData->length )
439 return false;
440 if ( pData == str.pData )
441 return true;
442 return rtl_str_reverseCompare_WithLength( pData->buffer, pData->length,
443 str.pData->buffer, str.pData->length ) == 0;
444 }
445
446 /**
447 Perform a comparison of two strings.
448
449 The result is true if and only if second string
450 represents the same sequence of characters as the first string.
451 The ASCII string must be NULL-terminated and must be greater or
452 equal as length.
453 This function can't be used for language specific comparison.
454
455
456 @param value a character array.
457 @param length the length of the character array.
458 @return true if the strings are equal;
459 false, otherwise.
460 */
461 bool equalsL( const sal_Char* value, sal_Int32 length ) const SAL_THROW(())
462 {
463 if ( pData->length != length )
464 return false;
465
466 return rtl_str_reverseCompare_WithLength( pData->buffer, pData->length,
467 value, length ) == 0;
468 }
469
470 /**
471 Perform a ASCII lowercase comparison of two strings.
472
473 The result is true if and only if second string
474 represents the same sequence of characters as the first string,
475 ignoring the case.
476 Character values between 65 and 90 (ASCII A-Z) are interpreted as
477 values between 97 and 122 (ASCII a-z).
478 This function can't be used for language specific comparison.
479
480 @param str the object to be compared.
481 @return true if the strings are equal;
482 false, otherwise.
483 */
484 bool equalsIgnoreAsciiCase( const OString & str ) const SAL_THROW(())
485 {
486 if ( pData->length != str.pData->length )
487 return false;
488 if ( pData == str.pData )
489 return true;
490 return rtl_str_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
491 str.pData->buffer, str.pData->length ) == 0;
492 }
493
494 /**
495 Perform a ASCII lowercase comparison of two strings.
496
497 The result is true if and only if second string
498 represents the same sequence of characters as the first string,
499 ignoring the case.
500 Character values between 65 and 90 (ASCII A-Z) are interpreted as
501 values between 97 and 122 (ASCII a-z).
502 Since this method is optimized for performance, the ASCII character
503 values are not converted in any way. The caller has to make sure that
504 all ASCII characters are in the allowed range between 0 and
505 127. The ASCII string must be NULL-terminated.
506 This function can't be used for language specific comparison.
507
508 Note: The argument type is always either char* or const char*, the return type is bool.
509 The template is used only for technical reasons.
510
511 @param asciiStr the 8-Bit ASCII character string to be compared.
512 @return true if the strings are equal;
513 false, otherwise.
514 */
515 template< typename T >
516 typename internal::CharPtrDetector< T, bool >::Type equalsIgnoreAsciiCase( const T& asciiStr ) const SAL_THROW(())
517 {
518 return rtl_str_compareIgnoreAsciiCase( pData->buffer, asciiStr ) == 0;
519 }
520
521 template< typename T >
522 typename internal::NonConstCharArrayDetector< T, bool >::Type equalsIgnoreAsciiCase( T& asciiStr ) const SAL_THROW(())
523 {
524 return rtl_str_compareIgnoreAsciiCase( pData->buffer, asciiStr ) == 0;
525 }
526
527 /**
528 @overload
529 This function accepts an ASCII string literal as its argument.
530 @since LibreOffice 3.6
531 */
532 template< typename T >
533 typename internal::ConstCharArrayDetector< T, bool >::Type equalsIgnoreAsciiCase( T& literal ) const SAL_THROW(())
534 {
535 RTL_STRING_CONST_FUNCTION
536 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
537 if ( pData->length != internal::ConstCharArrayDetector< T, void >::size - 1 )
538 return false;
539 return rtl_str_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
540 literal, internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
541 }
542
543 /**
544 Perform a ASCII lowercase 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 ignoring the case.
549 Character values between 65 and 90 (ASCII A-Z) are interpreted as
550 values between 97 and 122 (ASCII a-z).
551 Since this method is optimized for performance, the ASCII character
552 values are not converted in any way. The caller has to make sure that
553 all ASCII characters are in the allowed range between 0 and
554 127. The ASCII string must be greater or equal in length as asciiStrLength.
555 This function can't be used for language specific comparison.
556
557 @param asciiStr the 8-Bit ASCII character string to be compared.
558 @param asciiStrLength the length of the ascii string
559 @return true if the strings are equal;
560 false, otherwise.
561 */
562 bool equalsIgnoreAsciiCaseL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
563 {
564 if ( pData->length != asciiStrLength )
565 return false;
566
567 return rtl_str_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
568 asciiStr, asciiStrLength ) == 0;
569 }
570
571 /**
572 Match against a substring appearing in this string.
573
574 The result is true if and only if the second string appears as a substring
575 of this string, at the given position.
576 This function can't be used for language specific comparison.
577
578 @param str the object (substring) to be compared.
579 @param fromIndex the index to start the comparion from.
580 The index must be greater or equal than 0
581 and less or equal as the string length.
582 @return true if str match with the characters in the string
583 at the given position;
584 false, otherwise.
585 */
586 bool match( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
587 {
588 return rtl_str_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
589 str.pData->buffer, str.pData->length, str.pData->length ) == 0;
590 }
591
592 /**
593 @overload
594 This function accepts an ASCII string literal as its argument.
595 @since LibreOffice 3.6
596 */
597 template< typename T >
598 typename internal::ConstCharArrayDetector< T, bool >::Type match( T& literal, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
599 {
600 RTL_STRING_CONST_FUNCTION
601 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
602 return rtl_str_shortenedCompare_WithLength(
603 pData->buffer + fromIndex, pData->length - fromIndex,
604 literal, internal::ConstCharArrayDetector< T, void >::size - 1, internal::ConstCharArrayDetector< T, void >::size - 1) == 0;
605 }
606
607 /**
608 Match against a substring appearing in this string.
609
610 @param str the substring to be compared; must not be null and must point
611 to memory of at least strLength bytes
612
613 @param strLength the length of the substring; must be non-negative
614
615 @param fromIndex the index into this string to start the comparison at;
616 must be non-negative and not greater than this string's length
617
618 @return true if and only if the given str is contained as a substring of
619 this string at the given fromIndex
620
621 @since LibreOffice 3.6
622 */
623 bool matchL(
624 char const * str, sal_Int32 strLength, sal_Int32 fromIndex = 0)
625 const
626 {
627 return rtl_str_shortenedCompare_WithLength(
628 pData->buffer + fromIndex, pData->length - fromIndex,
629 str, strLength, strLength) == 0;
630 }
631
632 // This overload is left undefined, to detect calls of matchL that
633 // erroneously use RTL_CONSTASCII_USTRINGPARAM instead of
634 // RTL_CONSTASCII_STRINGPARAM (but would lead to ambiguities on 32 bit
635 // platforms):
636#if SAL_TYPES_SIZEOFLONG == 8
637 void matchL(char const *, sal_Int32, rtl_TextEncoding) const;
638#endif
639
640 /**
641 Match against a substring appearing in this string, ignoring the case of
642 ASCII letters.
643
644 The result is true if and only if the second string appears as a substring
645 of this string, at the given position.
646 Character values between 65 and 90 (ASCII A-Z) are interpreted as
647 values between 97 and 122 (ASCII a-z).
648 This function can't be used for language specific comparison.
649
650 @param str the object (substring) to be compared.
651 @param fromIndex the index to start the comparion from.
652 The index must be greater or equal than 0
653 and less or equal as the string length.
654 @return true if str match with the characters in the string
655 at the given position;
656 false, otherwise.
657 */
658 bool matchIgnoreAsciiCase( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
659 {
660 return rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
661 str.pData->buffer, str.pData->length,
662 str.pData->length ) == 0;
663 }
664
665 /**
666 @overload
667 This function accepts an ASCII string literal as its argument.
668 @since LibreOffice 3.6
669 */
670 template< typename T >
671 typename internal::ConstCharArrayDetector< T, bool >::Type matchIgnoreAsciiCase( T& literal, sal_Int32 fromIndex = 0 ) const
672 {
673 RTL_STRING_CONST_FUNCTION
674 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
675 return rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
676 literal, internal::ConstCharArrayDetector< T, void >::size - 1, internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
677 }
678
679 /**
680 Check whether this string starts with a given substring.
681
682 @param str the substring to be compared
683
684 @param rest if non-null, and this function returns true, then assign a
685 copy of the remainder of this string to *rest. Available since
686 LibreOffice 4.2
687
688 @return true if and only if the given str appears as a substring at the
689 start of this string
690
691 @since LibreOffice 4.0
692 */
693 bool startsWith(OString const & str, OString * rest = 0) const {
694 bool b = match(str, 0);
695 if (b && rest != 0) {
696 *rest = copy(str.getLength());
697 }
698 return b;
699 }
700
701 /**
702 @overload
703 This function accepts an ASCII string literal as its argument.
704 @since LibreOffice 4.0
705 */
706 template< typename T >
707 typename internal::ConstCharArrayDetector< T, bool >::Type startsWith(
708 T & literal, OString * rest = 0) const
709 {
710 RTL_STRING_CONST_FUNCTION
711 bool b = match(literal, 0);
712 if (b && rest != 0) {
713 *rest = copy(internal::ConstCharArrayDetector< T, void >::size - 1);
714 }
715 return b;
716 }
717
718 /**
719 Check whether this string ends with a given substring.
720
721 @param str the substring to be compared
722
723 @param rest if non-null, and this function returns true, then assign a
724 copy of the remainder of this string to *rest. Available since
725 LibreOffice 4.2
726
727 @return true if and only if the given str appears as a substring at the
728 end of this string
729
730 @since LibreOffice 3.6
731 */
732 bool endsWith(OString const & str, OString * rest = 0) const {
733 bool b = str.getLength() <= getLength()
734 && match(str, getLength() - str.getLength());
735 if (b && rest != 0) {
736 *rest = copy(0, getLength() - str.getLength());
737 }
738 return b;
739 }
740
741 /**
742 @overload
743 This function accepts an ASCII string literal as its argument.
744 @since LibreOffice 3.6
745 */
746 template< typename T >
747 typename internal::ConstCharArrayDetector< T, bool >::Type endsWith(
748 T & literal, OString * rest = 0) const
749 {
750 RTL_STRING_CONST_FUNCTION
751 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
752 bool b = internal::ConstCharArrayDetector< T, void >::size - 1 <= getLength()
753 && match(literal, getLength() - ( internal::ConstCharArrayDetector< T, void >::size - 1 ));
754 if (b && rest != 0) {
755 *rest = copy(
756 0,
757 (getLength()
758 - (internal::ConstCharArrayDetector< T, void >::size - 1)));
759 }
760 return b;
761 }
762
763 /**
764 Check whether this string ends with a given substring.
765
766 @param str the substring to be compared; must not be null and must point
767 to memory of at least strLength bytes
768
769 @param strLength the length of the substring; must be non-negative
770
771 @return true if and only if the given str appears as a substring at the
772 end of this string
773
774 @since LibreOffice 3.6
775 */
776 bool endsWithL(char const * str, sal_Int32 strLength) const {
777 return strLength <= getLength()
778 && matchL(str, strLength, getLength() - strLength);
779 }
780
781 friend bool operator == ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
782 { return rStr1.equals(rStr2); }
783 friend bool operator != ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
784 { return !(operator == ( rStr1, rStr2 )); }
785 friend bool operator < ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
786 { return rStr1.compareTo( rStr2 ) < 0; }
787 friend bool operator > ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
788 { return rStr1.compareTo( rStr2 ) > 0; }
789 friend bool operator <= ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
790 { return rStr1.compareTo( rStr2 ) <= 0; }
791 friend bool operator >= ( const OString& rStr1, const OString& rStr2 ) SAL_THROW(())
792 { return rStr1.compareTo( rStr2 ) >= 0; }
793
794 template< typename T >
795 friend typename internal::CharPtrDetector< T, bool >::Type operator==( const OString& rStr1, const T& value ) SAL_THROW(())
796 {
797 return rStr1.compareTo( value ) == 0;
798 }
799
800 template< typename T >
801 friend typename internal::NonConstCharArrayDetector< T, bool >::Type operator==( const OString& rStr1, T& value ) SAL_THROW(())
802 {
803 return rStr1.compareTo( value ) == 0;
804 }
805
806 template< typename T >
807 friend typename internal::CharPtrDetector< T, bool >::Type operator==( const T& value, const OString& rStr2 ) SAL_THROW(())
808 {
809 return rStr2.compareTo( value ) == 0;
810 }
811
812 template< typename T >
813 friend typename internal::NonConstCharArrayDetector< T, bool >::Type operator==( T& value, const OString& rStr2 ) SAL_THROW(())
814 {
815 return rStr2.compareTo( value ) == 0;
816 }
817
818 /**
819 @overload
820 This function accepts an ASCII string literal as its argument.
821 @since LibreOffice 3.6
822 */
823 template< typename T >
824 friend typename internal::ConstCharArrayDetector< T, bool >::Type operator==( const OString& rStr, T& literal ) SAL_THROW(())
825 {
826 RTL_STRING_CONST_FUNCTION
827 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
828 return rStr.getLength() == internal::ConstCharArrayDetector< T, void >::size - 1
829 && rtl_str_compare_WithLength( rStr.pData->buffer, rStr.pData->length, literal,
830 internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
831 }
832
833 /**
834 @overload
835 This function accepts an ASCII string literal as its argument.
836 @since LibreOffice 3.6
837 */
838 template< typename T >
839 friend typename internal::ConstCharArrayDetector< T, bool >::Type operator==( T& literal, const OString& rStr ) SAL_THROW(())
840 {
841 RTL_STRING_CONST_FUNCTION
842 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
843 return rStr.getLength() == internal::ConstCharArrayDetector< T, void >::size - 1
844 && rtl_str_compare_WithLength( rStr.pData->buffer, rStr.pData->length, literal,
845 internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
846 }
847
848 template< typename T >
849 friend typename internal::CharPtrDetector< T, bool >::Type operator!=( const OString& rStr1, const T& value ) SAL_THROW(())
850 {
851 return !(operator == ( rStr1, value ));
852 }
853
854 template< typename T >
855 friend typename internal::NonConstCharArrayDetector< T, bool >::Type operator!=( const OString& rStr1, T& value ) SAL_THROW(())
856 {
857 return !(operator == ( rStr1, value ));
858 }
859
860 template< typename T >
861 friend typename internal::CharPtrDetector< T, bool >::Type operator!=( const T& value, const OString& rStr2 ) SAL_THROW(())
862 {
863 return !(operator == ( value, rStr2 ));
864 }
865
866 template< typename T >
867 friend typename internal::NonConstCharArrayDetector< T, bool >::Type operator!=( T& value, const OString& rStr2 ) SAL_THROW(())
868 {
869 return !(operator == ( value, rStr2 ));
870 }
871
872 /**
873 @overload
874 This function accepts an ASCII string literal as its argument.
875 @since LibreOffice 3.6
876 */
877 template< typename T >
878 friend typename internal::ConstCharArrayDetector< T, bool >::Type operator!=( const OString& rStr, T& literal ) SAL_THROW(())
879 {
880 return !( rStr == literal );
881 }
882
883 /**
884 @overload
885 This function accepts an ASCII string literal as its argument.
886 @since LibreOffice 3.6
887 */
888 template< typename T >
889 friend typename internal::ConstCharArrayDetector< T, bool >::Type operator!=( T& literal, const OString& rStr ) SAL_THROW(())
890 {
891 return !( literal == rStr );
892 }
893
894 /**
895 Returns a hashcode for this string.
896
897 @return a hash code value for this object.
898
899 @see rtl::OStringHash for convenient use of boost::unordered_map
900 */
901 sal_Int32 hashCode() const SAL_THROW(())
902 {
903 return rtl_str_hashCode_WithLength( pData->buffer, pData->length );
904 }
905
906 /**
907 Returns the index within this string of the first occurrence of the
908 specified character, starting the search at the specified index.
909
910 @param ch character to be located.
911 @param fromIndex the index to start the search from.
912 The index must be greater or equal than 0
913 and less or equal as the string length.
914 @return the index of the first occurrence of the character in the
915 character sequence represented by this string that is
916 greater than or equal to fromIndex, or
917 -1 if the character does not occur.
918 */
919 sal_Int32 indexOf( sal_Char ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
920 {
921 sal_Int32 ret = rtl_str_indexOfChar_WithLength( pData->buffer+fromIndex, pData->length-fromIndex, ch );
922 return (ret < 0 ? ret : ret+fromIndex);
923 }
924
925 /**
926 Returns the index within this string of the last occurrence of the
927 specified character, searching backward starting at the end.
928
929 @param ch character to be located.
930 @return the index of the last occurrence of the character in the
931 character sequence represented by this string, or
932 -1 if the character does not occur.
933 */
934 sal_Int32 lastIndexOf( sal_Char ch ) const SAL_THROW(())
935 {
936 return rtl_str_lastIndexOfChar_WithLength( pData->buffer, pData->length, ch );
937 }
938
939 /**
940 Returns the index within this string of the last occurrence of the
941 specified character, searching backward starting before the specified
942 index.
943
944 @param ch character to be located.
945 @param fromIndex the index before which to start the search.
946 @return the index of the last occurrence of the character in the
947 character sequence represented by this string that
948 is less than fromIndex, or -1
949 if the character does not occur before that point.
950 */
951 sal_Int32 lastIndexOf( sal_Char ch, sal_Int32 fromIndex ) const SAL_THROW(())
952 {
953 return rtl_str_lastIndexOfChar_WithLength( pData->buffer, fromIndex, ch );
954 }
955
956 /**
957 Returns the index within this string of the first occurrence of the
958 specified substring, starting at the specified index.
959
960 If str doesn't include any character, always -1 is
961 returned. This is also the case, if both strings are empty.
962
963 @param str the substring to search for.
964 @param fromIndex the index to start the search from.
965 @return If the string argument occurs one or more times as a substring
966 within this string at the starting index, then the index
967 of the first character of the first such substring is
968 returned. If it does not occur as a substring starting
969 at fromIndex or beyond, -1 is returned.
970 */
971 sal_Int32 indexOf( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
972 {
973 sal_Int32 ret = rtl_str_indexOfStr_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
974 str.pData->buffer, str.pData->length );
975 return (ret < 0 ? ret : ret+fromIndex);
976 }
977
978 /**
979 @overload
980 This function accepts an ASCII string literal as its argument.
981 @since LibreOffice 3.6
982 */
983 template< typename T >
984 typename internal::ConstCharArrayDetector< T, sal_Int32 >::Type indexOf( T& literal, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
985 {
986 RTL_STRING_CONST_FUNCTION
987 assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
988 sal_Int32 n = rtl_str_indexOfStr_WithLength(
989 pData->buffer + fromIndex, pData->length - fromIndex, literal, internal::ConstCharArrayDetector< T, void >::size - 1);
990 return n < 0 ? n : n + fromIndex;
991 }
992
993 /**
994 Returns the index within this string of the first occurrence of the
995 specified substring, starting at the specified index.
996
997 If str doesn't include any character, always -1 is
998 returned. This is also the case, if both strings are empty.
999
1000 @param str the substring to search for.
1001 @param len the length of the substring.
1002 @param fromIndex the index to start the search from.
1003 @return If the string argument occurs one or more times as a substring
1004 within this string at the starting index, then the index
1005 of the first character of the first such substring is
1006 returned. If it does not occur as a substring starting
1007 at fromIndex or beyond, -1 is returned.
1008
1009 @since LibreOffice 3.6
1010 */
1011 sal_Int32 indexOfL(char const * str, sal_Int32 len, sal_Int32 fromIndex = 0)
1012 const SAL_THROW(())
1013 {
1014 sal_Int32 n = rtl_str_indexOfStr_WithLength(
1015 pData->buffer + fromIndex, pData->length - fromIndex, str, len);
1016 return n < 0 ? n : n + fromIndex;
1017 }
1018
1019 // This overload is left undefined, to detect calls of indexOfL that
1020 // erroneously use RTL_CONSTASCII_USTRINGPARAM instead of
1021 // RTL_CONSTASCII_STRINGPARAM (but would lead to ambiguities on 32 bit
1022 // platforms):
1023#if SAL_TYPES_SIZEOFLONG == 8
1024 void indexOfL(char const *, sal_Int32, rtl_TextEncoding) const;
1025#endif
1026
1027 /**
1028 Returns the index within this string of the last occurrence of
1029 the specified substring, searching backward starting at the end.
1030
1031 The returned index indicates the starting index of the substring
1032 in this string.
1033 If str doesn't include any character, always -1 is
1034 returned. This is also the case, if both strings are empty.
1035
1036 @param str the substring to search for.
1037 @return If the string argument occurs one or more times as a substring
1038 within this string, then the index of the first character of
1039 the last such substring is returned. If it does not occur as
1040 a substring, -1 is returned.
1041 */
1042 sal_Int32 lastIndexOf( const OString & str ) const SAL_THROW(())
1043 {
1044 return rtl_str_lastIndexOfStr_WithLength( pData->buffer, pData->length,
1045 str.pData->buffer, str.pData->length );
1046 }
1047
1048 /**
1049 Returns the index within this string of the last occurrence of
1050 the specified substring, searching backward starting before the specified
1051 index.
1052
1053 The returned index indicates the starting index of the substring
1054 in this string.
1055 If str doesn't include any character, always -1 is
1056 returned. This is also the case, if both strings are empty.
1057
1058 @param str the substring to search for.
1059 @param fromIndex the index before which to start the search.
1060 @return If the string argument occurs one or more times as a substring
1061 within this string before the starting index, then the index
1062 of the first character of the last such substring is
1063 returned. Otherwise, -1 is returned.
1064 */
1065 sal_Int32 lastIndexOf( const OString & str, sal_Int32 fromIndex ) const SAL_THROW(())
1066 {
1067 return rtl_str_lastIndexOfStr_WithLength( pData->buffer, fromIndex,
1068 str.pData->buffer, str.pData->length );
1069 }
1070
1071 /**
1072 Returns a new string that is a substring of this string.
1073
1074 The substring begins at the specified beginIndex. If
1075 beginIndex is negative or be greater than the length of
1076 this string, behaviour is undefined.
1077
1078 @param beginIndex the beginning index, inclusive.
1079 @return the specified substring.
1080 */
1081 SAL_WARN_UNUSED_RESULT OString copy( sal_Int32 beginIndex ) const SAL_THROW(())
1082 {
1083 rtl_String *pNew = 0;
1084 rtl_string_newFromSubString( &pNew, pData, beginIndex, getLength() - beginIndex );
1085 return OString( pNew, SAL_NO_ACQUIRE );
1086 }
1087
1088 /**
1089 Returns a new string that is a substring of this string.
1090
1091 The substring begins at the specified beginIndex and contains count
1092 characters. If either beginIndex or count are negative,
1093 or beginIndex + count are greater than the length of this string
1094 then behaviour is undefined.
1095
1096 @param beginIndex the beginning index, inclusive.
1097 @param count the number of characters.
1098 @return the specified substring.
1099 */
1100 SAL_WARN_UNUSED_RESULT OString copy( sal_Int32 beginIndex, sal_Int32 count ) const SAL_THROW(())
1101 {
1102 rtl_String *pNew = 0;
1103 rtl_string_newFromSubString( &pNew, pData, beginIndex, count );
1104 return OString( pNew, SAL_NO_ACQUIRE );
1105 }
1106
1107 /**
1108 Concatenates the specified string to the end of this string.
1109
1110 @param str the string that is concatenated to the end
1111 of this string.
1112 @return a string that represents the concatenation of this string
1113 followed by the string argument.
1114 */
1115 SAL_WARN_UNUSED_RESULT OString concat( const OString & str ) const SAL_THROW(())
1116 {
1117 rtl_String* pNew = 0;
1118 rtl_string_newConcat( &pNew, pData, str.pData );
1119 return OString( pNew, SAL_NO_ACQUIRE );
1120 }
1121
1122#ifndef RTL_FAST_STRING
1123 friend OString operator+( const OString & str1, const OString & str2 ) SAL_THROW(())
1124 {
1125 return str1.concat( str2 );
1126 }
1127#endif
1128
1129 /**
1130 Returns a new string resulting from replacing n = count characters
1131 from position index in this string with newStr.
1132
1133 @param index the replacing index in str.
1134 The index must be greater or equal as 0 and
1135 less or equal as the length of the string.
1136 @param count the count of characters that will replaced
1137 The count must be greater or equal as 0 and
1138 less or equal as the length of the string minus index.
1139 @param newStr the new substring.
1140 @return the new string.
1141 */
1142 SAL_WARN_UNUSED_RESULT OString replaceAt( sal_Int32 index, sal_Int32 count, const OString& newStr ) const SAL_THROW(())
1143 {
1144 rtl_String* pNew = 0;
1145 rtl_string_newReplaceStrAt( &pNew, pData, index, count, newStr.pData );
1146 return OString( pNew, SAL_NO_ACQUIRE );
1147 }
1148
1149 /**
1150 Returns a new string resulting from replacing all occurrences of
1151 oldChar in this string with newChar.
1152
1153 If the character oldChar does not occur in the character sequence
1154 represented by this object, then the string is assigned with
1155 str.
1156
1157 @param oldChar the old character.
1158 @param newChar the new character.
1159 @return a string derived from this string by replacing every
1160 occurrence of oldChar with newChar.
1161 */
1162 SAL_WARN_UNUSED_RESULT OString replace( sal_Char oldChar, sal_Char newChar ) const SAL_THROW(())
1163 {
1164 rtl_String* pNew = 0;
1165 rtl_string_newReplace( &pNew, pData, oldChar, newChar );
1166 return OString( pNew, SAL_NO_ACQUIRE );
1167 }
1168
1169 /**
1170 Returns a new string resulting from replacing the first occurrence of a
1171 given substring with another substring.
1172
1173 @param from the substring to be replaced
1174
1175 @param to the replacing substring
1176
1177 @param[in,out] index pointer to a start index; if the pointer is
1178 non-null: upon entry to the function, its value is the index into the this
1179 string at which to start searching for the \p from substring, the value
1180 must be non-negative and not greater than this string's length; upon exit
1181 from the function its value is the index into this string at which the
1182 replacement took place or -1 if no replacement took place; if the pointer
1183 is null, searching always starts at index 0
1184
1185 @since LibreOffice 3.6
1186 */
1187 SAL_WARN_UNUSED_RESULT OString replaceFirst(
1188 OString const & from, OString const & to, sal_Int32 * index = 0) const
1189 {
1190 rtl_String * s = 0;
1191 sal_Int32 i = 0;
1192 rtl_string_newReplaceFirst(
1193 &s, pData, from.pData->buffer, from.pData->length,
1194 to.pData->buffer, to.pData->length, index == 0 ? &i : index);
1195 return OString(s, SAL_NO_ACQUIRE);
1196 }
1197
1198 /**
1199 Returns a new string resulting from replacing all occurrences of a given
1200 substring with another substring.
1201
1202 Replacing subsequent occurrences picks up only after a given replacement.
1203 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1204
1205 @param from the substring to be replaced
1206
1207 @param to the replacing substring
1208
1209 @since LibreOffice 3.6
1210 */
1211 SAL_WARN_UNUSED_RESULT OString replaceAll(OString const & from, OString const & to) const {
1212 rtl_String * s = 0;
1213 rtl_string_newReplaceAll(
1214 &s, pData, from.pData->buffer, from.pData->length,
1215 to.pData->buffer, to.pData->length);
1216 return OString(s, SAL_NO_ACQUIRE);
1217 }
1218
1219 /**
1220 Converts from this string all ASCII uppercase characters (65-90)
1221 to ASCII lowercase characters (97-122).
1222
1223 This function can't be used for language specific conversion.
1224 If the string doesn't contain characters which must be converted,
1225 then the new string is assigned with str.
1226
1227 @return the string, converted to ASCII lowercase.
1228 */
1229 SAL_WARN_UNUSED_RESULT OString toAsciiLowerCase() const SAL_THROW(())
1230 {
1231 rtl_String* pNew = 0;
1232 rtl_string_newToAsciiLowerCase( &pNew, pData );
1233 return OString( pNew, SAL_NO_ACQUIRE );
1234 }
1235
1236 /**
1237 Converts from this string all ASCII lowercase characters (97-122)
1238 to ASCII uppercase characters (65-90).
1239
1240 This function can't be used for language specific conversion.
1241 If the string doesn't contain characters which must be converted,
1242 then the new string is assigned with str.
1243
1244 @return the string, converted to ASCII uppercase.
1245 */
1246 SAL_WARN_UNUSED_RESULT OString toAsciiUpperCase() const SAL_THROW(())
1247 {
1248 rtl_String* pNew = 0;
1249 rtl_string_newToAsciiUpperCase( &pNew, pData );
1250 return OString( pNew, SAL_NO_ACQUIRE );
1251 }
1252
1253 /**
1254 Returns a new string resulting from removing white space from both ends
1255 of the string.
1256
1257 All characters that have codes less than or equal to
1258 32 (the space character) are considered to be white space.
1259 If the string doesn't contain white spaces at both ends,
1260 then the new string is assigned with str.
1261
1262 @return the string, with white space removed from the front and end.
1263 */
1264 SAL_WARN_UNUSED_RESULT OString trim() const SAL_THROW(())
1265 {
1266 rtl_String* pNew = 0;
1267 rtl_string_newTrim( &pNew, pData );
1268 return OString( pNew, SAL_NO_ACQUIRE );
1269 }
1270
1271 /**
1272 Returns a token in the string.
1273
1274 Example:
1275 sal_Int32 nIndex = 0;
1276 do
1277 {
1278 ...
1279 OString aToken = aStr.getToken( 0, ';', nIndex );
1280 ...
1281 }
1282 while ( nIndex >= 0 );
1283
1284 @param token the number of the token to return.
1285 @param cTok the character which separate the tokens.
1286 @param index the position at which the token is searched in the
1287 string.
1288 The index must not be greater thanthe length of the
1289 string.
1290 This param is set to the position of the
1291 next token or to -1, if it is the last token.
1292 @return the token; if either token or index is negative, an empty token
1293 is returned (and index is set to -1)
1294 */
1295 OString getToken( sal_Int32 token, sal_Char cTok, sal_Int32& index ) const SAL_THROW(())
1296 {
1297 rtl_String * pNew = 0;
1298 index = rtl_string_getToken( &pNew, pData, token, cTok, index );
1299 return OString( pNew, SAL_NO_ACQUIRE );
1300 }
1301
1302 /**
1303 Returns a token from the string.
1304
1305 The same as getToken(sal_Int32, sal_Char, sal_Int32 &), but always passing
1306 in 0 as the start index in the third argument.
1307
1308 @param count the number of the token to return, starting with 0
1309 @param separator the character which separates the tokens
1310
1311 @return the given token, or an empty string
1312
1313 @since LibreOffice 3.6
1314 */
1315 OString getToken(sal_Int32 count, char separator) const {
1316 sal_Int32 n = 0;
1317 return getToken(count, separator, n);
1318 }
1319
1320 /**
1321 Returns the Boolean value from this string.
1322
1323 This function can't be used for language specific conversion.
1324
1325 @return true, if the string is 1 or "True" in any ASCII case.
1326 false in any other case.
1327 */
1328 bool toBoolean() const SAL_THROW(())
1329 {
1330 return rtl_str_toBoolean( pData->buffer );
1331 }
1332
1333 /**
1334 Returns the first character from this string.
1335
1336 @return the first character from this string or 0, if this string
1337 is emptry.
1338 */
1339 sal_Char toChar() const SAL_THROW(())
1340 {
1341 return pData->buffer[0];
1342 }
1343
1344 /**
1345 Returns the int32 value from this string.
1346
1347 This function can't be used for language specific conversion.
1348
1349 @param radix the radix (between 2 and 36)
1350 @return the int32 represented from this string.
1351 0 if this string represents no number or one of too large
1352 magnitude.
1353 */
1354 sal_Int32 toInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
1355 {
1356 return rtl_str_toInt32( pData->buffer, radix );
1357 }
1358
1359 /**
1360 Returns the uint32 value from this string.
1361
1362 This function can't be used for language specific conversion.
1363
1364 @param radix the radix (between 2 and 36)
1365 @return the uint32 represented from this string.
1366 0 if this string represents no number or one of too large
1367 magnitude.
1368
1369 @since LibreOffice 4.2
1370 */
1371 sal_uInt32 toUInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
1372 {
1373 return rtl_str_toUInt32( pData->buffer, radix );
1374 }
1375
1376 /**
1377 Returns the int64 value from this string.
1378
1379 This function can't be used for language specific conversion.
1380
1381 @param radix the radix (between 2 and 36)
1382 @return the int64 represented from this string.
1383 0 if this string represents no number or one of too large
1384 magnitude.
1385 */
1386 sal_Int64 toInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
1387 {
1388 return rtl_str_toInt64( pData->buffer, radix );
1389 }
1390
1391 /**
1392 Returns the uint64 value from this string.
1393
1394 This function can't be used for language specific conversion.
1395
1396 @param radix the radix (between 2 and 36)
1397 @return the uint64 represented from this string.
1398 0 if this string represents no number or one of too large
1399 magnitude.
1400
1401 @since LibreOffice 4.1
1402 */
1403 sal_uInt64 toUInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
1404 {
1405 return rtl_str_toUInt64( pData->buffer, radix );
1406 }
1407
1408 /**
1409 Returns the float value from this string.
1410
1411 This function can't be used for language specific conversion.
1412
1413 @return the float represented from this string.
1414 0.0 if this string represents no number.
1415 */
1416 float toFloat() const SAL_THROW(())
1417 {
1418 return rtl_str_toFloat( pData->buffer );
1419 }
1420
1421 /**
1422 Returns the double value from this string.
1423
1424 This function can't be used for language specific conversion.
1425
1426 @return the double represented from this string.
1427 0.0 if this string represents no number.
1428 */
1429 double toDouble() const SAL_THROW(())
1430 {
1431 return rtl_str_toDouble( pData->buffer );
1432 }
1433
1434 /**
1435 Returns the string representation of the integer argument.
1436
1437 This function can't be used for language specific conversion.
1438
1439 @param i an integer value
1440 @param radix the radix (between 2 and 36)
1441 @return a string with the string representation of the argument.
1442 @since LibreOffice 4.1
1443 */
1444 static OString number( int i, sal_Int16 radix = 10 )
1445 {
1446 return number( static_cast< long long >( i ), radix );
1447 }
1448 /// @overload
1449 /// @since LibreOffice 4.1
1450 static OString number( unsigned int i, sal_Int16 radix = 10 )
1451 {
1452 return number( static_cast< unsigned long long >( i ), radix );
1453 }
1454 /// @overload
1455 /// @since LibreOffice 4.1
1456 static OString number( long i, sal_Int16 radix = 10 )
1457 {
1458 return number( static_cast< long long >( i ), radix );
1459 }
1460 /// @overload
1461 /// @since LibreOffice 4.1
1462 static OString number( unsigned long i, sal_Int16 radix = 10 )
1463 {
1464 return number( static_cast< unsigned long long >( i ), radix );
1465 }
1466 /// @overload
1467 /// @since LibreOffice 4.1
1468 static OString number( long long ll, sal_Int16 radix = 10 )
1469 {
1470 sal_Char aBuf[RTL_STR_MAX_VALUEOFINT64];
1471 rtl_String* pNewData = 0;
1472 rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfInt64( aBuf, ll, radix ) );
1473 return OString( pNewData, SAL_NO_ACQUIRE );
1474 }
1475 /// @overload
1476 /// @since LibreOffice 4.1
1477 static OString number( unsigned long long ll, sal_Int16 radix = 10 )
1478 {
1479 sal_Char aBuf[RTL_STR_MAX_VALUEOFUINT64];
1480 rtl_String* pNewData = 0;
1481 rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfUInt64( aBuf, ll, radix ) );
1482 return OString( pNewData, SAL_NO_ACQUIRE );
1483 }
1484
1485 /**
1486 Returns the string representation of the float argument.
1487
1488 This function can't be used for language specific conversion.
1489
1490 @param f a float.
1491 @return a string with the string representation of the argument.
1492 @since LibreOffice 4.1
1493 */
1494 static OString number( float f )
1495 {
1496 sal_Char aBuf[RTL_STR_MAX_VALUEOFFLOAT];
1497 rtl_String* pNewData = 0;
1498 rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfFloat( aBuf, f ) );
1499 return OString( pNewData, SAL_NO_ACQUIRE );
1500 }
1501
1502 /**
1503 Returns the string representation of the double argument.
1504
1505 This function can't be used for language specific conversion.
1506
1507 @param d a double.
1508 @return a string with the string representation of the argument.
1509 @since LibreOffice 4.1
1510 */
1511 static OString number( double d )
1512 {
1513 sal_Char aBuf[RTL_STR_MAX_VALUEOFDOUBLE];
1514 rtl_String* pNewData = 0;
1515 rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfDouble( aBuf, d ) );
1516 return OString( pNewData, SAL_NO_ACQUIRE );
1517 }
1518
1519 /**
1520 Returns the string representation of the sal_Bool argument.
1521
1522 If the sal_Bool is true, the string "true" is returned.
1523 If the sal_Bool is false, the string "false" is returned.
1524 This function can't be used for language specific conversion.
1525
1526 @param b a sal_Bool.
1527 @return a string with the string representation of the argument.
1528 @deprecated use boolean()
1529 */
1530 SAL_DEPRECATED("use boolean()") static OString valueOf( sal_Bool b ) SAL_THROW(())
1531 {
1532 return boolean(b);
1533 }
1534
1535 /**
1536 Returns the string representation of the boolean argument.
1537
1538 If the argument is true, the string "true" is returned.
1539 If the argument is false, the string "false" is returned.
1540 This function can't be used for language specific conversion.
1541
1542 @param b a bool.
1543 @return a string with the string representation of the argument.
1544 @since LibreOffice 4.1
1545 */
1546 static OString boolean( bool b ) SAL_THROW(())
1547 {
1548 sal_Char aBuf[RTL_STR_MAX_VALUEOFBOOLEAN];
1549 rtl_String* pNewData = 0;
1550 rtl_string_newFromStr_WithLength( &pNewData, aBuf, rtl_str_valueOfBoolean( aBuf, b ) );
1551 return OString( pNewData, SAL_NO_ACQUIRE );
1552 }
1553
1554 /**
1555 Returns the string representation of the char argument.
1556
1557 @param c a character.
1558 @return a string with the string representation of the argument.
1559 @deprecated use operator, function or constructor taking char or sal_Unicode argument
1560 */
1561 SAL_DEPRECATED("convert to OString or use directly") static OString valueOf( sal_Char c ) SAL_THROW(())
1562 {
1563 return OString( &c, 1 );
1564 }
1565
1566 /**
1567 Returns the string representation of the int argument.
1568
1569 This function can't be used for language specific conversion.
1570
1571 @param i a int32.
1572 @param radix the radix (between 2 and 36)
1573 @return a string with the string representation of the argument.
1574 @deprecated use number()
1575 */
1576 SAL_DEPRECATED("use number()") static OString valueOf( sal_Int32 i, sal_Int16 radix = 10 ) SAL_THROW(())
1577 {
1578 return number( i, radix );
1579 }
1580
1581 /**
1582 Returns the string representation of the long argument.
1583
1584 This function can't be used for language specific conversion.
1585
1586 @param ll a int64.
1587 @param radix the radix (between 2 and 36)
1588 @return a string with the string representation of the argument.
1589 @deprecated use number()
1590 */
1591 SAL_DEPRECATED("use number()") static OString valueOf( sal_Int64 ll, sal_Int16 radix = 10 ) SAL_THROW(())
1592 {
1593 return number( ll, radix );
1594 }
1595
1596 /**
1597 Returns the string representation of the float argument.
1598
1599 This function can't be used for language specific conversion.
1600
1601 @param f a float.
1602 @return a string with the string representation of the argument.
1603 @deprecated use number()
1604 */
1605 SAL_DEPRECATED("use number()") static OString valueOf( float f ) SAL_THROW(())
1606 {
1607 return number(f);
1608 }
1609
1610 /**
1611 Returns the string representation of the double argument.
1612
1613 This function can't be used for language specific conversion.
1614
1615 @param d a double.
1616 @return a string with the string representation of the argument.
1617 @deprecated use number()
1618 */
1619 SAL_DEPRECATED("use number()") static OString valueOf( double d ) SAL_THROW(())
1620 {
1621 return number(d);
1622 }
1623
1624};
1625
1626/* ======================================================================= */
1627
1628#ifdef RTL_FAST_STRING
1629/**
1630A simple wrapper around string literal. It is usually not necessary to use, can
1631be mostly used to force OString operator+ working with operands that otherwise would
1632not trigger it.
1633
1634This class is not part of public API and is meant to be used only in LibreOffice code.
1635@since LibreOffice 4.0
1636*/
1637struct SAL_WARN_UNUSED OStringLiteral
1638{
1639 template< int N >
1640 OStringLiteral( const char (&str)[ N ] ) : size( N - 1 ), data( str ) { assert( strlen( str ) == N - 1 ); }
1641 int size;
1642 const char* data;
1643};
1644
1645/**
1646 @internal
1647*/
1648template<>
1649struct ToStringHelper< OString >
1650 {
1651 static int length( const OString& s ) { return s.getLength(); }
1652 static char* addData( char* buffer, const OString& s ) { return addDataHelper( buffer, s.getStr(), s.getLength()); }
1653 static const bool allowOStringConcat = true;
1654 static const bool allowOUStringConcat = false;
1655 };
1656
1657/**
1658 @internal
1659*/
1660template<>
1661struct ToStringHelper< OStringLiteral >
1662 {
1663 static int length( const OStringLiteral& str ) { return str.size; }
1664 static char* addData( char* buffer, const OStringLiteral& str ) { return addDataHelper( buffer, str.data, str.size ); }
1665 static const bool allowOStringConcat = true;
1666 static const bool allowOUStringConcat = false;
1667 };
1668
1669/**
1670 @internal
1671*/
1672template< typename charT, typename traits, typename T1, typename T2 >
1673inline std::basic_ostream<charT, traits> & operator <<(
1674 std::basic_ostream<charT, traits> & stream, const OStringConcat< T1, T2 >& concat)
1675{
1676 return stream << OString( concat );
1677}
1678#else
1679// non-RTL_FAST_STRING needs this to compile
1680/// @cond INTERNAL
1681typedef OString OStringLiteral;
1682/// @endcond
1683#endif
1684
1685
1686/** A helper to use OStrings with hash maps.
1687
1688 Instances of this class are unary function objects that can be used as
1689 hash function arguments to boost::unordered_map and similar constructs.
1690 */
1691struct OStringHash
1692{
1693 /** Compute a hash code for a string.
1694
1695 @param rString
1696 a string.
1697
1698 @return
1699 a hash code for the string. This hash code should not be stored
1700 persistently, as its computation may change in later revisions.
1701 */
1702 size_t operator()( const OString& rString ) const
1703 { return (size_t)rString.hashCode(); }
1704};
1705
1706/** Equality functor for classic c-strings (i.e., null-terminated char* strings). */
1707struct CStringEqual
1708{
1709 bool operator()( const char* p1, const char* p2) const
1710 { return rtl_str_compare(p1, p2) == 0; }
1711};
1712
1713/** Hashing functor for classic c-strings (i.e., null-terminated char* strings). */
1714struct CStringHash
1715{
1716 size_t operator()(const char* p) const
1717 { return rtl_str_hashCode(p); }
1718};
1719
1720/* ======================================================================= */
1721
1722/**
1723 Support for rtl::OString in std::ostream (and thus in
1724 CPPUNIT_ASSERT or SAL_INFO macros, for example).
1725
1726 @since LibreOffice 4.0
1727 */
1728template< typename charT, typename traits > std::basic_ostream<charT, traits> &
1729operator <<(
1730 std::basic_ostream<charT, traits> & stream, OString const & string)
1731{
1732 return stream << string.getStr();
1733 // best effort; potentially loses data due to embedded null characters
1734}
1735
1736} /* Namespace */
1737
1738#ifdef RTL_STRING_UNITTEST
1739namespace rtl
1740{
1741typedef rtlunittest::OString OString;
1742}
1743#undef RTL_STRING_CONST_FUNCTION
1744#endif
1745
1746#ifdef RTL_USING
1747using ::rtl::OString;
1748using ::rtl::OStringHash;
1749using ::rtl::OStringLiteral;
1750#endif
1751
1752#endif // INCLUDED_RTL_STRING_HXX
1753
1754/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
1755