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_USTRING_HXX
21	#define INCLUDED_RTL_USTRING_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/ustring.h>
32	#include <rtl/string.hxx>
33	#include <rtl/stringutils.hxx>
34	#include <rtl/textenc.h>
35	#include <sal/log.hxx>
36
37	#ifdef RTL_FAST_STRING
38	#include <rtl/stringconcat.hxx>
39	#endif
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
50	namespace rtl
51	{
52
53	#ifdef RTL_STRING_UNITTEST
54	#undef rtl
55	#endif
56
57	/* ======================================================================= */
58
59	/**
60	This String class provides base functionality for C++ like Unicode
61	character array handling. The advantage of this class is that it
62	handles all the memory management for you - and it does it
63	more efficiently. If you assign a string to another string, the
64	data of both strings are shared (without any copy operation or
65	memory allocation) as long as you do not change the string. This class
66	also stores the length of the string, so that many operations are
67	faster than the C-str-functions.
68
69	This class provides only readonly string handling. So you could create
70	a string and you could only query the content from this string.
71	It provides also functionality to change the string, but this results
72	in every case in a new string instance (in the most cases with a
73	memory allocation). You don't have functionality to change the
74	content of the string. If you want to change the string content, then
75	you should use the OStringBuffer class, which provides these
76	functionalities and avoids too much memory allocation.
77
78	The design of this class is similar to the string classes in Java so
79	less people should have understanding problems when they use this class.
80	*/
81
82	class SAL_WARN_UNUSED OUString
83	{
84	public:
85	/// @cond INTERNAL
86	rtl_uString * pData;
87	/// @endcond
88
89	/**
90	New string containing no characters.
91	*/
92	OUString() SAL_THROW(())
93	{
94	pData = 0;
95	rtl_uString_new( &pData );
96	}
97
98	/**
99	New string from OUString.
100
101	@param str a OUString.
102	*/
103	OUString( const OUString & str ) SAL_THROW(())
104	{
105	pData = str.pData;
106	rtl_uString_acquire( pData );
107	}
108
109	/**
110	New string from OUString data.
111
112	@param str a OUString data.
113	*/
114	OUString( rtl_uString * str ) SAL_THROW(())
115	{
116	pData = str;
117	rtl_uString_acquire( pData );
118	}
119
120	/** New OUString from OUString data without acquiring it. Takeover of ownership.
121
122	The SAL_NO_ACQUIRE dummy parameter is only there to distinguish this
123	from other constructors.
124
125	@param str
126	OUString data
127	*/
128	inline OUString( rtl_uString * str, __sal_NoAcquire ) SAL_THROW(())
129	{ pData = str; }
130
131	/**
132	New string from a single Unicode character.
133
134	@param value a Unicode character.
135	*/
136	explicit OUString( sal_Unicode value ) SAL_THROW(())
137	: pData (0)
138	{
139	rtl_uString_newFromStr_WithLength( &pData, &value, 1 );
140	}
141
142	/**
143	New string from a Unicode character buffer array.
144
145	@param value a NULL-terminated Unicode character array.
146	*/
147	OUString( const sal_Unicode * value ) SAL_THROW(())
148	{
149	pData = 0;
150	rtl_uString_newFromStr( &pData, value );
151	}
152
153	/**
154	New string from a Unicode character buffer array.
155
156	@param value a Unicode character array.
157	@param length the number of character which should be copied.
158	The character array length must be greater than
159	or equal to this value.
160	*/
161	OUString( const sal_Unicode * value, sal_Int32 length ) SAL_THROW(())
162	{
163	pData = 0;
164	rtl_uString_newFromStr_WithLength( &pData, value, length );
165	}
166
167	/**
168	New string from an 8-Bit string literal that is expected to contain only
169	characters in the ASCII set (i.e. first 128 characters). This constructor
170	allows an efficient and convenient way to create OUString
171	instances from ASCII literals. When creating strings from data that
172	is not pure ASCII, it needs to be converted to OUString by explicitly
173	providing the encoding to use for the conversion.
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	@param literal the 8-bit ASCII string literal
179
180	@since LibreOffice 3.6
181	*/
182	template< typename T >
183	OUString( T& literal, typename internal::ConstCharArrayDetector< T, internal::Dummy >::Type = internal::Dummy() )
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_uString_new( &pData );
189	else
190	rtl_uString_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	#ifdef RTL_STRING_UNITTEST
197	/**
198	* Only used by unittests to detect incorrect conversions.
199	* @internal
200	*/
201	template< typename T >
202	OUString( T&, typename internal::ExceptConstCharArrayDetector< T >::Type = internal::Dummy() )
203	{
204	pData = 0;
205	rtl_uString_newFromLiteral( &pData, "!!br0ken!!", 10, 0 ); // set to garbage
206	rtl_string_unittest_invalid_conversion = true;
207	}
208	/**
209	* Only used by unittests to detect incorrect conversions.
210	* @internal
211	*/
212	template< typename T >
213	OUString( const T&, typename internal::ExceptCharArrayDetector< T >::Type = internal::Dummy() )
214	{
215	pData = 0;
216	rtl_uString_newFromLiteral( &pData, "!!br0ken!!", 10, 0 ); // set to garbage
217	rtl_string_unittest_invalid_conversion = true;
218	}
219	#endif
220
221	/**
222	New string from an 8-Bit character buffer array.
223
224	@param value An 8-Bit character array.
225	@param length The number of character which should be converted.
226	The 8-Bit character array length must be
227	greater than or equal to this value.
228	@param encoding The text encoding from which the 8-Bit character
229	sequence should be converted.
230	@param convertFlags Flags which control the conversion.
231	see RTL_TEXTTOUNICODE_FLAGS_...
232
233	@exception std::bad_alloc is thrown if an out-of-memory condition occurs
234	*/
235	OUString( const sal_Char * value, sal_Int32 length,
236	rtl_TextEncoding encoding,
237	sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS )
238	{
239	pData = 0;
240	rtl_string2UString( &pData, value, length, encoding, convertFlags );
241	if (pData == 0) {
242	throw std::bad_alloc();
243	}
244	}
245
246	/** Create a new string from an array of Unicode code points.
247
248	@param codePoints
249	an array of at least codePointCount code points, which each must be in
250	the range from 0 to 0x10FFFF, inclusive. May be null if codePointCount
251	is zero.
252
253	@param codePointCount
254	the non-negative number of code points.
255
256	@exception std::bad_alloc
257	is thrown if either an out-of-memory condition occurs or the resulting
258	number of UTF-16 code units would have been larger than SAL_MAX_INT32.
259
260	@since UDK 3.2.7
261	*/
262	inline explicit OUString(
263	sal_uInt32 const * codePoints, sal_Int32 codePointCount):
264	pData(NULL)
265	{
266	rtl_uString_newFromCodePoints(&pData, codePoints, codePointCount);
267	if (pData == NULL) {
268	throw std::bad_alloc();
269	}
270	}
271
272	#ifdef RTL_FAST_STRING
273	/**
274	@overload
275	@internal
276	*/
277	template< typename T1, typename T2 >
278	OUString( const OUStringConcat< T1, T2 >& c )
279	{
280	const sal_Int32 l = c.length();
281	pData = rtl_uString_alloc( l );
282	if (l != 0)
283	{
284	sal_Unicode* end = c.addData( pData->buffer );
285	pData->length = end - pData->buffer;
286	*end = '\0';
287	// TODO realloc in case pData->length is noticeably smaller than l?
288	}
289	}
290	#endif
291
292	/**
293	Release the string data.
294	*/
295	~OUString() SAL_THROW(())
296	{
297	rtl_uString_release( pData );
298	}
299
300	/** Provides an OUString const & passing a storage pointer of an
301	rtl_uString * handle.
302	It is more convenient to use C++ OUString member functions when dealing
303	with rtl_uString * handles. Using this function avoids unnecessary
304	acquire()/release() calls for a temporary OUString object.
305
306	@param ppHandle
307	pointer to storage
308	@return
309	OUString const & based on given storage
310	*/
311	static inline OUString const & unacquired( rtl_uString * const * ppHandle )
312	{ return * reinterpret_cast< OUString const * >( ppHandle ); }
313
314	/**
315	Assign a new string.
316
317	@param str a OUString.
318	*/
319	OUString & operator=( const OUString & str ) SAL_THROW(())
320	{
321	rtl_uString_assign( &pData, str.pData );
322	return *this;
323	}
324
325	/**
326	Assign a new string from an 8-Bit string literal that is expected to contain only
327	characters in the ASCII set (i.e. first 128 characters). This operator
328	allows an efficient and convenient way to assign OUString
329	instances from ASCII literals. When assigning strings from data that
330	is not pure ASCII, it needs to be converted to OUString by explicitly
331	providing the encoding to use for the conversion.
332
333	@param literal the 8-bit ASCII string literal
334
335	@since LibreOffice 3.6
336	*/
337	template< typename T >
338	typename internal::ConstCharArrayDetector< T, OUString& >::Type operator=( T& literal )
339	{
340	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
341	if( internal::ConstCharArrayDetector< T, void >::size - 1 == 0 ) // empty string
342	rtl_uString_new( &pData );
343	else
344	rtl_uString_newFromLiteral( &pData, literal, internal::ConstCharArrayDetector< T, void >::size - 1, 0 );
345	return *this;
346	}
347
348	/**
349	Append a string to this string.
350
351	@param str a OUString.
352	*/
353	OUString & operator+=( const OUString & str ) SAL_THROW(())
354	{
355	rtl_uString_newConcat( &pData, pData, str.pData );
356	return *this;
357	}
358
359	#ifdef RTL_FAST_STRING
360	/**
361	@overload
362	@internal
363	*/
364	template< typename T1, typename T2 >
365	OUString& operator+=( const OUStringConcat< T1, T2 >& c )
366	{
367	const int l = c.length();
368	if( l == 0 )
369	return *this;
370	rtl_uString_ensureCapacity( &pData, pData->length + l );
371	sal_Unicode* end = c.addData( pData->buffer + pData->length );
372	*end = '\0';
373	pData->length = end - pData->buffer;
374	return *this;
375	}
376	#endif
377
378	/**
379	Returns the length of this string.
380
381	The length is equal to the number of Unicode characters in this string.
382
383	@return the length of the sequence of characters represented by this
384	object.
385	*/
386	sal_Int32 getLength() const SAL_THROW(()) { return pData->length; }
387
388	/**
389	Checks if a string is empty.
390
391	@return true if the string is empty;
392	false, otherwise.
393
394	@since LibreOffice 3.4
395	*/
396	bool isEmpty() const SAL_THROW(())
397	{
398	return pData->length == 0;
399	}
400
401	/**
402	Returns a pointer to the Unicode character buffer for this string.
403
404	It isn't necessarily NULL terminated.
405
406	@return a pointer to the Unicode characters buffer for this object.
407	*/
408	const sal_Unicode * getStr() const SAL_THROW(()) { return pData->buffer; }
409
410	/**
411	Access to individual characters.
412
413	@param index must be non-negative and less than length.
414
415	@return the character at the given index.
416
417	@since LibreOffice 3.5
418	*/
419	sal_Unicode operator [](sal_Int32 index) const {
420	// silence spurious -Werror=strict-overflow warnings from GCC 4.8.2
421	assert(index >= 0 && static_cast<sal_uInt32>(index) < static_cast<sal_uInt32>(getLength()));
422	return getStr()[index];
423	}
424
425	/**
426	Compares two strings.
427
428	The comparison is based on the numeric value of each character in
429	the strings and return a value indicating their relationship.
430	This function can't be used for language specific sorting.
431
432	@param str the object to be compared.
433	@return 0 - if both strings are equal
434	< 0 - if this string is less than the string argument
435	> 0 - if this string is greater than the string argument
436	*/
437	sal_Int32 compareTo( const OUString & str ) const SAL_THROW(())
438	{
439	return rtl_ustr_compare_WithLength( pData->buffer, pData->length,
440	str.pData->buffer, str.pData->length );
441	}
442
443	/**
444	Compares two strings with a maximum count of characters.
445
446	The comparison is based on the numeric value of each character in
447	the strings and return a value indicating their relationship.
448	This function can't be used for language specific sorting.
449
450	@param str the object to be compared.
451	@param maxLength the maximum count of characters to be compared.
452	@return 0 - if both strings are equal
453	< 0 - if this string is less than the string argument
454	> 0 - if this string is greater than the string argument
455
456	@since UDK 3.2.7
457	*/
458	sal_Int32 compareTo( const OUString & str, sal_Int32 maxLength ) const SAL_THROW(())
459	{
460	return rtl_ustr_shortenedCompare_WithLength( pData->buffer, pData->length,
461	str.pData->buffer, str.pData->length, maxLength );
462	}
463
464	/**
465	Compares two strings in reverse order.
466
467	The comparison is based on the numeric value of each character in
468	the strings and return a value indicating their relationship.
469	This function can't be used for language specific sorting.
470
471	@param str the object to be compared.
472	@return 0 - if both strings are equal
473	< 0 - if this string is less than the string argument
474	> 0 - if this string is greater than the string argument
475	*/
476	sal_Int32 reverseCompareTo( const OUString & str ) const SAL_THROW(())
477	{
478	return rtl_ustr_reverseCompare_WithLength( pData->buffer, pData->length,
479	str.pData->buffer, str.pData->length );
480	}
481
482	/**
483	@overload
484	This function accepts an ASCII string literal as its argument.
485	@since LibreOffice 4.1
486	*/
487	template< typename T >
488	typename internal::ConstCharArrayDetector< T, sal_Int32 >::Type reverseCompareTo( T& literal ) const SAL_THROW(())
489	{
490	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
491	return rtl_ustr_asciil_reverseCompare_WithLength( pData->buffer, pData->length,
492	literal, internal::ConstCharArrayDetector< T, void >::size - 1 );
493	}
494
495	/**
496	Perform a comparison of two strings.
497
498	The result is true if and only if second string
499	represents the same sequence of characters as the first string.
500	This function can't be used for language specific comparison.
501
502	@param str the object to be compared.
503	@return true if the strings are equal;
504	false, otherwise.
505	*/
506	bool equals( const OUString & str ) const SAL_THROW(())
507	{
508	if ( pData->length != str.pData->length )
509	return false;
510	if ( pData == str.pData )
511	return true;
512	return rtl_ustr_reverseCompare_WithLength( pData->buffer, pData->length,
513	str.pData->buffer, str.pData->length ) == 0;
514	}
515
516	/**
517	Perform a ASCII lowercase comparison of two strings.
518
519	The result is true if and only if second string
520	represents the same sequence of characters as the first string,
521	ignoring the case.
522	Character values between 65 and 90 (ASCII A-Z) are interpreted as
523	values between 97 and 122 (ASCII a-z).
524	This function can't be used for language specific comparison.
525
526	@param str the object to be compared.
527	@return true if the strings are equal;
528	false, otherwise.
529	*/
530	bool equalsIgnoreAsciiCase( const OUString & str ) const SAL_THROW(())
531	{
532	if ( pData->length != str.pData->length )
533	return false;
534	if ( pData == str.pData )
535	return true;
536	return rtl_ustr_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
537	str.pData->buffer, str.pData->length ) == 0;
538	}
539
540	/**
541	Perform a ASCII lowercase comparison of two strings.
542
543	Compare the two strings with uppercase ASCII
544	character values between 65 and 90 (ASCII A-Z) interpreted as
545	values between 97 and 122 (ASCII a-z).
546	This function can't be used for language specific comparison.
547
548	@param str the object to be compared.
549	@return 0 - if both strings are equal
550	< 0 - if this string is less than the string argument
551	> 0 - if this string is greater than the string argument
552
553	@since LibreOffice 4.0
554	*/
555	sal_Int32 compareToIgnoreAsciiCase( const OUString & str ) const SAL_THROW(())
556	{
557	return rtl_ustr_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length,
558	str.pData->buffer, str.pData->length );
559	}
560
561
562	/**
563	@overload
564	This function accepts an ASCII string literal as its argument.
565	@since LibreOffice 3.6
566	*/
567	template< typename T >
568	typename internal::ConstCharArrayDetector< T, bool >::Type equalsIgnoreAsciiCase( T& literal ) const SAL_THROW(())
569	{
570	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
571	if ( pData->length != internal::ConstCharArrayDetector< T, void >::size - 1 )
572	return false;
573
574	return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, literal ) == 0;
575	}
576
577	/**
578	Match against a substring appearing in this string.
579
580	The result is true if and only if the second string appears as a substring
581	of this string, at the given position.
582	This function can't be used for language specific comparison.
583
584	@param str the object (substring) to be compared.
585	@param fromIndex the index to start the comparion from.
586	The index must be greater than or equal to 0
587	and less or equal as the string length.
588	@return true if str match with the characters in the string
589	at the given position;
590	false, otherwise.
591	*/
592	bool match( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
593	{
594	return rtl_ustr_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
595	str.pData->buffer, str.pData->length, str.pData->length ) == 0;
596	}
597
598	/**
599	@overload
600	This function accepts an ASCII string literal as its argument.
601	@since LibreOffice 3.6
602	*/
603	template< typename T >
604	typename internal::ConstCharArrayDetector< T, bool >::Type match( T& literal, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
605	{
606	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
607	return rtl_ustr_ascii_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
608	literal, internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
609	}
610
611	/**
612	Match against a substring appearing in this string, ignoring the case of
613	ASCII letters.
614
615	The result is true if and only if the second string appears as a substring
616	of this string, at the given position.
617	Character values between 65 and 90 (ASCII A-Z) are interpreted as
618	values between 97 and 122 (ASCII a-z).
619	This function can't be used for language specific comparison.
620
621	@param str the object (substring) to be compared.
622	@param fromIndex the index to start the comparion from.
623	The index must be greater than or equal to 0
624	and less than or equal to the string length.
625	@return true if str match with the characters in the string
626	at the given position;
627	false, otherwise.
628	*/
629	bool matchIgnoreAsciiCase( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
630	{
631	return rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
632	str.pData->buffer, str.pData->length,
633	str.pData->length ) == 0;
634	}
635
636	/**
637	@overload
638	This function accepts an ASCII string literal as its argument.
639	@since LibreOffice 3.6
640	*/
641	template< typename T >
642	typename internal::ConstCharArrayDetector< T, bool >::Type matchIgnoreAsciiCase( T& literal, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
643	{
644	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
645	return rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
646	literal, internal::ConstCharArrayDetector< T, void >::size - 1 ) == 0;
647	}
648
649	/**
650	Compares two strings.
651
652	The comparison is based on the numeric value of each character in
653	the strings and return a value indicating their relationship.
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.
658	This function can't be used for language specific sorting.
659
660	@param asciiStr the 8-Bit ASCII character string to be compared.
661	@return 0 - if both strings are equal
662	< 0 - if this string is less than the string argument
663	> 0 - if this string is greater than the string argument
664	*/
665	sal_Int32 compareToAscii( const sal_Char* asciiStr ) const SAL_THROW(())
666	{
667	return rtl_ustr_ascii_compare_WithLength( pData->buffer, pData->length, asciiStr );
668	}
669
670	/**
671	Compares two strings with a maximum count of characters.
672
673	The comparison is based on the numeric value of each character in
674	the strings and return a value indicating their relationship.
675	Since this method is optimized for performance, the ASCII character
676	values are not converted in any way. The caller has to make sure that
677	all ASCII characters are in the allowed range between 0 and
678	127. The ASCII string must be NULL-terminated.
679	This function can't be used for language specific sorting.
680
681	@deprecated This is a confusing overload with unexpectedly different
682	semantics from the one-parameter form, so it is marked as deprecated.
683	Practically all uses compare the return value against zero and can thus
684	be replaced with uses of startsWith.
685
686	@param asciiStr the 8-Bit ASCII character string to be compared.
687	@param maxLength the maximum count of characters to be compared.
688	@return 0 - if both strings are equal
689	< 0 - if this string is less than the string argument
690	> 0 - if this string is greater than the string argument
691	*/
692	SAL_DEPRECATED(
693	"replace s1.compareToAscii(s2, strlen(s2)) == 0 with s1.startsWith(s2)")
694	sal_Int32 compareToAscii( const sal_Char * asciiStr, sal_Int32 maxLength ) const SAL_THROW(())
695	{
696	return rtl_ustr_ascii_shortenedCompare_WithLength( pData->buffer, pData->length,
697	asciiStr, maxLength );
698	}
699
700	/**
701	Compares two strings in reverse order.
702
703	This could be useful, if normally both strings start with the same
704	content. The comparison is based on the numeric value of each character
705	in the strings and return a value indicating their relationship.
706	Since this method is optimized for performance, the ASCII character
707	values are not converted in any way. The caller has to make sure that
708	all ASCII characters are in the allowed range between 0 and 127.
709	The ASCII string must be NULL-terminated and must be greater than
710	or equal to asciiStrLength.
711	This function can't be used for language specific sorting.
712
713	@param asciiStr the 8-Bit ASCII character string to be compared.
714	@param asciiStrLength the length of the ascii string
715	@return 0 - if both strings are equal
716	< 0 - if this string is less than the string argument
717	> 0 - if this string is greater than the string argument
718	*/
719	sal_Int32 reverseCompareToAsciiL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
720	{
721	return rtl_ustr_asciil_reverseCompare_WithLength( pData->buffer, pData->length,
722	asciiStr, asciiStrLength );
723	}
724
725	/**
726	Perform a comparison of two strings.
727
728	The result is true if and only if second string
729	represents the same sequence of characters as the first string.
730	Since this method is optimized for performance, the ASCII character
731	values are not converted in any way. The caller has to make sure that
732	all ASCII characters are in the allowed range between 0 and
733	127. The ASCII string must be NULL-terminated.
734	This function can't be used for language specific comparison.
735
736	@param asciiStr the 8-Bit ASCII character string to be compared.
737	@return true if the strings are equal;
738	false, otherwise.
739	*/
740	bool equalsAscii( const sal_Char* asciiStr ) const SAL_THROW(())
741	{
742	return rtl_ustr_ascii_compare_WithLength( pData->buffer, pData->length,
743	asciiStr ) == 0;
744	}
745
746	/**
747	Perform a comparison of two strings.
748
749	The result is true if and only if second string
750	represents the same sequence of characters as the first string.
751	Since this method is optimized for performance, the ASCII character
752	values are not converted in any way. The caller has to make sure that
753	all ASCII characters are in the allowed range between 0 and
754	127. The ASCII string must be NULL-terminated and must be greater than
755	or equal to asciiStrLength.
756	This function can't be used for language specific comparison.
757
758	@param asciiStr the 8-Bit ASCII character string to be compared.
759	@param asciiStrLength the length of the ascii string
760	@return true if the strings are equal;
761	false, otherwise.
762	*/
763	bool equalsAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
764	{
765	if ( pData->length != asciiStrLength )
766	return false;
767
768	return rtl_ustr_asciil_reverseEquals_WithLength(
769	pData->buffer, asciiStr, asciiStrLength );
770	}
771
772	/**
773	Perform a ASCII lowercase comparison of two strings.
774
775	The result is true if and only if second string
776	represents the same sequence of characters as the first string,
777	ignoring the case.
778	Character values between 65 and 90 (ASCII A-Z) are interpreted as
779	values between 97 and 122 (ASCII a-z).
780	Since this method is optimized for performance, the ASCII character
781	values are not converted in any way. The caller has to make sure that
782	all ASCII characters are in the allowed range between 0 and
783	127. The ASCII string must be NULL-terminated.
784	This function can't be used for language specific comparison.
785
786	@param asciiStr the 8-Bit ASCII character string to be compared.
787	@return true if the strings are equal;
788	false, otherwise.
789	*/
790	bool equalsIgnoreAsciiCaseAscii( const sal_Char * asciiStr ) const SAL_THROW(())
791	{
792	return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, asciiStr ) == 0;
793	}
794
795	/**
796	Compares two ASCII strings ignoring case
797
798	The comparison is based on the numeric value of each character in
799	the strings and return a value indicating their relationship.
800	Since this method is optimized for performance, the ASCII character
801	values are not converted in any way. The caller has to make sure that
802	all ASCII characters are in the allowed range between 0 and
803	127. The ASCII string must be NULL-terminated.
804	This function can't be used for language specific sorting.
805
806	@param asciiStr the 8-Bit ASCII character string to be compared.
807	@return 0 - if both strings are equal
808	< 0 - if this string is less than the string argument
809	> 0 - if this string is greater than the string argument
810
811	@since LibreOffice 3.5
812	*/
813	sal_Int32 compareToIgnoreAsciiCaseAscii( const sal_Char * asciiStr ) const SAL_THROW(())
814	{
815	return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, asciiStr );
816	}
817
818	/**
819	Perform an ASCII lowercase comparison of two strings.
820
821	The result is true if and only if second string
822	represents the same sequence of characters as the first string,
823	ignoring the case.
824	Character values between 65 and 90 (ASCII A-Z) are interpreted as
825	values between 97 and 122 (ASCII a-z).
826	Since this method is optimized for performance, the ASCII character
827	values are not converted in any way. The caller has to make sure that
828	all ASCII characters are in the allowed range between 0 and 127.
829	The ASCII string must be NULL-terminated and must be greater than
830	or equal to asciiStrLength.
831	This function can't be used for language specific comparison.
832
833	@param asciiStr the 8-Bit ASCII character string to be compared.
834	@param asciiStrLength the length of the ascii string
835	@return true if the strings are equal;
836	false, otherwise.
837	*/
838	bool equalsIgnoreAsciiCaseAsciiL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(())
839	{
840	if ( pData->length != asciiStrLength )
841	return false;
842
843	return rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( pData->buffer, pData->length, asciiStr ) == 0;
844	}
845
846	/**
847	Match against a substring appearing in this string.
848
849	The result is true if and only if the second string appears as a substring
850	of this string, at the given position.
851	Since this method is optimized for performance, the ASCII character
852	values are not converted in any way. The caller has to make sure that
853	all ASCII characters are in the allowed range between 0 and
854	127. The ASCII string must be NULL-terminated and must be greater than or
855	equal to asciiStrLength.
856	This function can't be used for language specific comparison.
857
858	@param asciiStr the object (substring) to be compared.
859	@param asciiStrLength the length of asciiStr.
860	@param fromIndex the index to start the comparion from.
861	The index must be greater than or equal to 0
862	and less than or equal to the string length.
863	@return true if str match with the characters in the string
864	at the given position;
865	false, otherwise.
866	*/
867	bool matchAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
868	{
869	return rtl_ustr_ascii_shortenedCompare_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
870	asciiStr, asciiStrLength ) == 0;
871	}
872
873	// This overload is left undefined, to detect calls of matchAsciiL that
874	// erroneously use RTL_CONSTASCII_USTRINGPARAM instead of
875	// RTL_CONSTASCII_STRINGPARAM (but would lead to ambiguities on 32 bit
876	// platforms):
877	#if SAL_TYPES_SIZEOFLONG == 8
878	void matchAsciiL(char const *, sal_Int32, rtl_TextEncoding) const;
879	#endif
880
881	/**
882	Match against a substring appearing in this string, ignoring the case of
883	ASCII letters.
884
885	The result is true if and only if the second string appears as a substring
886	of this string, at the given position.
887	Character values between 65 and 90 (ASCII A-Z) are interpreted as
888	values between 97 and 122 (ASCII a-z).
889	Since this method is optimized for performance, the ASCII character
890	values are not converted in any way. The caller has to make sure that
891	all ASCII characters are in the allowed range between 0 and
892	127. The ASCII string must be NULL-terminated and must be greater than or
893	equal to asciiStrLength.
894	This function can't be used for language specific comparison.
895
896	@param asciiStr the 8-Bit ASCII character string to be compared.
897	@param asciiStrLength the length of the ascii string
898	@param fromIndex the index to start the comparion from.
899	The index must be greater than or equal to 0
900	and less than or equal to the string length.
901	@return true if str match with the characters in the string
902	at the given position;
903	false, otherwise.
904	*/
905	bool matchIgnoreAsciiCaseAsciiL( const sal_Char* asciiStr, sal_Int32 asciiStrLength, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
906	{
907	return rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
908	asciiStr, asciiStrLength ) == 0;
909	}
910
911	// This overload is left undefined, to detect calls of
912	// matchIgnoreAsciiCaseAsciiL that erroneously use
913	// RTL_CONSTASCII_USTRINGPARAM instead of RTL_CONSTASCII_STRINGPARAM (but
914	// would lead to ambiguities on 32 bit platforms):
915	#if SAL_TYPES_SIZEOFLONG == 8
916	void matchIgnoreAsciiCaseAsciiL(char const *, sal_Int32, rtl_TextEncoding)
917	const;
918	#endif
919
920	/**
921	Check whether this string starts with a given substring.
922
923	@param str the substring to be compared
924
925	@param rest if non-null, and this function returns true, then assign a
926	copy of the remainder of this string to *rest. Available since
927	LibreOffice 4.2
928
929	@return true if and only if the given str appears as a substring at the
930	start of this string
931
932	@since LibreOffice 4.0
933	*/
934	bool startsWith(OUString const & str, OUString * rest = 0) const {
935	bool b = match(str, 0);
936	if (b && rest != 0) {
937	*rest = copy(str.getLength());
938	}
939	return b;
940	}
941
942	/**
943	@overload
944	This function accepts an ASCII string literal as its argument.
945	@since LibreOffice 4.0
946	*/
947	template< typename T >
948	typename internal::ConstCharArrayDetector< T, bool >::Type startsWith(
949	T & literal, OUString * rest = 0) const
950	{
951	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
952	bool b = internal::ConstCharArrayDetector< T, void >::size - 1 <= pData->length
953	&& rtl_ustr_asciil_reverseEquals_WithLength( pData->buffer, literal,
954	internal::ConstCharArrayDetector< T, void >::size - 1);
955	if (b && rest != 0) {
956	*rest = copy(internal::ConstCharArrayDetector< T, void >::size - 1);
957	}
958	return b;
959	}
960
961	/**
962	Check whether this string starts with a given string, ignoring the case of
963	ASCII letters.
964
965	Character values between 65 and 90 (ASCII A-Z) are interpreted as
966	values between 97 and 122 (ASCII a-z).
967	This function can't be used for language specific comparison.
968
969	@param str the substring to be compared
970
971	@param rest if non-null, and this function returns true, then assign a
972	copy of the remainder of this string to *rest. Available since
973	LibreOffice 4.2
974
975	@return true if and only if the given str appears as a substring at the
976	start of this string, ignoring the case of ASCII letters ("A"--"Z" and
977	"a"--"z")
978
979	@since LibreOffice 4.0
980	*/
981	bool startsWithIgnoreAsciiCase(OUString const & str, OUString * rest = 0)
982	const
983	{
984	bool b = matchIgnoreAsciiCase(str, 0);
985	if (b && rest != 0) {
986	*rest = copy(str.getLength());
987	}
988	return b;
989	}
990
991	/**
992	@overload
993	This function accepts an ASCII string literal as its argument.
994	@since LibreOffice 4.0
995	*/
996	template< typename T >
997	typename internal::ConstCharArrayDetector< T, bool >::Type
998	startsWithIgnoreAsciiCase(T & literal, OUString * rest = 0) const
999	{
1000	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1001	bool b = (rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
1002	pData->buffer,
1003	internal::ConstCharArrayDetector< T, void >::size - 1, literal,
1004	internal::ConstCharArrayDetector< T, void >::size - 1)
1005	== 0);
1006	if (b && rest != 0) {
1007	*rest = copy(internal::ConstCharArrayDetector< T, void >::size - 1);
1008	}
1009	return b;
1010	}
1011
1012	/**
1013	Check whether this string ends with a given substring.
1014
1015	@param str the substring to be compared
1016
1017	@param rest if non-null, and this function returns true, then assign a
1018	copy of the remainder of this string to *rest. Available since
1019	LibreOffice 4.2
1020
1021	@return true if and only if the given str appears as a substring at the
1022	end of this string
1023
1024	@since LibreOffice 3.6
1025	*/
1026	bool endsWith(OUString const & str, OUString * rest = 0) const {
1027	bool b = str.getLength() <= getLength()
1028	&& match(str, getLength() - str.getLength());
1029	if (b && rest != 0) {
1030	*rest = copy(0, getLength() - str.getLength());
1031	}
1032	return b;
1033	}
1034
1035	/**
1036	@overload
1037	This function accepts an ASCII string literal as its argument.
1038	@since LibreOffice 3.6
1039	*/
1040	template< typename T >
1041	typename internal::ConstCharArrayDetector< T, bool >::Type
1042	endsWith(T & literal, OUString * rest = 0) const
1043	{
1044	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1045	bool b = internal::ConstCharArrayDetector< T, void >::size - 1 <= pData->length
1046	&& rtl_ustr_asciil_reverseEquals_WithLength(
1047	pData->buffer + pData->length - ( internal::ConstCharArrayDetector< T, void >::size - 1 ), literal,
1048	internal::ConstCharArrayDetector< T, void >::size - 1);
1049	if (b && rest != 0) {
1050	*rest = copy(
1051	0,
1052	(getLength()
1053	- (internal::ConstCharArrayDetector< T, void >::size - 1)));
1054	}
1055	return b;
1056	}
1057
1058	/**
1059	Check whether this string ends with a given ASCII string.
1060
1061	@param asciiStr a sequence of at least asciiStrLength ASCII characters
1062	(bytes in the range 0x00--0x7F)
1063	@param asciiStrLength the length of asciiStr; must be non-negative
1064	@return true if this string ends with asciiStr; otherwise, false is
1065	returned
1066
1067	@since UDK 3.2.7
1068	*/
1069	inline bool endsWithAsciiL(char const * asciiStr, sal_Int32 asciiStrLength)
1070	const
1071	{
1072	return asciiStrLength <= pData->length
1073	&& rtl_ustr_asciil_reverseEquals_WithLength(
1074	pData->buffer + pData->length - asciiStrLength, asciiStr,
1075	asciiStrLength);
1076	}
1077
1078	/**
1079	Check whether this string ends with a given string, ignoring the case of
1080	ASCII letters.
1081
1082	Character values between 65 and 90 (ASCII A-Z) are interpreted as
1083	values between 97 and 122 (ASCII a-z).
1084	This function can't be used for language specific comparison.
1085
1086	@param str the substring to be compared
1087
1088	@param rest if non-null, and this function returns true, then assign a
1089	copy of the remainder of this string to *rest. Available since
1090	LibreOffice 4.2
1091
1092	@return true if and only if the given str appears as a substring at the
1093	end of this string, ignoring the case of ASCII letters ("A"--"Z" and
1094	"a"--"z")
1095
1096	@since LibreOffice 3.6
1097	*/
1098	bool endsWithIgnoreAsciiCase(OUString const & str, OUString * rest) const
1099	{
1100	bool b = str.getLength() <= getLength()
1101	&& matchIgnoreAsciiCase(str, getLength() - str.getLength());
1102	if (b && rest != 0) {
1103	*rest = copy(0, getLength() - str.getLength());
1104	}
1105	return b;
1106	}
1107
1108	/**
1109	@overload
1110	This function accepts an ASCII string literal as its argument.
1111	@since LibreOffice 3.6
1112	*/
1113	template< typename T >
1114	typename internal::ConstCharArrayDetector< T, bool >::Type
1115	endsWithIgnoreAsciiCase(T & literal, OUString * rest = 0) const
1116	{
1117	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1118	bool b = internal::ConstCharArrayDetector< T, void >::size - 1 <= pData->length
1119	&& (rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
1120	pData->buffer + pData->length - ( internal::ConstCharArrayDetector< T, void >::size - 1 ),
1121	internal::ConstCharArrayDetector< T, void >::size - 1, literal,
1122	internal::ConstCharArrayDetector< T, void >::size - 1)
1123	== 0);
1124	if (b && rest != 0) {
1125	*rest = copy(
1126	0,
1127	(getLength()
1128	- (internal::ConstCharArrayDetector< T, void >::size - 1)));
1129	}
1130	return b;
1131	}
1132
1133	/**
1134	Check whether this string ends with a given ASCII string, ignoring the
1135	case of ASCII letters.
1136
1137	@param asciiStr a sequence of at least asciiStrLength ASCII characters
1138	(bytes in the range 0x00--0x7F)
1139	@param asciiStrLength the length of asciiStr; must be non-negative
1140	@return true if this string ends with asciiStr, ignoring the case of ASCII
1141	letters ("A"--"Z" and "a"--"z"); otherwise, false is returned
1142	*/
1143	inline bool endsWithIgnoreAsciiCaseAsciiL(
1144	char const * asciiStr, sal_Int32 asciiStrLength) const
1145	{
1146	return asciiStrLength <= pData->length
1147	&& (rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
1148	pData->buffer + pData->length - asciiStrLength,
1149	asciiStrLength, asciiStr, asciiStrLength)
1150	== 0);
1151	}
1152
1153	friend bool operator == ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1154	{ return rStr1.equals(rStr2); }
1155	friend bool operator == ( const OUString& rStr1, const sal_Unicode * pStr2 ) SAL_THROW(())
1156	{ return rStr1.compareTo( pStr2 ) == 0; }
1157	friend bool operator == ( const sal_Unicode * pStr1, const OUString& rStr2 ) SAL_THROW(())
1158	{ return OUString( pStr1 ).compareTo( rStr2 ) == 0; }
1159
1160	friend bool operator != ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1161	{ return !(operator == ( rStr1, rStr2 )); }
1162	friend bool operator != ( const OUString& rStr1, const sal_Unicode * pStr2 ) SAL_THROW(())
1163	{ return !(operator == ( rStr1, pStr2 )); }
1164	friend bool operator != ( const sal_Unicode * pStr1, const OUString& rStr2 ) SAL_THROW(())
1165	{ return !(operator == ( pStr1, rStr2 )); }
1166
1167	friend bool operator < ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1168	{ return rStr1.compareTo( rStr2 ) < 0; }
1169	friend bool operator > ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1170	{ return rStr1.compareTo( rStr2 ) > 0; }
1171	friend bool operator <= ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1172	{ return rStr1.compareTo( rStr2 ) <= 0; }
1173	friend bool operator >= ( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1174	{ return rStr1.compareTo( rStr2 ) >= 0; }
1175
1176	/**
1177	* Compare string to an ASCII string literal.
1178	*
1179	* This operator is equal to calling equalsAsciiL().
1180	*
1181	* @since LibreOffice 3.6
1182	*/
1183	template< typename T >
1184	friend inline typename internal::ConstCharArrayDetector< T, bool >::Type operator==( const OUString& string, T& literal )
1185	{
1186	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1187	return string.equalsAsciiL( literal, internal::ConstCharArrayDetector< T, void >::size - 1 );
1188	}
1189	/**
1190	* Compare string to an ASCII string literal.
1191	*
1192	* This operator is equal to calling equalsAsciiL().
1193	*
1194	* @since LibreOffice 3.6
1195	*/
1196	template< typename T >
1197	friend inline typename internal::ConstCharArrayDetector< T, bool >::Type operator==( T& literal, const OUString& string )
1198	{
1199	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1200	return string.equalsAsciiL( literal, internal::ConstCharArrayDetector< T, void >::size - 1 );
1201	}
1202	/**
1203	* Compare string to an ASCII string literal.
1204	*
1205	* This operator is equal to calling !equalsAsciiL().
1206	*
1207	* @since LibreOffice 3.6
1208	*/
1209	template< typename T >
1210	friend inline typename internal::ConstCharArrayDetector< T, bool >::Type operator!=( const OUString& string, T& literal )
1211	{
1212	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1213	return !string.equalsAsciiL( literal, internal::ConstCharArrayDetector< T, void >::size - 1 );
1214	}
1215	/**
1216	* Compare string to an ASCII string literal.
1217	*
1218	* This operator is equal to calling !equalsAsciiL().
1219	*
1220	* @since LibreOffice 3.6
1221	*/
1222	template< typename T >
1223	friend inline typename internal::ConstCharArrayDetector< T, bool >::Type operator!=( T& literal, const OUString& string )
1224	{
1225	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1226	return !string.equalsAsciiL( literal, internal::ConstCharArrayDetector< T, void >::size - 1 );
1227	}
1228
1229	/**
1230	Returns a hashcode for this string.
1231
1232	@return a hash code value for this object.
1233
1234	@see rtl::OUStringHash for convenient use of boost::unordered_map
1235	*/
1236	sal_Int32 hashCode() const SAL_THROW(())
1237	{
1238	return rtl_ustr_hashCode_WithLength( pData->buffer, pData->length );
1239	}
1240
1241	/**
1242	Returns the index within this string of the first occurrence of the
1243	specified character, starting the search at the specified index.
1244
1245	@param ch character to be located.
1246	@param fromIndex the index to start the search from.
1247	The index must be greater than or equal to 0
1248	and less than or equal to the string length.
1249	@return the index of the first occurrence of the character in the
1250	character sequence represented by this string that is
1251	greater than or equal to fromIndex, or
1252	-1 if the character does not occur.
1253	*/
1254	sal_Int32 indexOf( sal_Unicode ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
1255	{
1256	sal_Int32 ret = rtl_ustr_indexOfChar_WithLength( pData->buffer+fromIndex, pData->length-fromIndex, ch );
1257	return (ret < 0 ? ret : ret+fromIndex);
1258	}
1259
1260	/**
1261	Returns the index within this string of the last occurrence of the
1262	specified character, searching backward starting at the end.
1263
1264	@param ch character to be located.
1265	@return the index of the last occurrence of the character in the
1266	character sequence represented by this string, or
1267	-1 if the character does not occur.
1268	*/
1269	sal_Int32 lastIndexOf( sal_Unicode ch ) const SAL_THROW(())
1270	{
1271	return rtl_ustr_lastIndexOfChar_WithLength( pData->buffer, pData->length, ch );
1272	}
1273
1274	/**
1275	Returns the index within this string of the last occurrence of the
1276	specified character, searching backward starting before the specified
1277	index.
1278
1279	@param ch character to be located.
1280	@param fromIndex the index before which to start the search.
1281	@return the index of the last occurrence of the character in the
1282	character sequence represented by this string that
1283	is less than fromIndex, or -1
1284	if the character does not occur before that point.
1285	*/
1286	sal_Int32 lastIndexOf( sal_Unicode ch, sal_Int32 fromIndex ) const SAL_THROW(())
1287	{
1288	return rtl_ustr_lastIndexOfChar_WithLength( pData->buffer, fromIndex, ch );
1289	}
1290
1291	/**
1292	Returns the index within this string of the first occurrence of the
1293	specified substring, starting at the specified index.
1294
1295	If str doesn't include any character, always -1 is
1296	returned. This is also the case, if both strings are empty.
1297
1298	@param str the substring to search for.
1299	@param fromIndex the index to start the search from.
1300	@return If the string argument occurs one or more times as a substring
1301	within this string at the starting index, then the index
1302	of the first character of the first such substring is
1303	returned. If it does not occur as a substring starting
1304	at fromIndex or beyond, -1 is returned.
1305	*/
1306	sal_Int32 indexOf( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
1307	{
1308	sal_Int32 ret = rtl_ustr_indexOfStr_WithLength( pData->buffer+fromIndex, pData->length-fromIndex,
1309	str.pData->buffer, str.pData->length );
1310	return (ret < 0 ? ret : ret+fromIndex);
1311	}
1312
1313	/**
1314	@overload
1315	This function accepts an ASCII string literal as its argument.
1316	@since LibreOffice 3.6
1317	*/
1318	template< typename T >
1319	typename internal::ConstCharArrayDetector< T, sal_Int32 >::Type indexOf( T& literal, sal_Int32 fromIndex = 0 ) const SAL_THROW(())
1320	{
1321	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1322	sal_Int32 ret = rtl_ustr_indexOfAscii_WithLength(
1323	pData->buffer + fromIndex, pData->length - fromIndex, literal,
1324	internal::ConstCharArrayDetector< T, void >::size - 1);
1325	return ret < 0 ? ret : ret + fromIndex;
1326	}
1327
1328	/**
1329	Returns the index within this string of the first occurrence of the
1330	specified ASCII substring, starting at the specified index.
1331
1332	@param str
1333	the substring to be searched for. Need not be null-terminated, but must
1334	be at least as long as the specified len. Must only contain characters
1335	in the ASCII range 0x00--7F.
1336
1337	@param len
1338	the length of the substring; must be non-negative.
1339
1340	@param fromIndex
1341	the index to start the search from. Must be in the range from zero to
1342	the length of this string, inclusive.
1343
1344	@return
1345	the index (starting at 0) of the first character of the first occurrence
1346	of the substring within this string starting at the given fromIndex, or
1347	-1 if the substring does not occur. If len is zero, -1 is returned.
1348
1349	@since UDK 3.2.7
1350	*/
1351	sal_Int32 indexOfAsciiL(
1352	char const * str, sal_Int32 len, sal_Int32 fromIndex = 0) const
1353	SAL_THROW(())
1354	{
1355	sal_Int32 ret = rtl_ustr_indexOfAscii_WithLength(
1356	pData->buffer + fromIndex, pData->length - fromIndex, str, len);
1357	return ret < 0 ? ret : ret + fromIndex;
1358	}
1359
1360	// This overload is left undefined, to detect calls of indexOfAsciiL that
1361	// erroneously use RTL_CONSTASCII_USTRINGPARAM instead of
1362	// RTL_CONSTASCII_STRINGPARAM (but would lead to ambiguities on 32 bit
1363	// platforms):
1364	#if SAL_TYPES_SIZEOFLONG == 8
1365	void indexOfAsciiL(char const *, sal_Int32 len, rtl_TextEncoding) const;
1366	#endif
1367
1368	/**
1369	Returns the index within this string of the last occurrence of
1370	the specified substring, searching backward starting at the end.
1371
1372	The returned index indicates the starting index of the substring
1373	in this string.
1374	If str doesn't include any character, always -1 is
1375	returned. This is also the case, if both strings are empty.
1376
1377	@param str the substring to search for.
1378	@return If the string argument occurs one or more times as a substring
1379	within this string, then the index of the first character of
1380	the last such substring is returned. If it does not occur as
1381	a substring, -1 is returned.
1382	*/
1383	sal_Int32 lastIndexOf( const OUString & str ) const SAL_THROW(())
1384	{
1385	return rtl_ustr_lastIndexOfStr_WithLength( pData->buffer, pData->length,
1386	str.pData->buffer, str.pData->length );
1387	}
1388
1389	/**
1390	Returns the index within this string of the last occurrence of
1391	the specified substring, searching backward starting before the specified
1392	index.
1393
1394	The returned index indicates the starting index of the substring
1395	in this string.
1396	If str doesn't include any character, always -1 is
1397	returned. This is also the case, if both strings are empty.
1398
1399	@param str the substring to search for.
1400	@param fromIndex the index before which to start the search.
1401	@return If the string argument occurs one or more times as a substring
1402	within this string before the starting index, then the index
1403	of the first character of the last such substring is
1404	returned. Otherwise, -1 is returned.
1405	*/
1406	sal_Int32 lastIndexOf( const OUString & str, sal_Int32 fromIndex ) const SAL_THROW(())
1407	{
1408	return rtl_ustr_lastIndexOfStr_WithLength( pData->buffer, fromIndex,
1409	str.pData->buffer, str.pData->length );
1410	}
1411
1412	/**
1413	@overload
1414	This function accepts an ASCII string literal as its argument.
1415	@since LibreOffice 3.6
1416	*/
1417	template< typename T >
1418	typename internal::ConstCharArrayDetector< T, sal_Int32 >::Type lastIndexOf( T& literal ) const SAL_THROW(())
1419	{
1420	assert( strlen( literal ) == internal::ConstCharArrayDetector< T >::size - 1 );
1421	return rtl_ustr_lastIndexOfAscii_WithLength(
1422	pData->buffer, pData->length, literal, internal::ConstCharArrayDetector< T, void >::size - 1);
1423	}
1424
1425	/**
1426	Returns the index within this string of the last occurrence of the
1427	specified ASCII substring.
1428
1429	@param str
1430	the substring to be searched for. Need not be null-terminated, but must
1431	be at least as long as the specified len. Must only contain characters
1432	in the ASCII range 0x00--7F.
1433
1434	@param len
1435	the length of the substring; must be non-negative.
1436
1437	@return
1438	the index (starting at 0) of the first character of the last occurrence
1439	of the substring within this string, or -1 if the substring does not
1440	occur. If len is zero, -1 is returned.
1441
1442	@since UDK 3.2.7
1443	*/
1444	sal_Int32 lastIndexOfAsciiL(char const * str, sal_Int32 len) const
1445	SAL_THROW(())
1446	{
1447	return rtl_ustr_lastIndexOfAscii_WithLength(
1448	pData->buffer, pData->length, str, len);
1449	}
1450
1451	/**
1452	Returns a new string that is a substring of this string.
1453
1454	The substring begins at the specified beginIndex. If
1455	beginIndex is negative or be greater than the length of
1456	this string, behaviour is undefined.
1457
1458	@param beginIndex the beginning index, inclusive.
1459	@return the specified substring.
1460	*/
1461	SAL_WARN_UNUSED_RESULT OUString copy( sal_Int32 beginIndex ) const SAL_THROW(())
1462	{
1463	rtl_uString *pNew = 0;
1464	rtl_uString_newFromSubString( &pNew, pData, beginIndex, getLength() - beginIndex );
1465	return OUString( pNew, SAL_NO_ACQUIRE );
1466	}
1467
1468	/**
1469	Returns a new string that is a substring of this string.
1470
1471	The substring begins at the specified beginIndex and contains count
1472	characters. If either beginIndex or count are negative,
1473	or beginIndex + count are greater than the length of this string
1474	then behaviour is undefined.
1475
1476	@param beginIndex the beginning index, inclusive.
1477	@param count the number of characters.
1478	@return the specified substring.
1479	*/
1480	SAL_WARN_UNUSED_RESULT OUString copy( sal_Int32 beginIndex, sal_Int32 count ) const SAL_THROW(())
1481	{
1482	rtl_uString *pNew = 0;
1483	rtl_uString_newFromSubString( &pNew, pData, beginIndex, count );
1484	return OUString( pNew, SAL_NO_ACQUIRE );
1485	}
1486
1487	/**
1488	Concatenates the specified string to the end of this string.
1489
1490	@param str the string that is concatenated to the end
1491	of this string.
1492	@return a string that represents the concatenation of this string
1493	followed by the string argument.
1494	*/
1495	SAL_WARN_UNUSED_RESULT OUString concat( const OUString & str ) const SAL_THROW(())
1496	{
1497	rtl_uString* pNew = 0;
1498	rtl_uString_newConcat( &pNew, pData, str.pData );
1499	return OUString( pNew, SAL_NO_ACQUIRE );
1500	}
1501
1502	#ifndef RTL_FAST_STRING
1503	friend OUString operator+( const OUString& rStr1, const OUString& rStr2 ) SAL_THROW(())
1504	{
1505	return rStr1.concat( rStr2 );
1506	}
1507	#endif
1508
1509	/**
1510	Returns a new string resulting from replacing n = count characters
1511	from position index in this string with newStr.
1512
1513	@param index the replacing index in str.
1514	The index must be greater than or equal to 0 and
1515	less than or equal to the length of the string.
1516	@param count the count of characters that will be replaced
1517	The count must be greater than or equal to 0 and
1518	less than or equal to the length of the string minus index.
1519	@param newStr the new substring.
1520	@return the new string.
1521	*/
1522	SAL_WARN_UNUSED_RESULT OUString replaceAt( sal_Int32 index, sal_Int32 count, const OUString& newStr ) const SAL_THROW(())
1523	{
1524	rtl_uString* pNew = 0;
1525	rtl_uString_newReplaceStrAt( &pNew, pData, index, count, newStr.pData );
1526	return OUString( pNew, SAL_NO_ACQUIRE );
1527	}
1528
1529	/**
1530	Returns a new string resulting from replacing all occurrences of
1531	oldChar in this string with newChar.
1532
1533	If the character oldChar does not occur in the character sequence
1534	represented by this object, then the string is assigned with
1535	str.
1536
1537	@param oldChar the old character.
1538	@param newChar the new character.
1539	@return a string derived from this string by replacing every
1540	occurrence of oldChar with newChar.
1541	*/
1542	SAL_WARN_UNUSED_RESULT OUString replace( sal_Unicode oldChar, sal_Unicode newChar ) const SAL_THROW(())
1543	{
1544	rtl_uString* pNew = 0;
1545	rtl_uString_newReplace( &pNew, pData, oldChar, newChar );
1546	return OUString( pNew, SAL_NO_ACQUIRE );
1547	}
1548
1549	/**
1550	Returns a new string resulting from replacing the first occurrence of a
1551	given substring with another substring.
1552
1553	@param from the substring to be replaced
1554
1555	@param to the replacing substring
1556
1557	@param[in,out] index pointer to a start index; if the pointer is
1558	non-null: upon entry to the function, its value is the index into this
1559	string at which to start searching for the \p from substring, the value
1560	must be non-negative and not greater than this string's length; upon exiting
1561	the function its value is the index into this string at which the
1562	replacement took place or -1 if no replacement took place; if the pointer
1563	is null, searching always starts at index 0
1564
1565	@since LibreOffice 3.6
1566	*/
1567	SAL_WARN_UNUSED_RESULT OUString replaceFirst(
1568	OUString const & from, OUString const & to, sal_Int32 * index = 0) const
1569	{
1570	rtl_uString * s = 0;
1571	sal_Int32 i = 0;
1572	rtl_uString_newReplaceFirst(
1573	&s, pData, from.pData, to.pData, index == 0 ? &i : index);
1574	return OUString(s, SAL_NO_ACQUIRE);
1575	}
1576
1577	/**
1578	Returns a new string resulting from replacing the first occurrence of a
1579	given substring with another substring.
1580
1581	@param from ASCII string literal, the substring to be replaced
1582
1583	@param to the replacing substring
1584
1585	@param[in,out] index pointer to a start index; if the pointer is
1586	non-null: upon entry to the function, its value is the index into the this
1587	string at which to start searching for the \p from substring, the value
1588	must be non-negative and not greater than this string's length; upon exiting
1589	the function its value is the index into this string at which the
1590	replacement took place or -1 if no replacement took place; if the pointer
1591	is null, searching always starts at index 0
1592
1593	@since LibreOffice 3.6
1594	*/
1595	template< typename T >
1596	SAL_WARN_UNUSED_RESULT typename internal::ConstCharArrayDetector< T, OUString >::Type replaceFirst( T& from, OUString const & to,
1597	sal_Int32 * index = 0) const
1598	{
1599	rtl_uString * s = 0;
1600	sal_Int32 i = 0;
1601	assert( strlen( from ) == internal::ConstCharArrayDetector< T >::size - 1 );
1602	rtl_uString_newReplaceFirstAsciiL(
1603	&s, pData, from, internal::ConstCharArrayDetector< T, void >::size - 1, to.pData, index == 0 ? &i : index);
1604	return OUString(s, SAL_NO_ACQUIRE);
1605	}
1606
1607	/**
1608	Returns a new string resulting from replacing the first occurrence of a
1609	given substring with another substring.
1610
1611	@param from ASCII string literal, the substring to be replaced
1612
1613	@param to ASCII string literal, the substring to be replaced
1614
1615	@param[in,out] index pointer to a start index; if the pointer is
1616	non-null: upon entry to the function, its value is the index into the this
1617	string at which to start searching for the \p from substring, the value
1618	must be non-negative and not greater than this string's length; upon exiting
1619	the function its value is the index into this string at which the
1620	replacement took place or -1 if no replacement took place; if the pointer
1621	is null, searching always starts at index 0
1622
1623	@since LibreOffice 3.6
1624	*/
1625	template< typename T1, typename T2 >
1626	SAL_WARN_UNUSED_RESULT typename internal::ConstCharArrayDetector< T1, typename internal::ConstCharArrayDetector< T2, OUString >::Type >::Type
1627	replaceFirst( T1& from, T2& to, sal_Int32 * index = 0) const
1628	{
1629	rtl_uString * s = 0;
1630	sal_Int32 i = 0;
1631	assert( strlen( from ) == internal::ConstCharArrayDetector< T1 >::size - 1 );
1632	assert( strlen( to ) == internal::ConstCharArrayDetector< T2 >::size - 1 );
1633	rtl_uString_newReplaceFirstAsciiLAsciiL(
1634	&s, pData, from, internal::ConstCharArrayDetector< T1, void >::size - 1, to,
1635	internal::ConstCharArrayDetector< T2, void >::size - 1, index == 0 ? &i : index);
1636	return OUString(s, SAL_NO_ACQUIRE);
1637	}
1638
1639	/**
1640	Returns a new string resulting from replacing all occurrences of a given
1641	substring with another substring.
1642
1643	Replacing subsequent occurrences picks up only after a given replacement.
1644	That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1645
1646	@param from the substring to be replaced
1647
1648	@param to the replacing substring
1649
1650	@param fromIndex the position in the string where we will begin searching
1651
1652	@since LibreOffice 4.0
1653	*/
1654	SAL_WARN_UNUSED_RESULT OUString replaceAll(
1655	OUString const & from, OUString const & to, sal_Int32 fromIndex = 0) const
1656	{
1657	rtl_uString * s = 0;
1658	rtl_uString_newReplaceAllFromIndex(&s, pData, from.pData, to.pData, fromIndex);
1659	return OUString(s, SAL_NO_ACQUIRE);
1660	}
1661
1662	/**
1663	Returns a new string resulting from replacing all occurrences of a given
1664	substring with another substring.
1665
1666	Replacing subsequent occurrences picks up only after a given replacement.
1667	That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1668
1669	@param from ASCII string literal, the substring to be replaced
1670
1671	@param to the replacing substring
1672
1673	@since LibreOffice 3.6
1674	*/
1675	template< typename T >
1676	SAL_WARN_UNUSED_RESULT typename internal::ConstCharArrayDetector< T, OUString >::Type replaceAll( T& from, OUString const & to) const
1677	{
1678	rtl_uString * s = 0;
1679	assert( strlen( from ) == internal::ConstCharArrayDetector< T >::size - 1 );
1680	rtl_uString_newReplaceAllAsciiL(&s, pData, from, internal::ConstCharArrayDetector< T, void >::size - 1, to.pData);
1681	return OUString(s, SAL_NO_ACQUIRE);
1682	}
1683
1684	/**
1685	Returns a new string resulting from replacing all occurrences of a given
1686	substring with another substring.
1687
1688	Replacing subsequent occurrences picks up only after a given replacement.
1689	That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1690
1691	@param from ASCII string literal, the substring to be replaced
1692
1693	@param to ASCII string literal, the substring to be replaced
1694
1695	@since LibreOffice 3.6
1696	*/
1697	template< typename T1, typename T2 >
1698	SAL_WARN_UNUSED_RESULT typename internal::ConstCharArrayDetector< T1, typename internal::ConstCharArrayDetector< T2, OUString >::Type >::Type
1699	replaceAll( T1& from, T2& to ) const
1700	{
1701	rtl_uString * s = 0;
1702	assert( strlen( from ) == internal::ConstCharArrayDetector< T1 >::size - 1 );
1703	assert( strlen( to ) == internal::ConstCharArrayDetector< T2 >::size - 1 );
1704	rtl_uString_newReplaceAllAsciiLAsciiL(
1705	&s, pData, from, internal::ConstCharArrayDetector< T1, void >::size - 1,
1706	to, internal::ConstCharArrayDetector< T2, void >::size - 1);
1707	return OUString(s, SAL_NO_ACQUIRE);
1708	}
1709
1710	/**
1711	Converts from this string all ASCII uppercase characters (65-90)
1712	to ASCII lowercase characters (97-122).
1713
1714	This function can't be used for language specific conversion.
1715	If the string doesn't contain characters which must be converted,
1716	then the new string is assigned with str.
1717
1718	@return the string, converted to ASCII lowercase.
1719	*/
1720	SAL_WARN_UNUSED_RESULT OUString toAsciiLowerCase() const SAL_THROW(())
1721	{
1722	rtl_uString* pNew = 0;
1723	rtl_uString_newToAsciiLowerCase( &pNew, pData );
1724	return OUString( pNew, SAL_NO_ACQUIRE );
1725	}
1726
1727	/**
1728	Converts from this string all ASCII lowercase characters (97-122)
1729	to ASCII uppercase characters (65-90).
1730
1731	This function can't be used for language specific conversion.
1732	If the string doesn't contain characters which must be converted,
1733	then the new string is assigned with str.
1734
1735	@return the string, converted to ASCII uppercase.
1736	*/
1737	SAL_WARN_UNUSED_RESULT OUString toAsciiUpperCase() const SAL_THROW(())
1738	{
1739	rtl_uString* pNew = 0;
1740	rtl_uString_newToAsciiUpperCase( &pNew, pData );
1741	return OUString( pNew, SAL_NO_ACQUIRE );
1742	}
1743
1744	/**
1745	Returns a new string resulting from removing white space from both ends
1746	of the string.
1747
1748	All characters that have codes less than or equal to
1749	32 (the space character) are considered to be white space.
1750	If the string doesn't contain white spaces at both ends,
1751	then the new string is assigned with str.
1752
1753	@return the string, with white space removed from the front and end.
1754	*/
1755	SAL_WARN_UNUSED_RESULT OUString trim() const SAL_THROW(())
1756	{
1757	rtl_uString* pNew = 0;
1758	rtl_uString_newTrim( &pNew, pData );
1759	return OUString( pNew, SAL_NO_ACQUIRE );
1760	}
1761
1762	/**
1763	Returns a token in the string.
1764
1765	Example:
1766	sal_Int32 nIndex = 0;
1767	do
1768	{
1769	...
1770	OUString aToken = aStr.getToken( 0, ';', nIndex );
1771	...
1772	}
1773	while ( nIndex >= 0 );
1774
1775	@param token the number of the token to return
1776	@param cTok the character which separate the tokens.
1777	@param index the position at which the token is searched in the
1778	string.
1779	The index must not be greater than the length of the
1780	string.
1781	This param is set to the position of the
1782	next token or to -1, if it is the last token.
1783	@return the token; if either token or index is negative, an empty token
1784	is returned (and index is set to -1)
1785	*/
1786	OUString getToken( sal_Int32 token, sal_Unicode cTok, sal_Int32& index ) const SAL_THROW(())
1787	{
1788	rtl_uString * pNew = 0;
1789	index = rtl_uString_getToken( &pNew, pData, token, cTok, index );
1790	return OUString( pNew, SAL_NO_ACQUIRE );
1791	}
1792
1793	/**
1794	Returns a token from the string.
1795
1796	The same as getToken(sal_Int32, sal_Unicode, sal_Int32 &), but always
1797	passing in 0 as the start index in the third argument.
1798
1799	@param count the number of the token to return, starting with 0
1800	@param separator the character which separates the tokens
1801
1802	@return the given token, or an empty string
1803
1804	@since LibreOffice 3.6
1805	*/
1806	OUString getToken(sal_Int32 count, sal_Unicode separator) const {
1807	sal_Int32 n = 0;
1808	return getToken(count, separator, n);
1809	}
1810
1811	/**
1812	Returns the Boolean value from this string.
1813
1814	This function can't be used for language specific conversion.
1815
1816	@return true, if the string is 1 or "True" in any ASCII case.
1817	false in any other case.
1818	*/
1819	bool toBoolean() const SAL_THROW(())
1820	{
1821	return rtl_ustr_toBoolean( pData->buffer );
1822	}
1823
1824	/**
1825	Returns the first character from this string.
1826
1827	@return the first character from this string or 0, if this string
1828	is emptry.
1829	*/
1830	sal_Unicode toChar() const SAL_THROW(())
1831	{
1832	return pData->buffer[0];
1833	}
1834
1835	/**
1836	Returns the int32 value from this string.
1837
1838	This function can't be used for language specific conversion.
1839
1840	@param radix the radix (between 2 and 36)
1841	@return the int32 represented from this string.
1842	0 if this string represents no number or one of too large
1843	magnitude.
1844	*/
1845	sal_Int32 toInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
1846	{
1847	return rtl_ustr_toInt32( pData->buffer, radix );
1848	}
1849
1850	/**
1851	Returns the uint32 value from this string.
1852
1853	This function can't be used for language specific conversion.
1854
1855	@param radix the radix (between 2 and 36)
1856	@return the uint32 represented from this string.
1857	0 if this string represents no number or one of too large
1858	magnitude.
1859
1860	@since LibreOffice 4.2
1861	*/
1862	sal_uInt32 toUInt32( sal_Int16 radix = 10 ) const SAL_THROW(())
1863	{
1864	return rtl_ustr_toUInt32( pData->buffer, radix );
1865	}
1866
1867	/**
1868	Returns the int64 value from this string.
1869
1870	This function can't be used for language specific conversion.
1871
1872	@param radix the radix (between 2 and 36)
1873	@return the int64 represented from this string.
1874	0 if this string represents no number or one of too large
1875	magnitude.
1876	*/
1877	sal_Int64 toInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
1878	{
1879	return rtl_ustr_toInt64( pData->buffer, radix );
1880	}
1881
1882	/**
1883	Returns the uint64 value from this string.
1884
1885	This function can't be used for language specific conversion.
1886
1887	@param radix the radix (between 2 and 36)
1888	@return the uint64 represented from this string.
1889	0 if this string represents no number or one of too large
1890	magnitude.
1891
1892	@since LibreOffice 4.1
1893	*/
1894	sal_uInt64 toUInt64( sal_Int16 radix = 10 ) const SAL_THROW(())
1895	{
1896	return rtl_ustr_toUInt64( pData->buffer, radix );
1897	}
1898
1899	/**
1900	Returns the float value from this string.
1901
1902	This function can't be used for language specific conversion.
1903
1904	@return the float represented from this string.
1905	0.0 if this string represents no number.
1906	*/
1907	float toFloat() const SAL_THROW(())
1908	{
1909	return rtl_ustr_toFloat( pData->buffer );
1910	}
1911
1912	/**
1913	Returns the double value from this string.
1914
1915	This function can't be used for language specific conversion.
1916
1917	@return the double represented from this string.
1918	0.0 if this string represents no number.
1919	*/
1920	double toDouble() const SAL_THROW(())
1921	{
1922	return rtl_ustr_toDouble( pData->buffer );
1923	}
1924
1925
1926	/**
1927	Return a canonical representation for a string.
1928
1929	A pool of strings, initially empty is maintained privately
1930	by the string class. On invocation, if present in the pool
1931	the original string will be returned. Otherwise this string,
1932	or a copy thereof will be added to the pool and returned.
1933
1934	@return
1935	a version of the string from the pool.
1936
1937	@exception std::bad_alloc is thrown if an out-of-memory condition occurs
1938
1939	@since UDK 3.2.7
1940	*/
1941	OUString intern() const
1942	{
1943	rtl_uString * pNew = 0;
1944	rtl_uString_intern( &pNew, pData );
1945	if (pNew == 0) {
1946	throw std::bad_alloc();
1947	}
1948	return OUString( pNew, SAL_NO_ACQUIRE );
1949	}
1950
1951	/**
1952	Return a canonical representation for a converted string.
1953
1954	A pool of strings, initially empty is maintained privately
1955	by the string class. On invocation, if present in the pool
1956	the original string will be returned. Otherwise this string,
1957	or a copy thereof will be added to the pool and returned.
1958
1959	@param value a 8-Bit character array.
1960	@param length the number of character which should be converted.
1961	The 8-Bit character array length must be
1962	greater than or equal to this value.
1963	@param encoding the text encoding from which the 8-Bit character
1964	sequence should be converted.
1965	@param convertFlags flags which controls the conversion.
1966	see RTL_TEXTTOUNICODE_FLAGS_...
1967	@param pInfo pointer to return conversion status or NULL.
1968
1969	@return
1970	a version of the converted string from the pool.
1971
1972	@exception std::bad_alloc is thrown if an out-of-memory condition occurs
1973
1974	@since UDK 3.2.7
1975	*/
1976	static OUString intern( const sal_Char * value, sal_Int32 length,
1977	rtl_TextEncoding encoding,
1978	sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS,
1979	sal_uInt32 *pInfo = NULL )
1980	{
1981	rtl_uString * pNew = 0;
1982	rtl_uString_internConvert( &pNew, value, length, encoding,
1983	convertFlags, pInfo );
1984	if (pNew == 0) {
1985	throw std::bad_alloc();
1986	}
1987	return OUString( pNew, SAL_NO_ACQUIRE );
1988	}
1989
1990	/**
1991	Converts to an OString, signalling failure.
1992
1993	@param pTarget
1994	An out parameter receiving the converted OString. Must not be null; the
1995	contents are not modified if conversion fails (convertToOString returns
1996	false).
1997
1998	@param nEncoding
1999	The text encoding to convert into. Must be an octet encoding (i.e.,
2000	rtl_isOctetTextEncoding(nEncoding) must return true).
2001
2002	@param nFlags
2003	A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the
2004	conversion (see rtl_convertUnicodeToText). RTL_UNICODETOTEXT_FLAGS_FLUSH
2005	need not be included, it is implicitly assumed. Typical uses are either
2006	RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
2007	RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot
2008	be converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS
2009	(make a best efforts conversion).
2010
2011	@return
2012	True if the conversion succeeded, false otherwise.
2013	*/
2014	inline bool convertToString(OString * pTarget, rtl_TextEncoding nEncoding,
2015	sal_uInt32 nFlags) const
2016	{
2017	return rtl_convertUStringToString(&pTarget->pData, pData->buffer,
2018	pData->length, nEncoding, nFlags);
2019	}
2020
2021	/** Iterate through this string based on code points instead of UTF-16 code
2022	units.
2023
2024	See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for
2025	definitions of the various terms used in this description.
2026
2027	This string is interpreted as a sequence of zero or more UTF-16 code
2028	units. For each index into this sequence (from zero to one less than
2029	the length of the sequence, inclusive), a code point represented
2030	starting at the given index is computed as follows:
2031
2032	- If the UTF-16 code unit addressed by the index constitutes a
2033	well-formed UTF-16 code unit sequence, the computed code point is the
2034	scalar value encoded by that UTF-16 code unit sequence.
2035
2036	- Otherwise, if the index is at least two UTF-16 code units away from
2037	the end of the sequence, and the sequence of two UTF-16 code units
2038	addressed by the index constitutes a well-formed UTF-16 code unit
2039	sequence, the computed code point is the scalar value encoded by that
2040	UTF-16 code unit sequence.
2041
2042	- Otherwise, the computed code point is the UTF-16 code unit addressed
2043	by the index. (This last case catches unmatched surrogates as well as
2044	indices pointing into the middle of surrogate pairs.)
2045
2046	@param indexUtf16
2047	pointer to a UTF-16 based index into this string; must not be null. On
2048	entry, the index must be in the range from zero to the length of this
2049	string (in UTF-16 code units), inclusive. Upon successful return, the
2050	index will be updated to address the UTF-16 code unit that is the given
2051	incrementCodePoints away from the initial index.
2052
2053	@param incrementCodePoints
2054	the number of code points to move the given *indexUtf16. If
2055	non-negative, moving is done after determining the code point at the
2056	index. If negative, moving is done before determining the code point
2057	at the (then updated) index. The value must be such that the resulting
2058	UTF-16 based index is in the range from zero to the length of this
2059	string (in UTF-16 code units), inclusive.
2060
2061	@return
2062	the code point (an integer in the range from 0 to 0x10FFFF, inclusive)
2063	that is represented within this string starting at the index computed as
2064	follows: If incrementCodePoints is non-negative, the index is the
2065	initial value of *indexUtf16; if incrementCodePoints is negative, the
2066	index is the updated value of *indexUtf16. In either case, the computed
2067	index must be in the range from zero to one less than the length of this
2068	string (in UTF-16 code units), inclusive.
2069
2070	@since UDK 3.2.7
2071	*/
2072	inline sal_uInt32 iterateCodePoints(
2073	sal_Int32 * indexUtf16, sal_Int32 incrementCodePoints = 1) const
2074	{
2075	return rtl_uString_iterateCodePoints(
2076	pData, indexUtf16, incrementCodePoints);
2077	}
2078
2079	/**
2080	Returns the string representation of the integer argument.
2081
2082	This function can't be used for language specific conversion.
2083
2084	@param i an integer value
2085	@param radix the radix (between 2 and 36)
2086	@return a string with the string representation of the argument.
2087	@since LibreOffice 4.1
2088	*/
2089	static OUString number( int i, sal_Int16 radix = 10 )
2090	{
2091	sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFINT32];
2092	rtl_uString* pNewData = 0;
2093	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfInt32( aBuf, i, radix ) );
2094	return OUString( pNewData, SAL_NO_ACQUIRE );
2095	}
2096	/// @overload
2097	/// @since LibreOffice 4.1
2098	static OUString number( unsigned int i, sal_Int16 radix = 10 )
2099	{
2100	return number( static_cast< unsigned long long >( i ), radix );
2101	}
2102	/// @overload
2103	/// @since LibreOffice 4.1
2104	static OUString number( long i, sal_Int16 radix = 10)
2105	{
2106	return number( static_cast< long long >( i ), radix );
2107	}
2108	/// @overload
2109	/// @since LibreOffice 4.1
2110	static OUString number( unsigned long i, sal_Int16 radix = 10 )
2111	{
2112	return number( static_cast< unsigned long long >( i ), radix );
2113	}
2114	/// @overload
2115	/// @since LibreOffice 4.1
2116	static OUString number( long long ll, sal_Int16 radix = 10 )
2117	{
2118	sal_Unicode aBuf[RTL_STR_MAX_VALUEOFINT64];
2119	rtl_uString* pNewData = 0;
2120	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfInt64( aBuf, ll, radix ) );
2121	return OUString( pNewData, SAL_NO_ACQUIRE );
2122	}
2123	/// @overload
2124	/// @since LibreOffice 4.1
2125	static OUString number( unsigned long long ll, sal_Int16 radix = 10 )
2126	{
2127	sal_Unicode aBuf[RTL_STR_MAX_VALUEOFUINT64];
2128	rtl_uString* pNewData = 0;
2129	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfUInt64( aBuf, ll, radix ) );
2130	return OUString( pNewData, SAL_NO_ACQUIRE );
2131	}
2132
2133	/**
2134	Returns the string representation of the float argument.
2135
2136	This function can't be used for language specific conversion.
2137
2138	@param f a float.
2139	@return a string with the string representation of the argument.
2140	@since LibreOffice 4.1
2141	*/
2142	static OUString number( float f )
2143	{
2144	sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFFLOAT];
2145	rtl_uString* pNewData = 0;
2146	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfFloat( aBuf, f ) );
2147	return OUString( pNewData, SAL_NO_ACQUIRE );
2148	}
2149
2150	/**
2151	Returns the string representation of the double argument.
2152
2153	This function can't be used for language specific conversion.
2154
2155	@param d a double.
2156	@return a string with the string representation of the argument.
2157	@since LibreOffice 4.1
2158	*/
2159	static OUString number( double d )
2160	{
2161	sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFDOUBLE];
2162	rtl_uString* pNewData = 0;
2163	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfDouble( aBuf, d ) );
2164	return OUString( pNewData, SAL_NO_ACQUIRE );
2165	}
2166
2167	/**
2168	Returns the string representation of the sal_Bool argument.
2169
2170	If the sal_Bool is true, the string "true" is returned.
2171	If the sal_Bool is false, the string "false" is returned.
2172	This function can't be used for language specific conversion.
2173
2174	@param b a sal_Bool.
2175	@return a string with the string representation of the argument.
2176	@deprecated use boolean()
2177	*/
2178	SAL_DEPRECATED("use boolean()") static OUString valueOf( sal_Bool b ) SAL_THROW(())
2179	{
2180	return boolean(b);
2181	}
2182
2183	/**
2184	Returns the string representation of the boolean argument.
2185
2186	If the argument is true, the string "true" is returned.
2187	If the argument is false, the string "false" is returned.
2188	This function can't be used for language specific conversion.
2189
2190	@param b a bool.
2191	@return a string with the string representation of the argument.
2192	@since LibreOffice 4.1
2193	*/
2194	static OUString boolean( bool b ) SAL_THROW(())
2195	{
2196	sal_Unicode aBuf[RTL_USTR_MAX_VALUEOFBOOLEAN];
2197	rtl_uString* pNewData = 0;
2198	rtl_uString_newFromStr_WithLength( &pNewData, aBuf, rtl_ustr_valueOfBoolean( aBuf, b ) );
2199	return OUString( pNewData, SAL_NO_ACQUIRE );
2200	}
2201
2202	/**
2203	Returns the string representation of the char argument.
2204
2205	@param c a character.
2206	@return a string with the string representation of the argument.
2207	@deprecated use operator, function or constructor taking char or sal_Unicode argument
2208	*/
2209	SAL_DEPRECATED("convert to OUString or use directly") static OUString valueOf( sal_Unicode c ) SAL_THROW(())
2210	{
2211	return OUString( &c, 1 );
2212	}
2213
2214	/**
2215	Returns the string representation of the int argument.
2216
2217	This function can't be used for language specific conversion.
2218
2219	@param i a int32.
2220	@param radix the radix (between 2 and 36)
2221	@return a string with the string representation of the argument.
2222	@deprecated use number()
2223	*/
2224	SAL_DEPRECATED("use number()") static OUString valueOf( sal_Int32 i, sal_Int16 radix = 10 ) SAL_THROW(())
2225	{
2226	return number( i, radix );
2227	}
2228
2229	/**
2230	Returns the string representation of the long argument.
2231
2232	This function can't be used for language specific conversion.
2233
2234	@param ll a int64.
2235	@param radix the radix (between 2 and 36)
2236	@return a string with the string representation of the argument.
2237	@deprecated use number()
2238	*/
2239	SAL_DEPRECATED("use number()") static OUString valueOf( sal_Int64 ll, sal_Int16 radix = 10 ) SAL_THROW(())
2240	{
2241	return number( ll, radix );
2242	}
2243
2244	/**
2245	Returns the string representation of the float argument.
2246
2247	This function can't be used for language specific conversion.
2248
2249	@param f a float.
2250	@return a string with the string representation of the argument.
2251	@deprecated use number()
2252	*/
2253	SAL_DEPRECATED("use number()") static OUString valueOf( float f ) SAL_THROW(())
2254	{
2255	return number(f);
2256	}
2257
2258	/**
2259	Returns the string representation of the double argument.
2260
2261	This function can't be used for language specific conversion.
2262
2263	@param d a double.
2264	@return a string with the string representation of the argument.
2265	@deprecated use number()
2266	*/
2267	SAL_DEPRECATED("use number()") static OUString valueOf( double d ) SAL_THROW(())
2268	{
2269	return number(d);
2270	}
2271
2272	/**
2273	Returns a OUString copied without conversion from an ASCII
2274	character string.
2275
2276	Since this method is optimized for performance, the ASCII character
2277	values are not converted in any way. The caller has to make sure that
2278	all ASCII characters are in the allowed range between 0 and
2279	127. The ASCII string must be NULL-terminated.
2280
2281	Note that for string literals it is simpler and more efficient
2282	to directly use the OUString constructor.
2283
2284	@param value the 8-Bit ASCII character string
2285	@return a string with the string representation of the argument.
2286	*/
2287	static OUString createFromAscii( const sal_Char * value ) SAL_THROW(())
2288	{
2289	rtl_uString* pNew = 0;
2290	rtl_uString_newFromAscii( &pNew, value );
2291	return OUString( pNew, SAL_NO_ACQUIRE );
2292	}
2293	};
2294
2295	/* ======================================================================= */
2296
2297	#ifdef RTL_FAST_STRING
2298	/**
2299	A simple wrapper around string literal. It is usually not necessary to use, can
2300	be mostly used to force OUString operator+ working with operands that otherwise would
2301	not trigger it.
2302
2303	This class is not part of public API and is meant to be used only in LibreOffice code.
2304	@since LibreOffice 4.0
2305	*/
2306	struct SAL_WARN_UNUSED OUStringLiteral
2307	{
2308	template< int N >
2309	OUStringLiteral( const char (&str)[ N ] ) : size( N - 1 ), data( str ) { assert( strlen( str ) == N - 1 ); }
2310	int size;
2311	const char* data;
2312	};
2313
2314	/**
2315	@internal
2316	*/
2317	template<>
2318	struct ToStringHelper< OUString >
2319	{
2320	static int length( const OUString& s ) { return s.getLength(); }
2321	static sal_Unicode* addData( sal_Unicode* buffer, const OUString& s ) { return addDataHelper( buffer, s.getStr(), s.getLength()); }
2322	static const bool allowOStringConcat = false;
2323	static const bool allowOUStringConcat = true;
2324	};
2325
2326	/**
2327	@internal
2328	*/
2329	template<>
2330	struct ToStringHelper< OUStringLiteral >
2331	{
2332	static int length( const OUStringLiteral& str ) { return str.size; }
2333	static sal_Unicode* addData( sal_Unicode* buffer, const OUStringLiteral& str ) { return addDataLiteral( buffer, str.data, str.size ); }
2334	static const bool allowOStringConcat = false;
2335	static const bool allowOUStringConcat = true;
2336	};
2337
2338	/**
2339	@internal
2340	*/
2341	template< typename charT, typename traits, typename T1, typename T2 >
2342	inline std::basic_ostream<charT, traits> & operator <<(
2343	std::basic_ostream<charT, traits> & stream, const OUStringConcat< T1, T2 >& concat)
2344	{
2345	return stream << OUString( concat );
2346	}
2347	#else
2348	// non-RTL_FAST_STRING needs this to compile
2349	/// @cond INTERNAL
2350	typedef OUString OUStringLiteral;
2351	/// @endcond
2352	#endif
2353
2354	/** A helper to use OUStrings with hash maps.
2355
2356	Instances of this class are unary function objects that can be used as
2357	hash function arguments to boost::unordered_map and similar constructs.
2358	*/
2359	struct OUStringHash
2360	{
2361	/** Compute a hash code for a string.
2362
2363	@param rString
2364	a string.
2365
2366	@return
2367	a hash code for the string. This hash code should not be stored
2368	persistently, as its computation may change in later revisions.
2369	*/
2370	size_t operator()(const OUString& rString) const
2371	{ return (size_t)rString.hashCode(); }
2372	};
2373
2374	/* ======================================================================= */
2375
2376	/** Convert an OString to an OUString, using a specific text encoding.
2377
2378	The lengths of the two strings may differ (e.g., for double-byte
2379	encodings, UTF-7, UTF-8).
2380
2381	@param rStr
2382	an OString to convert.
2383
2384	@param encoding
2385	the text encoding to use for conversion.
2386
2387	@param convertFlags
2388	flags which control the conversion. Either use
2389	OSTRING_TO_OUSTRING_CVTFLAGS, or see
2390	<http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
2391	details.
2392	*/
2393	inline OUString OStringToOUString( const OString & rStr,
2394	rtl_TextEncoding encoding,
2395	sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS )
2396	{
2397	return OUString( rStr.getStr(), rStr.getLength(), encoding, convertFlags );
2398	}
2399
2400	/** Convert an OUString to an OString, using a specific text encoding.
2401
2402	The lengths of the two strings may differ (e.g., for double-byte
2403	encodings, UTF-7, UTF-8).
2404
2405	@param rUnicode
2406	an OUString to convert.
2407
2408	@param encoding
2409	the text encoding to use for conversion.
2410
2411	@param convertFlags
2412	flags which control the conversion. Either use
2413	OUSTRING_TO_OSTRING_CVTFLAGS, or see
2414	<http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
2415	details.
2416	*/
2417	inline OString OUStringToOString( const OUString & rUnicode,
2418	rtl_TextEncoding encoding,
2419	sal_uInt32 convertFlags = OUSTRING_TO_OSTRING_CVTFLAGS )
2420	{
2421	return OString( rUnicode.getStr(), rUnicode.getLength(), encoding, convertFlags );
2422	}
2423
2424	/* ======================================================================= */
2425
2426	/**
2427	Support for rtl::OUString in std::ostream (and thus in
2428	CPPUNIT_ASSERT or SAL_INFO macros, for example).
2429
2430	The rtl::OUString is converted to UTF-8.
2431
2432	@since LibreOffice 3.5.
2433	*/
2434	template< typename charT, typename traits >
2435	inline std::basic_ostream<charT, traits> & operator <<(
2436	std::basic_ostream<charT, traits> & stream, OUString const & string)
2437	{
2438	return stream <<
2439	OUStringToOString(string, RTL_TEXTENCODING_UTF8).getStr();
2440	// best effort; potentially loses data due to conversion failures
2441	// (stray surrogate halves) and embedded null characters
2442	}
2443
2444	} // namespace
2445
2446	#ifdef RTL_STRING_UNITTEST
2447	namespace rtl
2448	{
2449	typedef rtlunittest::OUString OUString;
2450	}
2451	#endif
2452
2453	// RTL_USING is defined by gbuild for all modules except those with stable public API
2454	// (as listed in ure/source/README). It allows to use classes like OUString without
2455	// having to explicitly refer to the rtl namespace, which is kind of superfluous
2456	// given that OUString itself is namespaced by its OU prefix.
2457	#ifdef RTL_USING
2458	using ::rtl::OUString;
2459	using ::rtl::OUStringHash;
2460	using ::rtl::OStringToOUString;
2461	using ::rtl::OUStringToOString;
2462	using ::rtl::OUStringLiteral;
2463	#endif
2464
2465	#endif /* _RTL_USTRING_HXX */
2466
2467	/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
2468

---

Generated while processing libreoffice/UnoControls/source/base/basecontainercontrol.cxx
Generated on 2014-Feb-12 from project libreoffice revision sdremote-2.0.0-474-g0c0ed05
Powered by Code Browser 1.5