LibreOffice LibreOffice 4.1 SDK C/C++ API Reference

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Member Functions | Static Public Member Functions | 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 >
| OUString (T &literal, typename internal::ConstCharArrayDetector< T, internal::Dummy >::Type=internal::Dummy())
| New string from an 8-Bit string literal that is expected to contain only characters in the ASCII set (i.e. More...
| 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...
OUString & | operator= (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...
OUString & | operator+= (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_Unicode * | getStr () 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...

## 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

  str | a OUString.

rtl::OUString::OUString | ( | rtl_uString * | str | ) |
throw | ( |
| ) |  |
| inline

New string from OUString data.

Parameters

  str | a 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

  str | OUString data

rtl::OUString::OUString | ( | sal_Unicode | value | ) |
throw | ( |
| ) |  |
| inline explicit

New string from a single Unicode character.

Parameters

  value | a Unicode character.

rtl::OUString::OUString | ( | const sal_Unicode * | value | ) |
throw | ( |
| ) |  |
| inline

New string from a Unicode character buffer array.

Parameters

  value | a 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

  value | a Unicode character array.
  length | the number of character which should be copied. The character array length must be greater than or equal to this value.

template<typename T >

rtl::OUString::OUString | ( | T & | literal,
|  | typename internal::ConstCharArrayDetector< T, internal::Dummy >::Type | = `internal::Dummy()`
| ) |  |
| inline

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

  literal | the 8-bit ASCII string literal

Since
  LibreOffice 3.6

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

  value | An 8-Bit character array.
  length | The number of character which should be converted. The 8-Bit character array length must be greater than or equal to this value.
  encoding | The text encoding from which the 8-Bit character sequence should be converted.
  convertFlags | Flags which control the conversion. see RTL_TEXTTOUNICODE_FLAGS_...

Exceptions

  std::bad_alloc | is thrown if an out-of-memory condition occurs

rtl::OUString::OUString | ( | sal_uInt32 const * | codePoints,
|  | sal_Int32 | codePointCount
| ) |  |
| inline explicit

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

Parameters

  codePoints | an 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.
  codePointCount | the non-negative number of code points.

Exceptions

  std::bad_alloc | is 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

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

  str | the 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

  str | the object to be compared.
  maxLength | the 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

  asciiStr | the 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

  str | the 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

  str | the 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

  str | the 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.

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

  str | the object (substring) to be compared.
  fromIndex | the 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

  str | the object (substring) to be compared.
  fromIndex | the 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

  str | a OUString.

OUString& rtl::OUString::operator= | ( | const OUString & | str | ) |
throw | ( |
| ) |  |
| inline

Assign a new string.

Parameters

  str | a 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

  literal | the 8-bit ASCII string literal

Since
  LibreOffice 3.6

sal_Unicode rtl::OUString::operator[] | ( | sal_Int32 | index | ) | const
| inline

Access to individual characters.

Parameters

  index | must 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

  str | the 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 | ) |
| inline static

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

  ppHandle | pointer to storage

Returns
  OUString const & based on given storage

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

- rtl/ustring.hxx