The Free and Open Productivity Suite
Follow us on Twitter: @ApacheOO

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


Global Functions in Global Namespace C++
in Sourcefile string.h


rtl_convertUStringToString
extern "C"
sal_Bool rtl_convertUStringToString(
rtl_String * * pTarget,
const sal_Unicode * pSource,
sal_Int32 nLength,
rtl_TextEncoding nEncoding,
sal_uInt32 nFlags );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Converts a Unicode string to a byte string, signalling failure.
Parameters
pTarget
  An out parameter receiving the converted string.  Must not be null itself, and
  must contain either null or a pointer to a valid rtl_String; the contents are
  not modified if conversion fails (rtl_convertUStringToString returns false).

  
pSource
  The Unicode string.  May only be null if nLength is zero.

  
nLength
  The length of the Unicode string.  Must be non-negative.

  
nEncoding
  The text encoding to convert into.  Must be an octet encoding (i.e.,
  rtl_isOctetTextEncoding(nEncoding) must return true).

  
nFlags
  A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
  (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
  included, it is implicitly assumed.  Typical uses are either
  RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
  RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
  converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
  best efforts conversion).

  
Return
True if the conversion succeeded, false otherwise.

rtl_str_compare
extern "C"
sal_Int32 rtl_str_compare(
const sal_Char * first,
const sal_Char * second );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. This function cannot be used for language-specific sorting. Both strings must be null-terminated.
Parameters
first
    the first null-terminated string to be compared.

    
second
    the second null-terminated string which is compared with the first one.

    
Return
0 if both strings are equal, a value less than 0 if the first string is less than the second string, and a value greater than 0 if the first string is greater than the second string.

rtl_str_compareIgnoreAsciiCase
extern "C"
sal_Int32 rtl_str_compareIgnoreAsciiCase(
const sal_Char * first,
const sal_Char * second );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings, ignoring the case of ASCII characters.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. Character values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 and 122 (ASCII a--z). This function cannot be used for language-specific sorting. Both strings must be null-terminated.
Parameters
first
    the first null-terminated string to be compared.

    
second
    the second null-terminated string which is compared with the first one.

    
Return
0 if both strings are equal, a value less than 0 if the first string is less than the second string, and a value greater than 0 if the first string is greater than the second string.

rtl_str_compareIgnoreAsciiCase_WithLength
extern "C"
sal_Int32 rtl_str_compareIgnoreAsciiCase_WithLength(
const sal_Char * first,
sal_Int32 firstLen,
const sal_Char * second,
sal_Int32 secondLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings, ignoring the case of ASCII characters.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. Character values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 and 122 (ASCII a--z). This function cannot be used for language-specific sorting.
Parameters
first
    the first string to be compared.  Need not be null-terminated, but must be
    at least as long as the specified firstLen.

    
firstLen
    the length of the first string.

    
second
    the second string which is compared with the first one.  Need not be
    null-terminated, but must be at least as long as the specified secondLen.

    
secondLen
    the length of the second string.

    
Return
0 if both strings are equal, a value less than 0 if the first string is less than the second string, and a value greater than 0 if the first string is greater than the second string.

rtl_str_compare_WithLength
extern "C"
sal_Int32 rtl_str_compare_WithLength(
const sal_Char * first,
sal_Int32 firstLen,
const sal_Char * second,
sal_Int32 secondLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. This function cannot be used for language-specific sorting.
Parameters
first
    the first string to be compared.  Need not be null-terminated, but must be
    at least as long as the specified firstLen.

    
firstLen
    the length of the first string.

    
second
    the second string which is compared with the first one.  Need not be
    null-terminated, but must be at least as long as the specified secondLen.

    
secondLen
    the length of the second string.

    
Return
0 if both strings are equal, a value less than 0 if the first string is less than the second string, and a value greater than 0 if the first string is greater than the second string.

rtl_str_getLength
extern "C"
sal_Int32 rtl_str_getLength(
const sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Return the length of a string.
Description
The length is equal to the number of 8-bit characters in the string, without the terminating NUL character.
Parameters
str
    a null-terminated string.

    
Return
the length of the sequence of characters represented by this string, excluding the terminating NUL character.

rtl_str_hashCode
extern "C"
sal_Int32 rtl_str_hashCode(
const sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Return a hash code for a string.
Description
It is not allowed to store the hash code persistently, because later versions could return other hash codes. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
Return
a hash code for the given string.

rtl_str_hashCode_WithLength
extern "C"
sal_Int32 rtl_str_hashCode_WithLength(
const sal_Char * str,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Return a hash code for a string.
Description
It is not allowed to store the hash code persistently, because later versions could return other hash codes.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
Return
a hash code for the given string.

rtl_str_indexOfChar
extern "C"
sal_Int32 rtl_str_indexOfChar(
const sal_Char * str,
sal_Char ch );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the first occurrence of a character within a string.
Description
The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
ch
    the character to be searched for.

    
Return
the index (starting at 0) of the first occurrence of the character in the string, or -1 if the character does not occur.

rtl_str_indexOfChar_WithLength
extern "C"
sal_Int32 rtl_str_indexOfChar_WithLength(
const sal_Char * str,
sal_Int32 len,
sal_Char ch );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the first occurrence of a character within a string.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
ch
    the character to be searched for.

    
Return
the index (starting at 0) of the first occurrence of the character in the string, or -1 if the character does not occur.

rtl_str_indexOfStr
extern "C"
sal_Int32 rtl_str_indexOfStr(
const sal_Char * str,
const sal_Char * subStr );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the first occurrence of a substring within a string.
Description
If subStr is empty, or both str and subStr are empty, -1 is returned. Both strings must be null-terminated.
Parameters
str
    a null-terminated string.

    
subStr
    the null-terminated substring to be searched for.

    
Return
the index (starting at 0) of the first character of the first occurrence of the substring within the string, or -1 if the substring does not occur.

rtl_str_indexOfStr_WithLength
extern "C"
sal_Int32 rtl_str_indexOfStr_WithLength(
const sal_Char * str,
sal_Int32 len,
const sal_Char * subStr,
sal_Int32 subLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the first occurrence of a substring within a string.
Description
If subStr is empty, or both str and subStr are empty, -1 is returned.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
subStr
    the substring to be searched for.  Need not be null-terminated, but must
    be at least as long as the specified subLen.

    
subLen
    the length of the substring.

    
Return
the index (starting at 0) of the first character of the first occurrence of the substring within the string, or -1 if the substring does not occur.

rtl_str_lastIndexOfChar
extern "C"
sal_Int32 rtl_str_lastIndexOfChar(
const sal_Char * str,
sal_Char ch );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the last occurrence of a character within a string.
Description
The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
ch
    the character to be searched for.

    
Return
the index (starting at 0) of the last occurrence of the character in the string, or -1 if the character does not occur. The returned value is always smaller than the string length.

rtl_str_lastIndexOfChar_WithLength
extern "C"
sal_Int32 rtl_str_lastIndexOfChar_WithLength(
const sal_Char * str,
sal_Int32 len,
sal_Char ch );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the last occurrence of a character within a string.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
ch
    the character to be searched for.

    
Return
the index (starting at 0) of the last occurrence of the character in the string, or -1 if the character does not occur. The returned value is always smaller than the string length.

rtl_str_lastIndexOfStr
extern "C"
sal_Int32 rtl_str_lastIndexOfStr(
const sal_Char * str,
const sal_Char * subStr );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the last occurrence of a substring within a string.
Description
If subStr is empty, or both str and subStr are empty, -1 is returned. Both strings must be null-terminated.
Parameters
str
    a null-terminated string.

    
subStr
    the null-terminated substring to be searched for.

    
Return
the index (starting at 0) of the first character of the last occurrence of the substring within the string, or -1 if the substring does not occur.

rtl_str_lastIndexOfStr_WithLength
extern "C"
sal_Int32 rtl_str_lastIndexOfStr_WithLength(
const sal_Char * str,
sal_Int32 len,
const sal_Char * subStr,
sal_Int32 subLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Search for the last occurrence of a substring within a string.
Description
If subStr is empty, or both str and subStr are empty, -1 is returned.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
subStr
    the substring to be searched for.  Need not be null-terminated, but must
    be at least as long as the specified subLen.

    
subLen
    the length of the substring.

    
Return
the index (starting at 0) of the first character of the first occurrence of the substring within the string, or -1 if the substring does not occur.

rtl_str_replaceChar
extern "C"
void rtl_str_replaceChar(
sal_Char * str,
sal_Char oldChar,
sal_Char newChar );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Replace all occurrences of a single character within a string.
Description
If oldChar does not occur within str, then the string is not modified. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
oldChar
    the old character.

    
newChar
    the new character.
 

rtl_str_replaceChar_WithLength
extern "C"
void rtl_str_replaceChar_WithLength(
sal_Char * str,
sal_Int32 len,
sal_Char oldChar,
sal_Char newChar );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Replace all occurrences of a single character within a string.
Description
If oldChar does not occur within str, then the string is not modified.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.

    
oldChar
    the old character.

    
newChar
    the new character.
 

rtl_str_reverseCompare_WithLength
extern "C"
sal_Int32 rtl_str_reverseCompare_WithLength(
const sal_Char * first,
sal_Int32 firstLen,
const sal_Char * second,
sal_Int32 secondLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings from back to front.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. This function cannot be used for language-specific sorting.
Parameters
first
    the first string to be compared.  Need not be null-terminated, but must be
    at least as long as the specified firstLen.

    
firstLen
    the length of the first string.

    
second
    the second string which is compared with the first one.  Need not be
    null-terminated, but must be at least as long as the specified secondLen.

    
secondLen
    the length of the second string.

    
Return
0 if both strings are equal, a value less than 0 if the first string compares less than the second string, and a value greater than 0 if the first string compares greater than the second string.

rtl_str_shortenedCompareIgnoreAsciiCase_WithLength
extern "C"
sal_Int32 rtl_str_shortenedCompareIgnoreAsciiCase_WithLength(
const sal_Char * first,
sal_Int32 firstLen,
const sal_Char * second,
sal_Int32 secondLen,
sal_Int32 shortenedLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings with a maximum count of characters, ignoring the case of ASCII characters.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. Character values between 65 and 90 (ASCII A--Z) are interpreted as values between 97 and 122 (ASCII a--z). This function cannot be used for language-specific sorting.
Parameters
first
the first string to be compared.  Need not be null-terminated, but must be
at least as long as the specified firstLen.

firstLen
the length of the first string.

second
the second string which is compared with the first one.  Need not be
null-terminated, but must be at least as long as the specified secondLen.

secondLen
the length of the second string.

shortenedLen
the maximum number of characters to compare.  This length can be greater
or smaller than the lengths of the two strings.

Return
0 if both substrings are equal, a value less than 0 if the first substring is less than the second substring, and a value greater than 0 if the first substring is greater than the second substring.

rtl_str_shortenedCompare_WithLength
extern "C"
sal_Int32 rtl_str_shortenedCompare_WithLength(
const sal_Char * first,
sal_Int32 firstLen,
const sal_Char * second,
sal_Int32 secondLen,
sal_Int32 shortenedLen );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Compare two strings with a maximum count of characters.
Description
The comparison is based on the numeric value of each character in the strings and returns a value indicating their relationship. This function cannot be used for language-specific sorting.
Parameters
first
    the first string to be compared.  Need not be null-terminated, but must be
    at least as long as the specified firstLen.

    
firstLen
    the length of the first string.

    
second
    the second string which is compared with the first one.  Need not be
    null-terminated, but must be at least as long as the specified secondLen.

    
secondLen
    the length of the second string.

    
shortenedLen
    the maximum number of characters to compare.  This length can be greater
    or smaller than the lengths of the two strings.

    
Return
0 if both substrings are equal, a value less than 0 if the first substring is less than the second substring, and a value greater than 0 if the first substring is greater than the second substring.

rtl_str_toAsciiLowerCase
extern "C"
void rtl_str_toAsciiLowerCase(
sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Convert all ASCII uppercase letters to lowercase within a string.
Description
The characters with values between 65 and 90 (ASCII A--Z) are replaced with values between 97 and 122 (ASCII a--z). The string must be null-terminated.
Parameters
str
    a null-terminated string.
 

rtl_str_toAsciiLowerCase_WithLength
extern "C"
void rtl_str_toAsciiLowerCase_WithLength(
sal_Char * str,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Convert all ASCII uppercase letters to lowercase within a string.
Description
The characters with values between 65 and 90 (ASCII A--Z) are replaced with values between 97 and 122 (ASCII a--z).
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.
 

rtl_str_toAsciiUpperCase
extern "C"
void rtl_str_toAsciiUpperCase(
sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Convert all ASCII lowercase letters to uppercase within a string.
Description
The characters with values between 97 and 122 (ASCII a--z) are replaced with values between 65 and 90 (ASCII A--Z). The string must be null-terminated.
Parameters
str
    a null-terminated string.
 

rtl_str_toAsciiUpperCase_WithLength
extern "C"
void rtl_str_toAsciiUpperCase_WithLength(
sal_Char * str,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Convert all ASCII lowercase letters to uppercase within a string.
Description
The characters with values between 97 and 122 (ASCII a--z) are replaced with values between 65 and 90 (ASCII A--Z).
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the length of the string.
 

rtl_str_toBoolean
extern "C"
sal_Bool rtl_str_toBoolean(
const sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Interpret a string as a boolean.
Description
This function cannot be used for language-specific conversion. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
Return
true if the string is "1" or "true" in any ASCII case, false otherwise.

rtl_str_toDouble
extern "C"
double rtl_str_toDouble(
const sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Interpret a string as a double.
Description
This function cannot be used for language-specific conversion. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
Return
the float value represented by the string, or 0.0 if the string does not represent a double.

rtl_str_toFloat
extern "C"
float rtl_str_toFloat(
const sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Interpret a string as a float.
Description
This function cannot be used for language-specific conversion. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
Return
the float value represented by the string, or 0.0 if the string does not represent a float.

rtl_str_toInt32
extern "C"
sal_Int32 rtl_str_toInt32(
const sal_Char * str,
sal_Int16 radix );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Interpret a string as an integer.
Description
This function cannot be used for language-specific conversion. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
radix
    the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
    (36), inclusive.

    
Return
the integer value represented by the string, or 0 if the string does not represent an integer.

rtl_str_toInt64
extern "C"
sal_Int64 rtl_str_toInt64(
const sal_Char * str,
sal_Int16 radix );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Interpret a string as a long integer.
Description
This function cannot be used for language-specific conversion. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
radix
    the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
    (36), inclusive.

    
Return
the long integer value represented by the string, or 0 if the string does not represent a long integer.

rtl_str_trim
extern "C"
sal_Int32 rtl_str_trim(
sal_Char * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Remove white space from both ends of a string.
Description
All characters with values less than or equal to 32 (the space character) are considered to be white space. This function cannot be used for language-specific operations. The string must be null-terminated.
Parameters
str
    a null-terminated string.

    
Return
the new length of the string.

rtl_str_trim_WithLength
extern "C"
sal_Int32 rtl_str_trim_WithLength(
sal_Char * str,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Remove white space from both ends of the string.
Description
All characters with values less than or equal to 32 (the space character) are considered to be white space. This function cannot be used for language-specific operations. The string must be null-terminated.
Parameters
str
    a string.  Need not be null-terminated, but must be at least as long as
    the specified len.

    
len
    the original length of the string.

    
Return
the new length of the string.

rtl_str_valueOfBoolean
extern "C"
sal_Int32 rtl_str_valueOfBoolean(
sal_Char * str,
sal_Bool b );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of a boolean.
Description
If b is true, the buffer is filled with the string "true" and 5 is returned. If b is false, the buffer is filled with the string "false" and 6 is returned. This function cannot be used for language-specific operations.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFBOOLEAN define to create
    a buffer that is big enough.

    
b
    a boolean value.

    
Return
the length of the string.

rtl_str_valueOfChar
extern "C"
sal_Int32 rtl_str_valueOfChar(
sal_Char * str,
sal_Char ch );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of a character.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFCHAR define to create a
    buffer that is big enough.

    
ch
    a character value.

    
Return
the length of the string.

rtl_str_valueOfDouble
extern "C"
sal_Int32 rtl_str_valueOfDouble(
sal_Char * str,
double d );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of a double.
Description
This function cannot be used for language-specific conversion.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFDOUBLE define to create
    a buffer that is big enough.

    
d
    a double value.

    
Return
the length of the string.

rtl_str_valueOfFloat
extern "C"
sal_Int32 rtl_str_valueOfFloat(
sal_Char * str,
float f );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of a float.
Description
This function cannot be used for language-specific conversion.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFFLOAT define to create a
    buffer that is big enough.

    
f
    a float value.

    
Return
the length of the string.

rtl_str_valueOfInt32
extern "C"
sal_Int32 rtl_str_valueOfInt32(
sal_Char * str,
sal_Int32 i,
sal_Int16 radix );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of an integer.
Description
This function cannot be used for language-specific operations.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFINT32 define to create a
    buffer that is big enough.

    
i
    an integer value.

    
radix
    the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
    (36), inclusive.

    
Return
the length of the string.

rtl_str_valueOfInt64
extern "C"
sal_Int32 rtl_str_valueOfInt64(
sal_Char * str,
sal_Int64 l,
sal_Int16 radix );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create the string representation of a long integer.
Description
This function cannot be used for language-specific operations.
Parameters
str
    a buffer that is big enough to hold the result and the terminating NUL
    character.  You should use the RTL_STR_MAX_VALUEOFINT64 define to create a
    buffer that is big enough.

    
l
    a long integer value.

    
radix
    the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
    (36), inclusive.

    
Return
the length of the string.

rtl_string_acquire
extern "C"
void rtl_string_acquire(
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Increment the reference count of a string.
Parameters
str
    a string.
 

rtl_string_assign
extern "C"
void rtl_string_assign(
rtl_String * * str,
rtl_String * rightValue );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Assign a new value to a string.
Description
First releases any value str might currently hold, then acquires rightValue.
Parameters
str
    pointer to the string.  The pointed-to data must be null or a valid
    string.

    
rightValue
    a valid string.
 

rtl_string_getLength
extern "C"
sal_Int32 rtl_string_getLength(
const rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Return the length of a string.
Description
The length is equal to the number of characters in the string.
Parameters
str
    a valid string.

    
Return
the length of the string.

rtl_string_getStr
extern "C"
sal_Char * rtl_string_getStr(
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Return a pointer to the underlying character array of a string.
Parameters
str
    a valid string.

    
Return
a pointer to the null-terminated character array.

rtl_string_getToken
extern "C"
sal_Int32 rtl_string_getToken(
rtl_String * * newStr,
rtl_String * str,
sal_Int32 token,
sal_Char cTok,
sal_Int32 idx );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by extracting a single token from another string.
Description
Starting at index, the token's next token is searched for. If there is no such token, the result is an empty string. Otherwise, all characters from the start of that token and up to, but not including the next occurrence of cTok make up the resulting token. The return value is the position of the next token, or -1 if no more tokens follow. Example code could look like rtl_String * pToken = NULL; sal_Int32 nIndex = 0; do { ... nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex); ... } while (nIndex >= 0); The new string does not necessarily have a reference count of 1, so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.  If either token or index is negative, an empty token is stored in
    newStr (and -1 is returned).

    
str
    a valid string.

    
token
    the number of the token to return, starting at index.

    
cTok
    the character that seperates the tokens.

    
index
    the position at which searching for the token starts.  Must not be greater
    than the length of str.

    
Return
the index of the next token, or -1 if no more tokens follow.

rtl_string_new
extern "C"
void rtl_string_new(
rtl_String * * newStr );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Allocate a new string containing no characters.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.
 

rtl_string_newConcat
extern "C"
void rtl_string_newConcat(
rtl_String * * newStr,
rtl_String * left,
rtl_String * right );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string that is the concatenation of two other strings.
Description
The new string does not necessarily have a reference count of 1 (in cases where one of the two other strings is empty), so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
left
    a valid string.

    
right
    a valid string.
 

rtl_string_newFromStr
extern "C"
void rtl_string_newFromStr(
rtl_String * * newStr,
const sal_Char * value );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Allocate a new string that contains a copy of a character array.
Description
If the length of value is greater than zero, the reference count of the new string will be 1. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
value
    a null-terminated character array.
 

rtl_string_newFromStr_WithLength
extern "C"
void rtl_string_newFromStr_WithLength(
rtl_String * * newStr,
const sal_Char * value,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Allocate a new string that contains a copy of a character array.
Description
If the length of value is greater than zero, the reference count of the new string will be 1. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
value
    a character array.  Need not be null-terminated, but must be at least as
    long as the specified len.

    
len
    the length of the character array.
 

rtl_string_newFromString
extern "C"
void rtl_string_newFromString(
rtl_String * * newStr,
const rtl_String * value );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Allocate a new string that contains a copy of another string.
Description
If the length of value is greater than zero, the reference count of the new string will be 1. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
value
    a valid string.
 

rtl_string_newReplace
extern "C"
void rtl_string_newReplace(
rtl_String * * newStr,
rtl_String * str,
sal_Char oldChar,
sal_Char newChar );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by replacing all occurrences of a single character within another string.
Description
The new string results from replacing all occurrences of oldChar in str with newChar. The new string does not necessarily have a reference count of 1 (in cases where oldChar does not occur in str), so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
pointer to the new string.  The pointed-to data must be null or a valid
string.

str
a valid string.

oldChar
the old character.

newChar
the new character.

rtl_string_newReplaceStrAt
extern "C"
void rtl_string_newReplaceStrAt(
rtl_String * * newStr,
rtl_String * str,
sal_Int32 idx,
sal_Int32 count,
rtl_String * subStr );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by replacing a substring of another string.
Description
The new string results from replacing a number of characters (count), starting at the specified position (index) in the original string (str), with some new substring (subStr). If subStr is null, than only a number of characters is deleted. The new string does not necessarily have a reference count of 1, so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
str
    a valid string.

    
index
    the index into str at which to start replacement.  Must be between 0 and
    the length of str, inclusive.

    
count
    the number of charcters to remove.  Must not be negative, and the sum of
    index and count must not exceed the length of str.

    
subStr
    either null or a valid string to be inserted.
 

rtl_string_newToAsciiLowerCase
extern "C"
void rtl_string_newToAsciiLowerCase(
rtl_String * * newStr,
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by converting all ASCII uppercase letters to lowercase within another string.
Description
The new string results from replacing all characters with values between 65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z). This function cannot be used for language-specific conversion. The new string does not necessarily have a reference count of 1 (in cases where no characters need to be converted), so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
pointer to the new string.  The pointed-to data must be null or a valid
string.

str
a valid string.

rtl_string_newToAsciiUpperCase
extern "C"
void rtl_string_newToAsciiUpperCase(
rtl_String * * newStr,
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by converting all ASCII lowercase letters to uppercase within another string.
Description
The new string results from replacing all characters with values between 97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z). This function cannot be used for language-specific conversion. The new string does not necessarily have a reference count of 1 (in cases where no characters need to be converted), so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
pointer to the new string.  The pointed-to data must be null or a valid
string.

str
a valid string.

rtl_string_newTrim
extern "C"
void rtl_string_newTrim(
rtl_String * * newStr,
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new string by removing white space from both ends of another string.
Description
The new string results from removing all characters with values less than or equal to 32 (the space character) form both ends of str. This function cannot be used for language-specific conversion. The new string does not necessarily have a reference count of 1 (in cases where no characters need to be removed), so it must not be modified without checking the reference count. This function does not handle out-of-memory conditions.
Parameters
newStr
pointer to the new string.  The pointed-to data must be null or a valid
string.

str
a valid string.

rtl_string_new_WithLength
extern "C"
void rtl_string_new_WithLength(
rtl_String * * newStr,
sal_Int32 len );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Allocate a new string containing space for a given number of characters.
Description
If len is greater than zero, the reference count of the new string will be 1. The values of all characters are set to 0 and the length of the string is 0. This function does not handle out-of-memory conditions.
Parameters
newStr
    pointer to the new string.  The pointed-to data must be null or a valid
    string.

    
len
    the number of characters.
 

rtl_string_release
extern "C"
void rtl_string_release(
rtl_String * str );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Decrement the reference count of a string.
Description
If the count goes to zero than the string data is deleted.
Parameters
str
    a string.
 

rtl_uString2String
extern "C"
void rtl_uString2String(
rtl_String * * newStr,
const sal_Unicode * str,
sal_Int32 len,
rtl_TextEncoding encoding,
sal_uInt32 convertFlags );

virtual abstract const volatile template static inline C-linkage
NO NO NO NO NO NO NO YES

Summary
Create a new byte string by converting a Unicode string, using a specific text encoding.
Description
The lengths of the byte string and the Unicode string may differ (e.g., for double-byte encodings, UTF-7, UTF-8). If the length of the Unicode string is greater than zero, the reference count of the new string will be 1. If an out-of-memory condition occurs, newStr will point to a null pointer upon return.
Parameters
newStr
pointer to the new string.  The pointed-to data must be null or a valid
string.

str
a Unicode character array.  Need not be null-terminated, but must be at
least as long as the specified len.

len
the length of the Unicode character array.

encoding
the text encoding to use for conversion.

convertFlags
flags which control the conversion.  Either use
OUSTRING_TO_OSTRING_CVTFLAGS, or see
 for more
details.

Top of Page

Apache Software Foundation

Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.