LibreOffice
LibreOffice 4.1 SDK C/C++ API Reference
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
rtl::OUString Class Reference

This String class provides base functionality for C++ like Unicode character array handling. More...

#include <ustring.hxx>

Public Member Functions

 OUString () throw ()
 New string containing no characters. More...
 
 OUString (const OUString &str) throw ()
 New string from OUString. More...
 
 OUString (rtl_uString *str) throw ()
 New string from OUString data. More...
 
 OUString (rtl_uString *str, __sal_NoAcquire) throw ()
 New OUString from OUString data without acquiring it. More...
 
 OUString (sal_Unicode value) throw ()
 New string from a single Unicode character. More...
 
 OUString (const sal_Unicode *value) throw ()
 New string from a Unicode character buffer array. More...
 
 OUString (const sal_Unicode *value, sal_Int32 length) throw ()
 New string from a Unicode character buffer array. More...
 
template<typename T >
 assert (strlen(literal)==internal::ConstCharArrayDetector< T >::size-1)
 New string from an 8-Bit string literal that is expected to contain only characters in the ASCII set (i.e. More...
 
 if (internal::ConstCharArrayDetector< T, void >::size-1==0) rtl_uString_new(&pData)
 
 OUString (const sal_Char *value, sal_Int32 length, rtl_TextEncoding encoding, sal_uInt32 convertFlags=OSTRING_TO_OUSTRING_CVTFLAGS)
 New string from an 8-Bit character buffer array. More...
 
 OUString (sal_uInt32 const *codePoints, sal_Int32 codePointCount)
 Create a new string from an array of Unicode code points. More...
 
 ~OUString () throw ()
 Release the string data. More...
 
OUStringoperator= (const OUString &str) throw ()
 Assign a new string. More...
 
template<typename T >
internal::ConstCharArrayDetector
< T, OUString & >::Type 
operator= (T &literal)
 Assign a new string from an 8-Bit string literal that is expected to contain only characters in the ASCII set (i.e. More...
 
OUStringoperator+= (const OUString &str) throw ()
 Append a string to this string. More...
 
sal_Int32 getLength () const throw ()
 Returns the length of this string. More...
 
bool isEmpty () const throw ()
 Checks if a string is empty. More...
 
const sal_UnicodegetStr () const throw ()
 Returns a pointer to the Unicode character buffer for this string. More...
 
sal_Unicode operator[] (sal_Int32 index) const
 Access to individual characters. More...
 
sal_Int32 compareTo (const OUString &str) const throw ()
 Compares two strings. More...
 
sal_Int32 compareTo (const OUString &str, sal_Int32 maxLength) const throw ()
 Compares two strings with a maximum count of characters. More...
 
sal_Int32 reverseCompareTo (const OUString &str) const throw ()
 Compares two strings in reverse order. More...
 
template<typename T >
internal::ConstCharArrayDetector
< T, sal_Int32 >::Type 
reverseCompareTo (T &literal) const throw ()
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument. More...
 
sal_Bool equals (const OUString &str) const throw ()
 Perform a comparison of two strings. More...
 
sal_Bool equalsIgnoreAsciiCase (const OUString &str) const throw ()
 Perform a ASCII lowercase comparison of two strings. More...
 
sal_Int32 compareToIgnoreAsciiCase (const OUString &str) const throw ()
 Perform a ASCII lowercase comparison of two strings. More...
 
template<typename T >
internal::ConstCharArrayDetector
< T, bool >::Type 
equalsIgnoreAsciiCase (T &literal) const throw ()
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument. More...
 
sal_Bool match (const OUString &str, sal_Int32 fromIndex=0) const throw ()
 Match against a substring appearing in this string. More...
 
template<typename T >
internal::ConstCharArrayDetector
< T, bool >::Type 
match (T &literal, sal_Int32 fromIndex=0) const throw ()
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument. More...
 
sal_Bool matchIgnoreAsciiCase (const OUString &str, sal_Int32 fromIndex=0) const throw ()
 Match against a substring appearing in this string, ignoring the case of ASCII letters. More...
 
template<typename T >
internal::ConstCharArrayDetector
< T, bool >::Type 
matchIgnoreAsciiCase (T &literal, sal_Int32 fromIndex=0) const throw ()
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument. More...
 
sal_Int32 compareToAscii (const sal_Char *asciiStr) const throw ()
 Compares two strings. More...
 

Static Public Member Functions

static OUString const & unacquired (rtl_uString *const *ppHandle)
 Provides an OUString const & passing a storage pointer of an rtl_uString * handle. More...
 

Public Attributes

 pData = 0
 
else rtl_uString_newFromLiteralpData
 

Detailed Description

This String class provides base functionality for C++ like Unicode character array handling.

The advantage of this class is that it handles all the memory management for you - and it does it more efficiently. If you assign a string to another string, the data of both strings are shared (without any copy operation or memory allocation) as long as you do not change the string. This class also stores the length of the string, so that many operations are faster than the C-str-functions.

This class provides only readonly string handling. So you could create a string and you could only query the content from this string. It provides also functionality to change the string, but this results in every case in a new string instance (in the most cases with a memory allocation). You don't have functionality to change the content of the string. If you want to change the string content, then you should use the OStringBuffer class, which provides these functionalities and avoids too much memory allocation.

The design of this class is similar to the string classes in Java so less people should have understanding problems when they use this class.

Constructor & Destructor Documentation

rtl::OUString::OUString ( )
throw (
)
inline

New string containing no characters.

rtl::OUString::OUString ( const OUString str)
throw (
)
inline

New string from OUString.

Parameters
stra OUString.
rtl::OUString::OUString ( rtl_uString *  str)
throw (
)
inline

New string from OUString data.

Parameters
stra OUString data.
rtl::OUString::OUString ( rtl_uString *  str,
__sal_NoAcquire   
)
throw (
)
inline

New OUString from OUString data without acquiring it.

Takeover of ownership.

The SAL_NO_ACQUIRE dummy parameter is only there to distinguish this from other constructors.

Parameters
strOUString data
rtl::OUString::OUString ( sal_Unicode  value)
throw (
)
inlineexplicit

New string from a single Unicode character.

Parameters
valuea Unicode character.
rtl::OUString::OUString ( const sal_Unicode value)
throw (
)
inline

New string from a Unicode character buffer array.

Parameters
valuea NULL-terminated Unicode character array.
rtl::OUString::OUString ( const sal_Unicode value,
sal_Int32  length 
)
throw (
)
inline

New string from a Unicode character buffer array.

Parameters
valuea Unicode character array.
lengththe number of character which should be copied. The character array length must be greater than or equal to this value.
rtl::OUString::OUString ( const sal_Char value,
sal_Int32  length,
rtl_TextEncoding  encoding,
sal_uInt32  convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS 
)
inline

New string from an 8-Bit character buffer array.

Parameters
valueAn 8-Bit character array.
lengthThe number of character which should be converted. The 8-Bit character array length must be greater than or equal to this value.
encodingThe text encoding from which the 8-Bit character sequence should be converted.
convertFlagsFlags which control the conversion. see RTL_TEXTTOUNICODE_FLAGS_...
Exceptions
std::bad_allocis thrown if an out-of-memory condition occurs
rtl::OUString::OUString ( sal_uInt32 const *  codePoints,
sal_Int32  codePointCount 
)
inlineexplicit

Create a new string from an array of Unicode code points.

Parameters
codePointsan array of at least codePointCount code points, which each must be in the range from 0 to 0x10FFFF, inclusive. May be null if codePointCount is zero.
codePointCountthe non-negative number of code points.
Exceptions
std::bad_allocis thrown if either an out-of-memory condition occurs or the resulting number of UTF-16 code units would have been larger than SAL_MAX_INT32.
Since
UDK 3.2.7
rtl::OUString::~OUString ( )
throw (
)
inline

Release the string data.

Member Function Documentation

template<typename T >
rtl::OUString::assert ( strlen(literal)  = =internal::ConstCharArrayDetector< T >::size-1)

New string from an 8-Bit string literal that is expected to contain only characters in the ASCII set (i.e.

first 128 characters). This constructor allows an efficient and convenient way to create OUString instances from ASCII literals. When creating strings from data that is not pure ASCII, it needs to be converted to OUString by explicitly providing the encoding to use for the conversion.

If there are any embedded \0's in the string literal, the result is undefined. Use the overload that explicitly accepts length.

Parameters
literalthe 8-bit ASCII string literal
Since
LibreOffice 3.6
sal_Int32 rtl::OUString::compareTo ( const OUString str) const
throw (
)
inline

Compares two strings.

The comparison is based on the numeric value of each character in the strings and return a value indicating their relationship. This function can't be used for language specific sorting.

Parameters
strthe object to be compared.
Returns
0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument
sal_Int32 rtl::OUString::compareTo ( const OUString str,
sal_Int32  maxLength 
) const
throw (
)
inline

Compares two strings with a maximum count of characters.

The comparison is based on the numeric value of each character in the strings and return a value indicating their relationship. This function can't be used for language specific sorting.

Parameters
strthe object to be compared.
maxLengththe maximum count of characters to be compared.
Returns
0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument
Since
UDK 3.2.7
sal_Int32 rtl::OUString::compareToAscii ( const sal_Char asciiStr) const
throw (
)
inline

Compares two strings.

The comparison is based on the numeric value of each character in the strings and return a value indicating their relationship. Since this method is optimized for performance, the ASCII character values are not converted in any way. The caller has to make sure that all ASCII characters are in the allowed range between 0 and

  1. The ASCII string must be NULL-terminated. This function can't be used for language specific sorting.
Parameters
asciiStrthe 8-Bit ASCII character string to be compared.
Returns
0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument
sal_Int32 rtl::OUString::compareToIgnoreAsciiCase ( const OUString str) const
throw (
)
inline

Perform a ASCII lowercase comparison of two strings.

Compare the two strings with uppercase ASCII character values between 65 and 90 (ASCII A-Z) interpreted as values between 97 and 122 (ASCII a-z). This function can't be used for language specific comparison.

Parameters
strthe object to be compared.
Returns
0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument
Since
LibreOffice 4.0
sal_Bool rtl::OUString::equals ( const OUString str) const
throw (
)
inline

Perform a comparison of two strings.

The result is true if and only if second string represents the same sequence of characters as the first string. This function can't be used for language specific comparison.

Parameters
strthe object to be compared.
Returns
sal_True if the strings are equal; sal_False, otherwise.
sal_Bool rtl::OUString::equalsIgnoreAsciiCase ( const OUString str) const
throw (
)
inline

Perform a ASCII lowercase comparison of two strings.

The result is true if and only if second string represents the same sequence of characters as the first string, ignoring the case. Character values between 65 and 90 (ASCII A-Z) are interpreted as values between 97 and 122 (ASCII a-z). This function can't be used for language specific comparison.

Parameters
strthe object to be compared.
Returns
sal_True if the strings are equal; sal_False, otherwise.
template<typename T >
internal::ConstCharArrayDetector< T, bool >::Type rtl::OUString::equalsIgnoreAsciiCase ( T &  literal) const
throw (
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument.

Since
LibreOffice 3.6
sal_Int32 rtl::OUString::getLength ( ) const
throw (
)
inline

Returns the length of this string.

The length is equal to the number of Unicode characters in this string.

Returns
the length of the sequence of characters represented by this object.
const sal_Unicode* rtl::OUString::getStr ( ) const
throw (
)
inline

Returns a pointer to the Unicode character buffer for this string.

It isn't necessarily NULL terminated.

Returns
a pointer to the Unicode characters buffer for this object.
rtl::OUString::if ( internal::ConstCharArrayDetector< T, void >::size-  1 = =0)
bool rtl::OUString::isEmpty ( ) const
throw (
)
inline

Checks if a string is empty.

Returns
true if the string is empty; false, otherwise.
Since
LibreOffice 3.4
sal_Bool rtl::OUString::match ( const OUString str,
sal_Int32  fromIndex = 0 
) const
throw (
)
inline

Match against a substring appearing in this string.

The result is true if and only if the second string appears as a substring of this string, at the given position. This function can't be used for language specific comparison.

Parameters
strthe object (substring) to be compared.
fromIndexthe index to start the comparion from. The index must be greater than or equal to 0 and less or equal as the string length.
Returns
sal_True if str match with the characters in the string at the given position; sal_False, otherwise.
template<typename T >
internal::ConstCharArrayDetector< T, bool >::Type rtl::OUString::match ( T &  literal,
sal_Int32  fromIndex = 0 
) const
throw (
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument.

Since
LibreOffice 3.6
sal_Bool rtl::OUString::matchIgnoreAsciiCase ( const OUString str,
sal_Int32  fromIndex = 0 
) const
throw (
)
inline

Match against a substring appearing in this string, ignoring the case of ASCII letters.

The result is true if and only if the second string appears as a substring of this string, at the given position. Character values between 65 and 90 (ASCII A-Z) are interpreted as values between 97 and 122 (ASCII a-z). This function can't be used for language specific comparison.

Parameters
strthe object (substring) to be compared.
fromIndexthe index to start the comparion from. The index must be greater than or equal to 0 and less than or equal to the string length.
Returns
sal_True if str match with the characters in the string at the given position; sal_False, otherwise.
template<typename T >
internal::ConstCharArrayDetector< T, bool >::Type rtl::OUString::matchIgnoreAsciiCase ( T &  literal,
sal_Int32  fromIndex = 0 
) const
throw (
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument.

Since
LibreOffice 3.6
OUString& rtl::OUString::operator+= ( const OUString str)
throw (
)
inline

Append a string to this string.

Parameters
stra OUString.
OUString& rtl::OUString::operator= ( const OUString str)
throw (
)
inline

Assign a new string.

Parameters
stra OUString.
template<typename T >
internal::ConstCharArrayDetector< T, OUString& >::Type rtl::OUString::operator= ( T &  literal)
inline

Assign a new string from an 8-Bit string literal that is expected to contain only characters in the ASCII set (i.e.

first 128 characters). This operator allows an efficient and convenient way to assign OUString instances from ASCII literals. When assigning strings from data that is not pure ASCII, it needs to be converted to OUString by explicitly providing the encoding to use for the conversion.

Parameters
literalthe 8-bit ASCII string literal
Since
LibreOffice 3.6
sal_Unicode rtl::OUString::operator[] ( sal_Int32  index) const
inline

Access to individual characters.

Parameters
indexmust be non-negative and less than length.
Returns
the character at the given index.
Since
LibreOffice 3.5
sal_Int32 rtl::OUString::reverseCompareTo ( const OUString str) const
throw (
)
inline

Compares two strings in reverse order.

The comparison is based on the numeric value of each character in the strings and return a value indicating their relationship. This function can't be used for language specific sorting.

Parameters
strthe object to be compared.
Returns
0 - if both strings are equal < 0 - if this string is less than the string argument > 0 - if this string is greater than the string argument
template<typename T >
internal::ConstCharArrayDetector< T, sal_Int32 >::Type rtl::OUString::reverseCompareTo ( T &  literal) const
throw (
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function accepts an ASCII string literal as its argument.

Since
LibreOffice 4.1
static OUString const& rtl::OUString::unacquired ( rtl_uString *const *  ppHandle)
inlinestatic

Provides an OUString const & passing a storage pointer of an rtl_uString * handle.

It is more convenient to use C++ OUString member functions when dealing with rtl_uString * handles. Using this function avoids unnecessary acquire()/release() calls for a temporary OUString object.

Parameters
ppHandlepointer to storage
Returns
OUString const & based on given storage

Member Data Documentation

rtl::OUString::pData = 0
else rtl_uString_newFromLiteral & rtl::OUString::pData

The documentation for this class was generated from the following file: