diff options
| author | Stephan Bergmann <sb@openoffice.org> | 2001-10-30 12:41:07 +0000 |
|---|---|---|
| committer | Stephan Bergmann <sb@openoffice.org> | 2001-10-30 12:41:07 +0000 |
| commit | 51e5f01dc701e87929634ac4455c1fa537b472e9 (patch) | |
| tree | e212112bad37d7ec1e9b95618d98e27c0e9a021d /sal/inc/rtl | |
| parent | 9481c4dac68408b0a5f98e870baa87b469e9b7db (diff) | |
#88337# Documentation.
Diffstat (limited to 'sal/inc/rtl')
| -rw-r--r-- | sal/inc/rtl/strbuf.h | 19 | ||||
| -rw-r--r-- | sal/inc/rtl/strbuf.hxx | 60 | ||||
| -rw-r--r-- | sal/inc/rtl/string.h | 1652 | ||||
| -rw-r--r-- | sal/inc/rtl/string.hxx | 100 | ||||
| -rw-r--r-- | sal/inc/rtl/ustrbuf.h | 23 | ||||
| -rw-r--r-- | sal/inc/rtl/ustrbuf.hxx | 63 | ||||
| -rw-r--r-- | sal/inc/rtl/ustring.h | 2033 | ||||
| -rw-r--r-- | sal/inc/rtl/ustring.hxx | 175 |
8 files changed, 2337 insertions, 1788 deletions
diff --git a/sal/inc/rtl/strbuf.h b/sal/inc/rtl/strbuf.h index d33e41a7c559..e552ef1a2e3a 100644 --- a/sal/inc/rtl/strbuf.h +++ b/sal/inc/rtl/strbuf.h @@ -2,9 +2,9 @@ * * $RCSfile: strbuf.h,v $ * - * $Revision: 1.2 $ + * $Revision: 1.3 $ * - * last change: $Author: jsc $ $Date: 2001-04-26 13:34:01 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -70,9 +70,11 @@ extern "C" { #endif -/** +/** @HTML Allocates a new <code>String</code> that contains characters from - the character array argument. The <code>count</code> argument specifies + the character array argument. + + The <code>count</code> argument specifies the length of the array. The initial capacity of the string buffer is <code>16</code> plus the length of the string argument. @@ -86,7 +88,9 @@ void SAL_CALL rtl_stringbuffer_newFromStr_WithLength( rtl_String ** newStr, /** Allocates a new <code>String</code> that contains the same sequence of - characters as the string argument. The initial capacity is the larger of: + characters as the string argument. + + The initial capacity is the larger of: <ul> <li> The <code>bufferLen</code> argument. <li> The <code>length</code> of the string argument. @@ -104,6 +108,7 @@ sal_Int32 SAL_CALL rtl_stringbuffer_newFromStringBuffer( rtl_String ** newStr, /** Ensures that the capacity of the buffer is at least equal to the specified minimum. + If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: @@ -125,7 +130,7 @@ void SAL_CALL rtl_stringbuffer_ensureCapacity( /*inout*/rtl_String ** This, /** Inserts the string representation of the <code>char</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -148,5 +153,3 @@ void SAL_CALL rtl_stringbuffer_insert( /*inout*/rtl_String ** This, #endif #endif /* _RTL_STRBUF_H_ */ - - diff --git a/sal/inc/rtl/strbuf.hxx b/sal/inc/rtl/strbuf.hxx index 2732d1b1d9e2..fc32b57cb172 100644 --- a/sal/inc/rtl/strbuf.hxx +++ b/sal/inc/rtl/strbuf.hxx @@ -2,9 +2,9 @@ * * $RCSfile: strbuf.hxx,v $ * - * $Revision: 1.5 $ + * $Revision: 1.6 $ * - * last change: $Author: sb $ $Date: 2001-10-15 07:58:51 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -74,7 +74,8 @@ namespace rtl { -/** +/** @HTML + A string buffer implements a mutable sequence of characters. <p> String buffers are safe for use by multiple threads. The methods @@ -155,7 +156,9 @@ public: /** Constructs a string buffer so that it represents the same - sequence of characters as the string argument. The initial + sequence of characters as the string argument. + + The initial capacity of the string buffer is <code>16</code> plus the length of the string argument. @@ -191,7 +194,8 @@ public: } /** - Fill the string data in the new string and clear the buffer.<BR> + Fill the string data in the new string and clear the buffer. + This method is more efficient than the contructor of the string. It does not copy the buffer. @@ -216,7 +220,9 @@ public: } /** - Returns the current capacity of the String buffer. The capacity + Returns the current capacity of the String buffer. + + The capacity is the amount of storage available for newly inserted characters. The real buffer size is 2 bytes longer, because all strings are 0 terminated. @@ -231,6 +237,7 @@ public: /** Ensures that the capacity of the buffer is at least equal to the specified minimum. + If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: @@ -250,6 +257,7 @@ public: /** Sets the length of this String buffer. + If the <code>newLength</code> argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the @@ -276,7 +284,7 @@ public: /** Returns the character at a specific index in this string buffer. - <p> + The first character of a string buffer is at index <code>0</code>, the next at index <code>1</code>, and so on, for array indexing. @@ -306,7 +314,7 @@ public: /** The character at the specified index of this string buffer is set to <code>ch</code>. - <p> + The offset argument must be greater than or equal to <code>0</code>, and less than the length of this string buffer. @@ -321,7 +329,7 @@ public: /** Appends the string to this string buffer. - <p> + The characters of the <code>String</code> argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. @@ -337,7 +345,7 @@ public: /** Appends the string representation of the <code>char</code> array argument to this string buffer. - <p> + The characters of the array argument are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the length of the argument. @@ -353,7 +361,7 @@ public: /** Appends the string representation of the <code>char</code> array argument to this string buffer. - <p> + Characters of the character array <code>str</code> are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of <code>len</code>. @@ -372,7 +380,7 @@ public: /** Appends the string representation of the <code>sal_Bool</code> argument to the string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -389,7 +397,7 @@ public: /** Appends the string representation of the <code>char</code> argument to this string buffer. - <p> + The argument is appended to the contents of this string buffer. The length of this string buffer increases by <code>1</code>. @@ -404,7 +412,7 @@ public: /** Appends the string representation of the <code>sal_Int32</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -421,7 +429,7 @@ public: /** Appends the string representation of the <code>long</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -438,7 +446,7 @@ public: /** Appends the string representation of the <code>float</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -455,7 +463,7 @@ public: /** Appends the string representation of the <code>double</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -471,7 +479,7 @@ public: /** Inserts the string into this string buffer. - <p> + The characters of the <code>String</code> argument are inserted, in order, into this string buffer at the indicated offset. The length of this string buffer is increased by the length of the argument. @@ -492,7 +500,7 @@ public: /** Inserts the string representation of the <code>char</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -510,7 +518,7 @@ public: /** Inserts the string representation of the <code>char</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -531,7 +539,7 @@ public: /** Inserts the string representation of the <code>sal_Bool</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -554,7 +562,7 @@ public: /** Inserts the string representation of the <code>char</code> argument into this string buffer. - <p> + The second argument is inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by one. @@ -575,7 +583,7 @@ public: /** Inserts the string representation of the second <code>sal_Int32</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -598,7 +606,7 @@ public: /** Inserts the string representation of the <code>long</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -621,7 +629,7 @@ public: /** Inserts the string representation of the <code>float</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -644,7 +652,7 @@ public: /** Inserts the string representation of the <code>double</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated diff --git a/sal/inc/rtl/string.h b/sal/inc/rtl/string.h index 8cc744027d40..9023d2ba32f5 100644 --- a/sal/inc/rtl/string.h +++ b/sal/inc/rtl/string.h @@ -2,9 +2,9 @@ * * $RCSfile: string.h,v $ * - * $Revision: 1.6 $ + * $Revision: 1.7 $ * - * last change: $Author: th $ $Date: 2001-07-27 13:20:22 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -75,592 +75,703 @@ extern "C" { /* ======================================================================= */ -/** - Returns the length of a string. - The length is equal to the number of 8-bit characters in the - string without the terminating NULL-character. +/** Return the length of a string. - @param str must be a NULL-terminated string. - @return the length of the sequence of characters represented by this - string, excluding the terminating NULL-character. -*/ + The length is equal to the number of 8-bit characters in the string, + without the terminating NUL character. + + @param str + a null-terminated string. + + @return + the length of the sequence of characters represented by this string, + excluding the terminating NUL character. + */ sal_Int32 SAL_CALL rtl_str_getLength( const sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - 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. - Both strings must be NULL-terminated. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated string which is compared - with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings. + + 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. + + @param first + the first null-terminated string to be compared. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_compare( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_compare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param secondLen + the length of the second string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - 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. - The string length must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with - the first param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings from back to front. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both strings must be NULL-terminated. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated string which is compared - with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + @param first + the first null-terminated string to be compared. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings with a maximum count - of characters for each string. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the - first param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings with a maximum count - of characters for each string. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters, ignoring the case + of ASCII characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param secondLen + the length of the second string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - Returns a hashcode for a string. - It is not allowed to store the hash code, because newer versions - could return other hashcodes. - The string must be NULL-terminated. +/** Return a hash code for a string. + + It is not allowed to store the hash code persistently, because later + versions could return other hash codes. The string must be + null-terminated. + + @param str + a null-terminated string. - @param str a NULL-terminated string. - @return a hash code value for str. -*/ + @return + a hash code for the given string. + */ sal_Int32 SAL_CALL rtl_str_hashCode( const sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Returns a hashcode for a substring. - It is not allowed to store the hash code, because newer versions - could return other hashcodes. - - @param str a string. - @param len the maximum number of characters for creating the - hashcode. The string length must be greater or equal - than this value. - @return a hash code value for str. -*/ +/** Return a hash code for a string. + + It is not allowed to store the hash code persistently, because later + versions could return other hash codes. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @return + a hash code for the given string. + */ sal_Int32 SAL_CALL rtl_str_hashCode_WithLength( const sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified character. - The string must be NULL-terminated. - - @param str a NULL-terminated string. - @param ch character to be located. - @return the index of the first occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. -*/ +/** Search for the first occurrence of a character within a string. + + The string must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_indexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the substring of the first occurrence of the - specified character. - The string length must be greater or equal as the given len. - - @param str a substring. - @param len the maximum number of characters. The string length - must be greater or equal than this value. - @param ch character to be located. - @return the index of the first occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. -*/ +/** Search for the first occurrence of a character within a string. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of the - specified character, searching backward starting at the end. - The string must be NULL-terminated. - - @param str a NULL-terminated string. - @param ch character to be located. - @return the index of the last occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. - The return value is always lower as the string len. -*/ +/** Search for the last occurrence of a character within a string. + + The string must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_lastIndexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of the - specified character, searching backward starting at the specified - index (excluding the character at the specified index). - - @param str a substring. - @param len the starting index. The string length - must be greater or equal than this value. - @param ch character to be located. - @return the index of the last occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. - The return value is always lower as the len param. -*/ +/** Search for the last occurrence of a character within a string. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified substring. - If subStr doesn't include any character, always <code>-1</code> is - returned. This is also the case, if both strings are empty. - Both strings must be NULL-terminated. - - @param str a NULL-terminated string. - @param subStr a NULL-terminated substring to be searched for. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the first - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. -*/ +/** Search for the first occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + Both strings must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_indexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified substring. - If subLen is zero, always <code>-1</code> is returned. This is also - the case, if str is also zero. - Both string lengths must be equal or greater as there given length. - - @param str a string. - @param len the length of the string or the number of - characters to compared. The string length - must be greater or equal than this value. - @param subStr a substring to be searched for. - @param subLen the length of the substring or the number of - characters to compared. The substring length - must be greater or equal than this value. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the first - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. -*/ +/** Search for the first occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param subStr + the substring to be searched for. Need not be null-terminated, but must + be at least as long as the specified subLen. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of - the specified substring, searching backward starting at the end. - The returned index indicates the starting index of the substring. - If subStr doesn't include any character, always <code>-1</code> is - returned. This is also the case, if both strings are empty. - Both strings must be NULL-terminated. - - @param str a NULL-terminated string. - @param subStr a NULL-terminated substring to be searched for. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the last - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. The return value is - always lower as the string len. -*/ +/** Search for the last occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + Both strings must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_lastIndexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of - the specified substring, searching backward starting at the specified - index (excluding the character at the specified index). - The returned index indicates the starting index of the substring. - If subLen is zero, always <code>-1</code> is returned. This is also - the case, if str is also zero. - Both string lengths must be equal or greater as there given length. - - @param str a string. - @param len the length of the string or the number of - characters to compared. The string length - must be greater or equal than this value. - @param subStr a substring to be searched for. - @param subLen the length of the substring or the number of - characters to compared. The substring length - must be greater or equal than this value. - @return If the string argument occurs one or more times as a substring - within the string, then the index of the first character of - the last such substring is returned. If it does not occur as a - substring <code>-1</code> is returned. The return value is - always lower as the len param. -*/ +/** Search for the last occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param subStr + the substring to be searched for. Need not be null-terminated, but must + be at least as long as the specified subLen. + + @param 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. + */ sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); -/** - Replaces all occurrences of oldChar in the string with newChar. - If the character oldChar does not occur in the character sequence - represented by the string, then the string is not modified. - The string must be NULL-terminated. +/** Replace all occurrences of a single character within a string. + + If oldChar does not occur within str, then the string is not modified. + The string must be null-terminated. + + @param str + a null-terminated string. - @param str a NULL-terminated string. - @param oldChar the old character. - @param newChar the new character. -*/ + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_str_replaceChar( sal_Char * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); -/** - Replaces all occurrences of oldChar in the string with newChar. - If the character oldChar does not occur in the character sequence - represented by the string, then the string is not modified. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to replaced. The string length - must be greater or equal than this value. - @param oldChar the old character. - @param newChar the new character. -*/ +/** Replace all occurrences of a single character within a string. + + If oldChar does not occur within str, then the string is not modified. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_str_replaceChar_WithLength( sal_Char * str, sal_Int32 len, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII uppercase characters (65-90) in the string to - ASCII lowercase characters (97-122). - The string must be NULL-terminated. +/** Convert all ASCII uppercase letters to lowercase within a string. - @param str a NULL-terminated string. -*/ + 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. + + @param str + a null-terminated string. + */ void SAL_CALL rtl_str_toAsciiLowerCase( sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII uppercase characters (65-90) in the string to - ASCII lowercase characters (97-122). - This function can't be used for language specific conversion. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. -*/ +/** Convert all ASCII uppercase letters to lowercase within a string. + + The characters with values between 65 and 90 (ASCII A--Z) are replaced + with values between 97 and 122 (ASCII a--z). + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + */ void SAL_CALL rtl_str_toAsciiLowerCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Convert all ASCII lowercase letters to uppercase within a string. - @param str a NULL-terminated string. -*/ + 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. + + @param str + a null-terminated string. + */ void SAL_CALL rtl_str_toAsciiUpperCase( sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. -*/ +/** Convert all ASCII lowercase letters to uppercase within a string. + + The characters with values between 97 and 122 (ASCII a--z) are replaced + with values between 65 and 90 (ASCII A--Z). + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + */ void SAL_CALL rtl_str_toAsciiUpperCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Removes white space from both ends of the string. - All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Remove white space from both ends of a string. - @param str a NULL-terminated string. - @return new length of the string. -*/ + 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. + + @param str + a null-terminated string. + + @return + the new length of the string. + */ sal_Int32 SAL_CALL rtl_str_trim( sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Removes white space from both ends of the string. - All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. - @return new length of the string. -*/ +/** Remove white space from both ends of the string. + + 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. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the original length of the string. + + @return + the new length of the string. + */ sal_Int32 SAL_CALL rtl_str_trim_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Returns the string representation of the sal_Bool argument. - If the sal_Bool is true, the buffer is filled with the - string "true" and 5 is returned. - If the sal_Bool is false, the buffer is filled with the - string "false" and 6 is returned. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFBOOLEAN - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param b a sal_Bool. - @return the length of the string. -*/ +/** Create the string representation of a boolean. + + 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. + + @param 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. + + @param b + a boolean value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfBoolean( sal_Char * str, sal_Bool b ) SAL_THROW_EXTERN_C(); #define RTL_STR_MAX_VALUEOFBOOLEAN 6 -/** - Returns the string representation of the char argument. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFCHAR - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param ch a char. - @return the length of the string. -*/ +/** Create the string representation of a character. + + @param 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. + + @param ch + a character value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfChar( sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C(); #define RTL_STR_MAX_VALUEOFCHAR 2 -/** - Returns the string representation of the int argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFINT32 - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param i a int32. - @param radix the radix (between 2 and 36) - @return the length of the string. -*/ +/** Create the string representation of an integer. + + This function cannot be used for language-specific operations. + + @param 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. + + @param i + an integer value. + + @param radix + the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX + (36), inclusive. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfInt32( sal_Char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C(); #define RTL_STR_MIN_RADIX 2 #define RTL_STR_MAX_RADIX 36 #define RTL_STR_MAX_VALUEOFINT32 33 -/** - Returns the string representation of the long argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFINT64 - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param l a int64. - @param radix the radix (between 2 and 36) - @return the length of the string. -*/ +/** Create the string representation of a long integer. + + This function cannot be used for language-specific operations. + + @param 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. + + @param l + a long integer value. + + @param radix + the radix. Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX + (36), inclusive. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfInt64( sal_Char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); #define RTL_STR_MAX_VALUEOFINT64 65 -/** - Returns the string representation of the float argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFFLOAT - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param f a float. - @return the length of the string. -*/ +/** Create the string representation of a float. + + This function cannot be used for language-specific conversion. + + @param 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. + + @param f + a float value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfFloat( sal_Char * str, float f ) SAL_THROW_EXTERN_C(); #define RTL_STR_MAX_VALUEOFFLOAT 15 -/** - Returns the string representation of the double argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_STR_MAX_VALUEOFDOUBLE - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param d a double. - @return the length of the string. -*/ +/** Create the string representation of a double. + + This function cannot be used for language-specific conversion. + + @param 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. + + @param d + a double value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_str_valueOfDouble( sal_Char * str, double d ) SAL_THROW_EXTERN_C(); #define RTL_STR_MAX_VALUEOFDOUBLE 25 -/** - Returns the Boolean value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a boolean. + + This function cannot be used for language-specific conversion. The string + must be null-terminated. - @param str a NULL-terminated string. - @return sal_True, if the string is 1 or "True" in any ASCII case. - sal_False in any other case. -*/ + @param str + a null-terminated string. + + @return + true if the string is "1" or "true" in any ASCII case, false otherwise. + */ sal_Bool SAL_CALL rtl_str_toBoolean( const sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Returns the int32 value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as an integer. + + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. - @param str a NULL-terminated string. - @param radix the radix (between 2 and 36) - @return the int32 represented by the string. - 0 if the string represents no number. -*/ + @param 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. + */ sal_Int32 SAL_CALL rtl_str_toInt32( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); -/** - Returns the int64 value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a long integer. + + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. - @param str a NULL-terminated string. - @param radix the radix (between 2 and 36) - @return the int64 represented by the string. - 0 if the string represents no number. -*/ + @param 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. + */ sal_Int64 SAL_CALL rtl_str_toInt64( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); -/** - Returns the float value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a float. + + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. - @param str a NULL-terminated string. - @return the float represented by the string. - 0.0 if the string represents no number. -*/ + @return + the float value represented by the string, or 0.0 if the string does not + represent a float. + */ float SAL_CALL rtl_str_toFloat( const sal_Char * str ) SAL_THROW_EXTERN_C(); -/** - Returns the double value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a double. + + This function cannot be used for language-specific conversion. The string + must be null-terminated. - @param str a NULL-terminated string. - @return the double represented by the string. - 0.0 if the string represents no number. -*/ + @param str + a null-terminated string. + + @return + the float value represented by the string, or 0.0 if the string does not + represent a double. + */ double SAL_CALL rtl_str_toDouble( const sal_Char * str ) SAL_THROW_EXTERN_C(); /* ======================================================================= */ @@ -671,9 +782,10 @@ double SAL_CALL rtl_str_toDouble( const sal_Char * str ) SAL_THROW_EXTERN_C(); #pragma pack(1) #endif -/** - The implementation structure of a byte string. -*/ +/** The implementation of a byte string. + + @internal + */ typedef struct _rtl_String { sal_Int32 refCount; @@ -689,263 +801,313 @@ typedef struct _rtl_String /* ----------------------------------------------------------------------- */ -/** - Increment the reference count of the string. +/** Increment the reference count of a string. - @param str the string. -*/ + @param str + a string. + */ void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Decrement the reference count of the string. If the count goes - to zero than the string data is deleted. +/** Decrement the reference count of a string. + + If the count goes to zero than the string data is deleted. - @param str the string. -*/ + @param str + a string. + */ void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string containing no characters. +/** Allocate a new string containing no characters. - @param newStr pointer to the new string. The data must be 0 or - a valid string. -*/ + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + */ void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string containing space for the given - numbers of characters. - The reference count of the new string is 1 or an empty string. - The values of all characters are set to 0 and the length of the - string is 0, only data is allocated for holding characters. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param len number of characters. -*/ +/** Allocate a new string containing space for a given number of characters. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param len + the number of characters. + */ void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains the same sequence of - characters as the string argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a valid string. -*/ +/** Allocate a new string that contains a copy of another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a valid string. + */ void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains the same sequence of - characters contained in the character array argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a NULL-terminated character array. -*/ +/** Allocate a new string that contains a copy of a character array. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a null-terminated character array. + */ void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains characters from - the character array argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a character array. - @param len the number of character which should be copied. - The character array length must be greater or - equal than this value. -*/ +/** Allocate a new string that contains a copy of a character array. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a character array. Need not be null-terminated, but must be at least as + long as the specified len. + + @param len + the length of the character array. + */ void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Assign rightValue to *str. Release *str and aquire rightValue! +/** Assign a new value to a string. + + First releases any value str might currently hold, then acquires + rightValue. - @param str pointer to the string. The data must be 0 or - a valid string. - @param rightValue a valid string. -*/ + @param str + pointer to the string. The pointed-to data must be null or a valid + string. + + @param rightValue + a valid string. + */ void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C(); -/** - Returns the length of this string. - The length is equal to the number of characters in the string. +/** Return the length of a string. + + The length is equal to the number of characters in the string. + + @param str + a valid string. - @param str a valid string. - @return the length of the sequence of characters represented by the - string. -*/ + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Returns the pointer to the character array of the string. +/** Return a pointer to the underlying character array of a string. + + @param str + a valid string. - @param str a valid string. - @return a null terminated character array. -*/ + @return + a pointer to the null-terminated character array. + */ sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Concatenates the right string to the end of the left string and - returns the result in a new instance. - The new instance isn't in every case a new instance (for example, - if one or both strings are empty). The new string object could - be a shared instance and can't be modified without checking the - refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param left a valid string. - @param right a valid string. -*/ +/** Create a new string that is the concatenation of two other strings. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param left + a valid string. + + @param right + a valid string. + */ void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from replacing a number of characters (count) - from the specified position (index) in the string (str) and inserting - the string (subStr) at the specified position (index). - If subStr is 0, than only a number of characters (count) are deleted - at the specified position (index). - The new instance isn't in every case a new instance. The new string - object could be a shared instance and can't be modified without - checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param index the replacing index in str. - The index must be greater or equal as 0 and - less or equal as the length of the string. - @param count the count of charcters that will replaced - The count must be greater or equal as 0 and - less or equal as the length of the string minus index. - @param subStr 0 or a valid string, which is inserted at nIndex. - If subStr is 0, only a number of characters (count) - are deleted at the specified position (index). -*/ +/** Create a new string by replacing a substring of another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param index + the index into str at which to start replacement. Must be between 0 and + the length of str, inclusive. + + @param 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. + + @param subStr + either null or a valid string to be inserted. + */ void SAL_CALL rtl_string_newReplaceStrAt( rtl_String ** newStr, rtl_String * str, sal_Int32 index, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from replacing all occurrences of - oldChar in this string with newChar. - If the character oldChar does not occur in the character sequence - represented by this object, then the string is assigned with - str. The new instance isn't in every case a new instance. The new - string object could be a shared instance and can't be modified without - checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param oldChar the old character. - @param newChar the new character. -*/ +/** Create a new string by replacing all occurrences of a single character + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_string_newReplace( rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from converting all - ASCII uppercase characters (65-90) in the string to - ASCII lowercase characters (97-122). - This function can't be used for language specific conversion. - If the string doesn't contain characters which must be converted, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. -*/ +/** Create a new string by converting all ASCII uppercase letters to lowercase + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + */ void SAL_CALL rtl_string_newToAsciiLowerCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from converting all - ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - If the string doesn't contain characters which must be converted, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. +/** Create a new string by converting all ASCII lowercase letters to uppercase + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. */ void SAL_CALL rtl_string_newToAsciiUpperCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from removing white space from both ends - of the string. All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - If the string doesn't contain white spaces at both ends, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. -*/ +/** Create a new string by removing white space from both ends of another + string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + */ void SAL_CALL rtl_string_newTrim( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string for the token specified by nToken. If nToken is - greater than the last possible Token then the result is an empty string. - The return value is the position of the next token or -1, if the queried - token is the last one. - Example: - rtl_String* pToken = 0; - sal_Int32 nIndex = 0; - do - { - ... - nIndex = rtl_string_getToken( &pToken, pStr, 0, ';', nIndex ); - ... - } - while ( nIndex >= 0 ); - The new instance isn't in every case a new instance. The new string - object could be a shared instance and can't be modified without checking - the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param token the number of the token to return. The number - must be greater or equal as 0. - @param cTok the character which seperate the tokens. - @param index the position at which the token is searched in the - string. - The index must be greater or equal as 0 and - less or equal as the length of the string. - @return the index of the next token or -1, if the current token is - the last one -*/ +/** Create a new string by extracting a single token from another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param token + the number of the token to return, starting at index. Must be + non-negative. + + @param cTok + the character that seperates the tokens. + + @param index + the position at which searching for the token starts. Must be between 0 + and the length of str, inclusive. + + @return + the index of the next token, or -1 if no more tokens follow. + */ sal_Int32 SAL_CALL rtl_string_getToken( rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 index ) SAL_THROW_EXTERN_C(); /* ======================================================================= */ @@ -965,28 +1127,36 @@ sal_Int32 SAL_CALL rtl_string_getToken( rtl_String ** newStr , rtl_String * str, /* ----------------------------------------------------------------------- */ -/** - Allocates a new byte string from the seequence of Unicode characters - and convert the Unicode sequence to a byte sequence with the specified - text encoding. - The string length could be a different one as the specified length, - because not all text conversions result in the same byte length - (for example double byte encodings, UTF-7, UTF-8, ...). - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a Unicode character array. - @param len the number of character which should be converted. - The Unicode character array length must be - greater or equal than this value. - @param encoding the text encoding in which the Unicode character - sequence should be converted. - @param convertFlags flags which controls the conversion. - see RTL_UNICODETOTEXT_FLAGS_... -*/ +/** Create a new byte string by converting a Unicode string, using a specific + text encoding. + + 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. This function does not handle + out-of-memory conditions. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a Unicode character array. Need not be null-terminated, but must be at + least as long as the specified len. + + @param len + the length of the Unicode character array. + + @param encoding + the text encoding to use for conversion. + + @param convertFlags + flags which control the conversion. Either use + OUSTRING_TO_OSTRING_CVTFLAGS, or see + <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more + details. + */ void SAL_CALL rtl_uString2String( rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C(); #ifdef __cplusplus @@ -994,5 +1164,3 @@ void SAL_CALL rtl_uString2String( rtl_String ** newStr, const sal_Unicode * str, #endif #endif /* _RTL_STRING_H_ */ - - diff --git a/sal/inc/rtl/string.hxx b/sal/inc/rtl/string.hxx index 9cdd629a3f6d..a1a12de47667 100644 --- a/sal/inc/rtl/string.hxx +++ b/sal/inc/rtl/string.hxx @@ -2,9 +2,9 @@ * * $RCSfile: string.hxx,v $ * - * $Revision: 1.10 $ + * $Revision: 1.11 $ * - * last change: $Author: hr $ $Date: 2001-09-11 12:32:52 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -91,7 +91,7 @@ namespace rtl handle all the memory managament for you - and it do it more efficient. 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 change the string. This class + memory allocation) as long as you do not change the string. This class stores also the length of the string, so that many operations are faster as the C-str-functions. @@ -114,10 +114,14 @@ class OString friend class ::ByteString; public: + /** @internal */ rtl_String * pData; private: + /** @internal */ class DO_NOT_ACQUIRE; + + /** @internal */ OString( rtl_String * value, DO_NOT_ACQUIRE * ) { pData = value; @@ -200,6 +204,11 @@ public: rtl_uString2String( &pData, value, length, encoding, convertFlags ); } + /** Convert a ByteString (from the tools module) into an OString. + + Since both ByteString and OString internally use the same data + structure, this is a very cheap operation. + */ OString( const ByteString & value ) SAL_THROW(()); /** @@ -234,6 +243,7 @@ public: /** Returns the length of this string. + The length is equal to the number of characters in this string. @return the length of the sequence of characters represented by this @@ -243,6 +253,7 @@ public: /** Returns a pointer to the character buffer from this string. + It isn't necessarily NULL terminated. @return a pointer to the characters buffer from this object. @@ -251,6 +262,7 @@ public: /** Returns a pointer to the character buffer from this string. + It isn't necessarily NULL terminated. @return a pointer to the characters buffer from this object. @@ -259,14 +271,15 @@ public: /** 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. @param str the object to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareTo( const OString & str ) const SAL_THROW(()) { @@ -276,15 +289,16 @@ public: /** Compares two strings with an 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. @param str the object to be compared. @param maxLength the maximum count of characters to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareTo( const OString & rObj, sal_Int32 maxLength ) const SAL_THROW(()) { @@ -294,14 +308,15 @@ public: /** 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. @param str the object to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 reverseCompareTo( const OString & str ) const SAL_THROW(()) { @@ -311,6 +326,7 @@ public: /** 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. @@ -331,6 +347,7 @@ public: /** 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. @@ -354,6 +371,7 @@ public: /** Perform a comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -375,6 +393,7 @@ public: /** Perform a ASCII lowercase comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -441,7 +460,7 @@ public: @return the index of the first occurrence of the character in the character sequence represented by this string that is greater than or equal to fromIndex, or - <code>-1</code> if the character does not occur. + -1 if the character does not occur. */ sal_Int32 indexOf( sal_Char ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(()) { @@ -456,7 +475,7 @@ public: @param ch character to be located. @return the index of the last occurrence of the character in the character sequence represented by this string, or - <code>-1</code> if the character does not occur. + -1 if the character does not occur. */ sal_Int32 lastIndexOf( sal_Char ch ) const SAL_THROW(()) { @@ -470,7 +489,7 @@ public: @param ch character to be located. @return the index of the last occurrence of the character in the character sequence represented by this string that - is less or than or equal to fromIndex, or <code>-1</code> + is less or than or equal to fromIndex, or -1 if the character does not occur before that point. */ sal_Int32 lastIndexOf( sal_Char ch, sal_Int32 fromIndex ) const SAL_THROW(()) @@ -481,7 +500,8 @@ public: /** Returns the index within this string of the first occurrence of the specified substring, starting at the specified index. - If str doesn't include any character, always <code>-1</code> is + + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @@ -490,7 +510,7 @@ public: within this string at the starting index, then the index of the first character of the first such substring is returned. If it does not occur as a substring starting - at fromIndex or beyond, <code>-1</code> is returned. + at fromIndex or beyond, -1 is returned. */ sal_Int32 indexOf( const OString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(()) { @@ -502,16 +522,17 @@ public: /** Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end. + The returned index indicates the starting index of the substring in this string. - If str doesn't include any character, always <code>-1</code> is + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @return If the string argument occurs one or more times as a substring within this string, then the index of the first character of the last such substring is returned. If it does not occur as - a substring, <code>-1</code> is returned. + a substring, -1 is returned. */ sal_Int32 lastIndexOf( const OString & str ) const SAL_THROW(()) { @@ -522,9 +543,10 @@ public: /** Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end. + The returned index indicates the starting index of the substring in this string. - If str doesn't include any character, always <code>-1</code> is + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @@ -533,7 +555,7 @@ public: within this string at the starting index, then the index of the first character of the last such substring is returned. If it does not occur as a substring starting - at fromIndex or earlier, <code>-1</code> is returned. + at fromIndex or earlier, -1 is returned. */ sal_Int32 lastIndexOf( const OString & str, sal_Int32 fromIndex ) const SAL_THROW(()) { @@ -561,8 +583,9 @@ public: } /** - Returns a new string that is a substring of this string. The - substring begins at the specified beginIndex and + Returns a new string that is a substring of this string. + + The substring begins at the specified beginIndex and extends to the character at index endIndex - 1. @param beginIndex the beginning index, inclusive. @@ -624,6 +647,7 @@ public: /** Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar. + If the character oldChar does not occur in the character sequence represented by this object, then the string is assigned with str. @@ -643,6 +667,7 @@ public: /** Converts from this string all ASCII uppercase characters (65-90) to ASCII lowercase characters (97-122). + This function can't be used for language specific conversion. If the string doesn't contain characters which must be converted, then the new string is assigned with str. @@ -659,6 +684,7 @@ public: /** Converts from this string all ASCII lowercase characters (97-122) to ASCII uppercase characters (65-90). + This function can't be used for language specific conversion. If the string doesn't contain characters which must be converted, then the new string is assigned with str. @@ -674,7 +700,9 @@ public: /** Returns a new string resulting from removing white space from both ends - of the string. All characters that have codes less than or equal to + of the string. + + All characters that have codes less than or equal to 32 (the space character) are considered to be white space. If the string doesn't contain white spaces at both ends, then the new string is assigned with str. @@ -721,6 +749,7 @@ public: /** Returns the Boolean value from this string. + This function can't be used for language specific conversion. @return sal_True, if the string is 1 or "True" in any ASCII case. @@ -744,6 +773,7 @@ public: /** Returns the int32 value from this string. + This function can't be used for language specific conversion. @param radix the radix (between 2 and 36) @@ -757,6 +787,7 @@ public: /** Returns the int64 value from this string. + This function can't be used for language specific conversion. @param radix the radix (between 2 and 36) @@ -770,6 +801,7 @@ public: /** Returns the float value from this string. + This function can't be used for language specific conversion. @return the float represented from this string. @@ -782,6 +814,7 @@ public: /** Returns the double value from this string. + This function can't be used for language specific conversion. @return the double represented from this string. @@ -794,6 +827,7 @@ public: /** Returns the string representation of the sal_Bool argument. + If the sal_Bool is true, the string "true" is returned. If the sal_Bool is false, the string "false" is returned. This function can't be used for language specific conversion. @@ -822,6 +856,7 @@ public: /** Returns the string representation of the int argument. + This function can't be used for language specific conversion. @param i a int32. @@ -838,6 +873,7 @@ public: /** Returns the string representation of the long argument. + This function can't be used for language specific conversion. @param l a int64. @@ -854,6 +890,7 @@ public: /** Returns the string representation of the float argument. + This function can't be used for language specific conversion. @param f a float. @@ -869,6 +906,7 @@ public: /** Returns the string representation of the double argument. + This function can't be used for language specific conversion. @param d a double. @@ -885,8 +923,22 @@ public: /* ======================================================================= */ +/** A helper to use OStrings with hash maps. + + Instances of this class are unary function objects that can be used as + hash function arguments to STLPort's hash_map and similar constructs. + */ struct OStringHash { + /** Compute a hash code for a string. + + @param rString + a string. + + @return + a hash code for the string. This hash code should not be stored + persistently, as its computation may change in later revisions. + */ size_t operator()( const rtl::OString& rString ) const { return (size_t)rString.hashCode(); } }; diff --git a/sal/inc/rtl/ustrbuf.h b/sal/inc/rtl/ustrbuf.h index c8a10f72f8c6..53b589822832 100644 --- a/sal/inc/rtl/ustrbuf.h +++ b/sal/inc/rtl/ustrbuf.h @@ -2,9 +2,9 @@ * * $RCSfile: ustrbuf.h,v $ * - * $Revision: 1.2 $ + * $Revision: 1.3 $ * - * last change: $Author: jsc $ $Date: 2001-04-26 13:34:01 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -70,9 +70,11 @@ extern "C" { #endif -/** +/** @HTML Allocates a new <code>String</code> that contains characters from - the character array argument. The <code>count</code> argument specifies + the character array argument. + + The <code>count</code> argument specifies the length of the array. The initial capacity of the string buffer is <code>16</code> plus the length of the string argument. @@ -86,7 +88,9 @@ void SAL_CALL rtl_uStringbuffer_newFromStr_WithLength( rtl_uString ** newStr, /** Allocates a new <code>String</code> that contains the same sequence of - characters as the string argument. The initial capacity is the larger of: + characters as the string argument. + + The initial capacity is the larger of: <ul> <li> The <code>bufferLen</code> argument. <li> The <code>length</code> of the string argument. @@ -104,6 +108,7 @@ sal_Int32 SAL_CALL rtl_uStringbuffer_newFromStringBuffer( rtl_uString ** newStr, /** Ensures that the capacity of the buffer is at least equal to the specified minimum. + If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: @@ -124,7 +129,7 @@ void SAL_CALL rtl_uStringbuffer_ensureCapacity( /*inout*/rtl_uString ** This, /** Inserts the string representation of the <code>str</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -145,7 +150,9 @@ void SAL_CALL rtl_uStringbuffer_insert( /*inout*/rtl_uString ** This, /** Inserts the 8-Bit ASCII string representation of the <code>str</code> - array argument into this string buffer. Since this function is optimized + array argument into this string buffer. + + Since this function 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 127. @@ -172,5 +179,3 @@ void SAL_CALL rtl_uStringbuffer_insert_ascii( /*inout*/rtl_uString ** This, #endif #endif /* _RTL_USTRBUF_H_ */ - - diff --git a/sal/inc/rtl/ustrbuf.hxx b/sal/inc/rtl/ustrbuf.hxx index 75ba467ce60a..5831d821c101 100644 --- a/sal/inc/rtl/ustrbuf.hxx +++ b/sal/inc/rtl/ustrbuf.hxx @@ -2,9 +2,9 @@ * * $RCSfile: ustrbuf.hxx,v $ * - * $Revision: 1.5 $ + * $Revision: 1.6 $ * - * last change: $Author: sb $ $Date: 2001-10-15 07:58:51 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -77,7 +77,7 @@ namespace rtl { -/** +/** @HTML A string buffer implements a mutable sequence of characters. <p> String buffers are safe for use by multiple threads. The methods @@ -158,7 +158,9 @@ public: /** Constructs a string buffer so that it represents the same - sequence of characters as the string argument. The initial + sequence of characters as the string argument. + + The initial capacity of the string buffer is <code>16</code> plus the length of the string argument. @@ -194,7 +196,8 @@ public: } /** - Fill the string data in the new string and clear the buffer.<BR> + Fill the string data in the new string and clear the buffer. + This method is more efficient than the contructor of the string. It does not copy the buffer. @@ -219,7 +222,9 @@ public: } /** - Returns the current capacity of the String buffer. The capacity + Returns the current capacity of the String buffer. + + The capacity is the amount of storage available for newly inserted characters. The real buffer size is 2 bytes longer, because all strings are 0 terminated. @@ -234,6 +239,7 @@ public: /** Ensures that the capacity of the buffer is at least equal to the specified minimum. + If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: @@ -253,6 +259,7 @@ public: /** Sets the length of this String buffer. + If the <code>newLength</code> argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the @@ -279,7 +286,7 @@ public: /** Returns the character at a specific index in this string buffer. - <p> + The first character of a string buffer is at index <code>0</code>, the next at index <code>1</code>, and so on, for array indexing. @@ -309,7 +316,7 @@ public: /** The character at the specified index of this string buffer is set to <code>ch</code>. - <p> + The offset argument must be greater than or equal to <code>0</code>, and less than the length of this string buffer. @@ -324,7 +331,7 @@ public: /** Appends the string to this string buffer. - <p> + The characters of the <code>String</code> argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. @@ -340,7 +347,7 @@ public: /** Appends the string representation of the <code>char</code> array argument to this string buffer. - <p> + The characters of the array argument are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the length of the argument. @@ -356,7 +363,7 @@ public: /** Appends the string representation of the <code>char</code> array argument to this string buffer. - <p> + Characters of the character array <code>str</code> are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of <code>len</code>. @@ -374,7 +381,8 @@ public: /** Appends a 8-Bit ASCII character string to this string buffer. - Since this method is optimized for performance. the ASCII + + 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 127. The ASCII string must be @@ -394,6 +402,7 @@ public: /** Appends a 8-Bit ASCII character string to this string buffer. + 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 @@ -418,7 +427,7 @@ public: /** Appends the string representation of the <code>sal_Bool</code> argument to the string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -435,7 +444,7 @@ public: /** Appends the string representation of the <code>char</code> argument to this string buffer. - <p> + The argument is appended to the contents of this string buffer. The length of this string buffer increases by <code>1</code>. @@ -450,7 +459,7 @@ public: /** Appends the string representation of the <code>sal_Int32</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -467,7 +476,7 @@ public: /** Appends the string representation of the <code>long</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -484,7 +493,7 @@ public: /** Appends the string representation of the <code>float</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -501,7 +510,7 @@ public: /** Appends the string representation of the <code>double</code> argument to this string buffer. - <p> + The argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then appended to this string buffer. @@ -517,7 +526,7 @@ public: /** Inserts the string into this string buffer. - <p> + The characters of the <code>String</code> argument are inserted, in order, into this string buffer at the indicated offset. The length of this string buffer is increased by the length of the argument. @@ -538,7 +547,7 @@ public: /** Inserts the string representation of the <code>char</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -556,7 +565,7 @@ public: /** Inserts the string representation of the <code>char</code> array argument into this string buffer. - <p> + The characters of the array argument are inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by @@ -577,7 +586,7 @@ public: /** Inserts the string representation of the <code>sal_Bool</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -600,7 +609,7 @@ public: /** Inserts the string representation of the <code>char</code> argument into this string buffer. - <p> + The second argument is inserted into the contents of this string buffer at the position indicated by <code>offset</code>. The length of this string buffer increases by one. @@ -621,7 +630,7 @@ public: /** Inserts the string representation of the second <code>sal_Int32</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -645,7 +654,7 @@ public: /** Inserts the string representation of the <code>long</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -669,7 +678,7 @@ public: /** Inserts the string representation of the <code>float</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated @@ -693,7 +702,7 @@ public: /** Inserts the string representation of the <code>double</code> argument into this string buffer. - <p> + The second argument is converted to a string as if by the method <code>String.valueOf</code>, and the characters of that string are then inserted into this string buffer at the indicated diff --git a/sal/inc/rtl/ustring.h b/sal/inc/rtl/ustring.h index 72e0999a0ef1..0865db145c7e 100644 --- a/sal/inc/rtl/ustring.h +++ b/sal/inc/rtl/ustring.h @@ -2,9 +2,9 @@ * * $RCSfile: ustring.h,v $ * - * $Revision: 1.5 $ + * $Revision: 1.6 $ * - * last change: $Author: th $ $Date: 2001-07-27 13:21:46 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -78,760 +78,910 @@ extern "C" { /* ======================================================================= */ -/** - Returns the length of a string. - The length is equal to the number of 16-bit Unicode characters in the - string without the terminating NULL-character. +/** Return the length of a string. - @param str must be a NULL-terminated string. - @return the length of the sequence of characters represented by this - string, excluding the terminating NULL-character. -*/ + The length is equal to the number of 16-bit Unicode characters in the + string, without the terminating NUL character. + + @param str + a null-terminated string. + + @return + the length of the sequence of characters represented by this string, + excluding the terminating NUL character. + */ sal_Int32 SAL_CALL rtl_ustr_getLength( const sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - 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. - Both strings must be NULL-terminated. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated string which is compared - with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings. + + 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. + + @param first + the first null-terminated string to be compared. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_compare( const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_compare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param secondLen + the length of the second string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_shortenedCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - 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. - The string length must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with - the first param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings from back to front. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_reverseCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both strings must be NULL-terminated. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated string which is compared - with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + @param first + the first null-terminated string to be compared. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase( const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings with a maximum count - of characters for each string. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the - first param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings with a maximum count - of characters for each string. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both string lengths must be equal or greater as there given length. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second string which is compared with the first - param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters, ignoring the case + of ASCII characters. + + 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. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param 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. + + @param secondLen + the length of the second string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - 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. - Both strings must be NULL-terminated. - 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 - 127. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated ASCII string which - is compared with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first null-terminated string to be compared. + + @param second + the second null-terminated ASCII string which is compared with the first + one. + + @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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_compare( const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - The string length must be equal or greater as there given length. - 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 - 127. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second ASCII string which is compared with - the first param. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param second + the second null-terminated ASCII string which is compared with the first + one. + + @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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_compare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Compares two strings with a maximum count of characters for each string. - 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. - Both string lengths must be equal or greater as there given length. - 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 - 127. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second ASCII string which is compared with - the first param. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param second + the second null-terminated ASCII string which is compared with the first + one. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - 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. - The string length must be equal or greater as there given length. - 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 - 127. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second ASCII string which is compared with - the first param. - @param secondLen the length of the second string or the number of - characters to compared. The second string length - must be greater or equal than this value. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings from back to front. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param second + the second ASCII string which is compared with the first one. Need not be + null-terminated, but must be at least as long as the specified secondLen. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_asciil_reverseCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both strings must be NULL-terminated. - 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 - 127. - - @param first the first NULL-terminated string to be compared. - @param second the second NULL-terminated ASCII string which - is compared with the first param. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if the first string is less than the second string - <code>> 0</code> - if the first string is greater than the second string -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first null-terminated string to be compared. + + @param second + the second null-terminated ASCII 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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase( const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - The string length must be equal or greater as there given length. - 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 - 127. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second ASCII string which is compared with - the first param. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings, ignoring the case of ASCII characters. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param second + the second null-terminated ASCII 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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C(); -/** - Perform a ASCII lowercase comparison of two strings with a maximum count - of characters for each string. - The comparison is based on the numeric value of each character in - the strings and return 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 can't be used for language specific sorting. - Both string lengths must be equal or greater as there given length. - 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 - 127. - - @param first the first string to be compared. - @param firstLen the length of the first string or the number of - characters to compared. The first string length - must be greater or equal than this value. - @param second the second ASCII string which is compared with - the first param. - @param shortenedLen the number of characters which should be compared. - This length can be longer, shorter or equal than - the both other strings. - @return <code>0</code> - if both substrings are equal - <code>< 0</code> - if the first substring is less than the second substring - <code>> 0</code> - if the first substring is greater than the second substring -*/ +/** Compare two strings with a maximum count of characters, ignoring the case + of ASCII characters. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param first + the first string to be compared. Need not be null-terminated, but must be + at least as long as the specified firstLen. + + @param firstLen + the length of the first string. + + @param second + the second null-terminated ASCII string which is compared with the first + one. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C(); -/** - Returns a hashcode for a string. - It is not allowed to store the hash code, because newer versions - could return other hashcodes. - The string must be NULL-terminated. +/** Return a hash code for a string. - @param str a NULL-terminated string. - @return a hash code value for str. -*/ + It is not allowed to store the hash code persistently, because later + versions could return other hash codes. The string must be + null-terminated. + + @param str + a null-terminated string. + + @return + a hash code for the given string. + */ sal_Int32 SAL_CALL rtl_ustr_hashCode( const sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - Returns a hashcode for a substring. - It is not allowed to store the hash code, because newer versions - could return other hashcodes. +/** Return a hash code for a string. - @param str a string. - @param len the maximum number of characters for creating the - hashcode. The string length must be greater or equal - than this value. - @return a hash code value for str. -*/ + It is not allowed to store the hash code persistently, because later + versions could return other hash codes. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @return + a hash code for the given string. + */ sal_Int32 SAL_CALL rtl_ustr_hashCode_WithLength( const sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified character. - The string must be NULL-terminated. +/** Search for the first occurrence of a character within a string. - @param str a NULL-terminated string. - @param ch character to be located. - @return the index of the first occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. -*/ + The string must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_indexOfChar( const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the substring of the first occurrence of the - specified character. - The string length must be greater or equal as the given len. - - @param str a substring. - @param len the maximum number of characters. The string length - must be greater or equal than this value. - @param ch character to be located. - @return the index of the first occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. -*/ +/** Search for the first occurrence of a character within a string. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_indexOfChar_WithLength( const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of the - specified character, searching backward starting at the end. - The string must be NULL-terminated. - - @param str a NULL-terminated string. - @param ch character to be located. - @return the index of the last occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. - The return value is always lower as the string len. -*/ +/** Search for the last occurrence of a character within a string. + + The string must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar( const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of the - specified character, searching backward starting at the specified - index (excluding the character at the specified index). - - @param str a substring. - @param len the starting index. The string length - must be greater or equal than this value. - @param ch character to be located. - @return the index of the last occurrence of the character in the - character sequence represented by the string, or - <code>-1</code> if the character does not occur. - The return value is always lower as the len param. -*/ +/** Search for the last occurrence of a character within a string. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar_WithLength( const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified substring. - If subStr doesn't include any character, always <code>-1</code> is - returned. This is also the case, if both strings are empty. - Both strings must be NULL-terminated. - - @param str a NULL-terminated string. - @param subStr a NULL-terminated substring to be searched for. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the first - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. -*/ +/** Search for the first occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + Both strings must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_indexOfStr( const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the first occurrence of the - specified substring. - If subLen is zero, always <code>-1</code> is returned. This is also - the case, if str is also zero. - Both string lengths must be equal or greater as there given length. - - @param str a string. - @param len the length of the string or the number of - characters to compared. The string length - must be greater or equal than this value. - @param subStr a substring to be searched for. - @param subLen the length of the substring or the number of - characters to compared. The substring length - must be greater or equal than this value. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the first - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. -*/ +/** Search for the first occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param subStr + the substring to be searched for. Need not be null-terminated, but must + be at least as long as the specified subLen. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_indexOfStr_WithLength( const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of - the specified substring, searching backward. - The returned index indicates the starting index of the substring. - If subStr doesn't include any character, always <code>-1</code> is - returned. This is also the case, if both strings are empty. - Both strings must be NULL-terminated. - - @param str a NULL-terminated string. - @param subStr a NULL-terminated substring to be searched for. - @return if the string argument occurs as a substring within the - string, then the index of the first character of the last - such substring is returned; if it does not occur as a - substring, <code>-1</code> is returned. The return value is - always lower as the string len. -*/ +/** Search for the last occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + Both strings must be null-terminated. + + @param str + a null-terminated string. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr( const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns the index within the string of the last occurrence of - the specified substring, searching backward starting at the specified - index (excluding the character at the specified index). - The returned index indicates the starting index of the substring. - If subLen is zero, always <code>-1</code> is returned. This is also - the case, if str is also zero. - Both string lengths must be equal or greater as there given length. - - @param str a string. - @param len the length of the string or the number of - characters to compared. The string length - must be greater or equal than this value. - @param subStr a substring to be searched for. - @param subLen the length of the substring or the number of - characters to compared. The substring length - must be greater or equal than this value. - @return If the string argument occurs one or more times as a substring - within the string, then the index of the first character of - the last such substring is returned. If it does not occur as a - substring <code>-1</code> is returned. The return value is - always lower as the len param. -*/ +/** Search for the last occurrence of a substring within a string. + + If subStr is empty, or both str and subStr are empty, -1 is returned. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param subStr + the substring to be searched for. Need not be null-terminated, but must + be at least as long as the specified subLen. + + @param 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. + */ sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr_WithLength( const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C(); -/** - Replaces all occurrences of oldChar in the string with newChar. - If the character oldChar does not occur in the character sequence - represented by the string, then the string is not modified. - The string must be NULL-terminated. +/** Replace all occurrences of a single character within a string. - @param str a NULL-terminated string. - @param oldChar the old character. - @param newChar the new character. -*/ + If oldChar does not occur within str, then the string is not modified. + The string must be null-terminated. + + @param str + a null-terminated string. + + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_ustr_replaceChar( sal_Unicode * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); -/** - Replaces all occurrences of oldChar in the string with newChar. - If the character oldChar does not occur in the character sequence - represented by the string, then the string is not modified. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to replaced. The string length - must be greater or equal than this value. - @param oldChar the old character. - @param newChar the new character. -*/ +/** Replace all occurrences of a single character within a string. + + If oldChar does not occur within str, then the string is not modified. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_ustr_replaceChar_WithLength( sal_Unicode * str, sal_Int32 len, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII uppercase characters (65-90) in the string to - ASCII lowercase characters (97-122). - This function can't be used for language specific conversion. - The string length must be greater or equal as the given len. +/** Convert all ASCII uppercase letters to lowercase within a string. - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. -*/ + 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. + + @param str + a null-terminated string. + */ +void SAL_CALL rtl_ustr_toAsciiLowerCase( sal_Unicode * str ) SAL_THROW_EXTERN_C(); + +/** Convert all ASCII uppercase letters to lowercase within a string. + + The characters with values between 65 and 90 (ASCII A--Z) are replaced + with values between 97 and 122 (ASCII a--z). + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + */ void SAL_CALL rtl_ustr_toAsciiLowerCase_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Convert all ASCII lowercase letters to uppercase within a string. - @param str a NULL-terminated string. -*/ + 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. + + @param str + a null-terminated string. + */ void SAL_CALL rtl_ustr_toAsciiUpperCase( sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - Converts all ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - The string length must be greater or equal as the given len. +/** Convert all ASCII lowercase letters to uppercase within a string. - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. -*/ + The characters with values between 97 and 122 (ASCII a--z) are replaced + with values between 65 and 90 (ASCII A--Z). + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the length of the string. + */ void SAL_CALL rtl_ustr_toAsciiUpperCase_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Removes white space from both ends of the string. - All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - Also the Unicode space characters between 0x2000 and 0x200B, - 0x2028 (LINE SEPARATOR) and 0x2029 (PARAGRAPH SEPARATOR) are - considered to be white space. - The string must be NULL-terminated. - - @param str a NULL-terminated string. - @return new length of the string. -*/ +/** Remove white space from both ends of a string. + + 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. + + @param str + a null-terminated string. + + @return + the new length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_trim( sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - Removes white space from both ends of the string. - All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - Also the Unicode space characters between 0x2000 and 0x200B, - 0x2028 (LINE SEPARATOR) and 0x2029 (PARAGRAPH SEPARATOR) are - considered to be white space. - The string length must be greater or equal as the given len. - - @param str a string. - @param len the length of the string or the number of - characters to converted. The string length - must be greater or equal than this value. - @return new length of the string. -*/ +/** Remove white space from both ends of the string. + + 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. + + @param str + a string. Need not be null-terminated, but must be at least as long as + the specified len. + + @param len + the original length of the string. + + @return + the new length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_trim_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Returns the string representation of the sal_Bool argument. - If the sal_Bool is true, the buffer is filled with the - string "true" and 5 is returned. - If the sal_Bool is false, the buffer is filled with the - string "false" and 6 is returned. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFBOOLEAN - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param b a sal_Bool. - @return the length of the string. -*/ +/** Create the string representation of a boolean. + + 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. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFBOOLEAN define to + create a buffer that is big enough. + + @param b + a boolean value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfBoolean( sal_Unicode * str, sal_Bool b ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MAX_VALUEOFBOOLEAN RTL_STR_MAX_VALUEOFBOOLEAN -/** - Returns the string representation of the char argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFCHAR - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param ch a char. - @return the length of the string. -*/ +/** Create the string representation of a character. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFCHAR define to create a + buffer that is big enough. + + @param ch + a character value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfChar( sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MAX_VALUEOFCHAR RTL_STR_MAX_VALUEOFCHAR -/** - Returns the string representation of the int argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFINT32 - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param i a int32. - @param radix the radix (between 2 and 36) - @return the length of the string. -*/ +/** Create the string representation of an integer. + + This function cannot be used for language-specific operations. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFINT32 define to create + a buffer that is big enough. + + @param i + an integer value. + + @param radix + the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX + (36), inclusive. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfInt32( sal_Unicode * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MIN_RADIX RTL_STR_MIN_RADIX #define RTL_USTR_MAX_RADIX RTL_STR_MAX_RADIX #define RTL_USTR_MAX_VALUEOFINT32 RTL_STR_MAX_VALUEOFINT32 -/** - Returns the string representation of the long argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFINT64 - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param l a int64. - @param radix the radix (between 2 and 36) - @return the length of the string. -*/ +/** Create the string representation of a long integer. + + This function cannot be used for language-specific operations. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFINT64 define to create + a buffer that is big enough. + + @param l + a long integer value. + + @param radix + the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX + (36), inclusive. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfInt64( sal_Unicode * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64 -/** - Returns the string representation of the float argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFFLOAT - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param f a float. - @return the length of the string. -*/ +/** Create the string representation of a float. + + This function cannot be used for language-specific conversion. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFFLOAT define to create + a buffer that is big enough. + + @param f + a float value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfFloat( sal_Unicode * str, float f ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MAX_VALUEOFFLOAT RTL_STR_MAX_VALUEOFFLOAT -/** - Returns the string representation of the double argument. - This function can't be used for language specific conversion. - - @param str a buffer, which is big enough to hold the result - and the terminating NULL-character. - You should use the RTL_USTR_MAX_VALUEOFDOUBLE - define to create a buffer, which is big enough. - It defines the maximum number of characters - with the terminating NULL-character. - @param d a double. - @return the length of the string. -*/ +/** Create the string representation of a double. + + This function cannot be used for language-specific conversion. + + @param str + a buffer that is big enough to hold the result and the terminating NUL + character. You should use the RTL_USTR_MAX_VALUEOFDOUBLE define to create + a buffer that is big enough. + + @param d + a double value. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_ustr_valueOfDouble( sal_Unicode * str, double d ) SAL_THROW_EXTERN_C(); #define RTL_USTR_MAX_VALUEOFDOUBLE RTL_STR_MAX_VALUEOFDOUBLE -/** - Returns the Boolean value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a boolean. - @param str a NULL-terminated string. - @return sal_True, if the string is 1 or "True" in any ASCII case. - sal_False in any other case. -*/ + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. + + @return + true if the string is "1" or "true" in any ASCII case, false otherwise. + */ sal_Bool SAL_CALL rtl_ustr_toBoolean( const sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - Returns the int32 value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as an integer. - @param str a NULL-terminated string. - @param radix the radix (between 2 and 36) - @return the int32 represented by the string. - 0 if the string represents no number. -*/ + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. + + @param radix + the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX + (36), inclusive. + + @return + the integer value represented by the string, or 0 if the string does not + represent an integer. + */ sal_Int32 SAL_CALL rtl_ustr_toInt32( const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); -/** - Returns the int64 value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a long integer. - @param str a NULL-terminated string. - @param radix the radix (between 2 and 36) - @return the int64 represented by the string. - 0 if the string represents no number. -*/ + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. + + @param radix + the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX + (36), inclusive. + + @return + the long integer value represented by the string, or 0 if the string does + not represent a long integer. + */ sal_Int64 SAL_CALL rtl_ustr_toInt64( const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C(); -/** - Returns the float value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a float. - @param str a NULL-terminated string. - @return the float represented by the string. - 0.0 if the string represents no number. -*/ + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. + + @return + the float value represented by the string, or 0.0 if the string does not + represent a float. + */ float SAL_CALL rtl_ustr_toFloat( const sal_Unicode * str ) SAL_THROW_EXTERN_C(); -/** - Returns the double value from the given string. - This function can't be used for language specific conversion. - The string must be NULL-terminated. +/** Interpret a string as a double. - @param str a NULL-terminated string. - @return the double represented by the string. - 0.0 if the string represents no number. -*/ + This function cannot be used for language-specific conversion. The string + must be null-terminated. + + @param str + a null-terminated string. + + @return + the float value represented by the string, or 0.0 if the string does not + represent a double. + */ double SAL_CALL rtl_ustr_toDouble( const sal_Unicode * str ) SAL_THROW_EXTERN_C(); /* ======================================================================= */ @@ -842,8 +992,9 @@ double SAL_CALL rtl_ustr_toDouble( const sal_Unicode * str ) SAL_THROW_EXTERN_C( #pragma pack(1) #endif -/** - The implementation structure of a unicode string. +/** The implementation of a Unicode string. + + @internal */ typedef struct _rtl_uString { @@ -860,286 +1011,341 @@ typedef struct _rtl_uString /* ----------------------------------------------------------------------- */ -/** - Increment the reference count of the string. +/** Increment the reference count of a string. - @param str the string. -*/ + @param str + a string. + */ void SAL_CALL rtl_uString_acquire( rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Decrement the reference count of the string. If the count goes - to zero than the string data is deleted. +/** Decrement the reference count of a string. - @param str the string. -*/ + If the count goes to zero than the string data is deleted. + + @param str + a string. + */ void SAL_CALL rtl_uString_release( rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string containing no characters. +/** Allocate a new string containing no characters. - @param newStr pointer to the new string. The data must be 0 or - a valid string. -*/ + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + */ void SAL_CALL rtl_uString_new( rtl_uString ** newStr ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string containing space for the given - numbers of characters. - The reference count of the new string is 1 or an empty string. - The values of all characters are set to 0 and the length of the - string is 0, only data is allocated for holding characters. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param len number of characters. -*/ +/** Allocate a new string containing space for a given number of characters. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param len + the number of characters. + */ void SAL_CALL rtl_uString_new_WithLength( rtl_uString ** newStr, sal_Int32 nLen ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains the same sequence of - characters as the string argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". +/** Allocate a new string that contains a copy of another string. - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a valid string. -*/ + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a valid string. + */ void SAL_CALL rtl_uString_newFromString( rtl_uString ** newStr, const rtl_uString * value ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains the same sequence of - characters contained in the character array argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". +/** Allocate a new string that contains a copy of a character array. - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a NULL-terminated character array. -*/ + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a null-terminated character array. + */ void SAL_CALL rtl_uString_newFromStr( rtl_uString ** newStr, const sal_Unicode * value ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains characters from - the character array argument. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a character array. - @param len the number of character which should be copied. - The character array length must be greater or - equal than this value. -*/ +/** Allocate a new string that contains a copy of a character array. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a character array. Need not be null-terminated, but must be at least as + long as the specified len. + + @param len + the length of the character array. + */ void SAL_CALL rtl_uString_newFromStr_WithLength( rtl_uString ** newStr, const sal_Unicode * value, sal_Int32 len ) SAL_THROW_EXTERN_C(); -/** - Allocates a new string that contains the same sequence of - characters contained in the character array argument without - conversion. - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param value a NULL-terminated ASCII character array. -*/ +/** Allocate a new string that contains a copy of a character array. + + 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. + + Since this function 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 of 0 and 127, inclusive. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param value + a null-terminated ASCII character array. + */ void SAL_CALL rtl_uString_newFromAscii( rtl_uString ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C(); -/** - Assign rightValue to *str. Release *str and aquire rightValue! +/** Assign a new value to a string. - @param str pointer to the string. The data must be 0 or - a valid string. - @param rightValue a valid string. -*/ + First releases any value str might currently hold, then acquires + rightValue. + + @param str + pointer to the string. The pointed-to data must be null or a valid + string. + + @param rightValue + a valid string. + */ void SAL_CALL rtl_uString_assign( rtl_uString ** str, rtl_uString * rightValue ) SAL_THROW_EXTERN_C(); -/** - Returns the length of this string. - The length is equal to the number of characters in the string. +/** Return the length of a string. - @param str a valid string. - @return the length of the sequence of characters represented by the - string. -*/ + The length is equal to the number of characters in the string. + + @param str + a valid string. + + @return + the length of the string. + */ sal_Int32 SAL_CALL rtl_uString_getLength( const rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Returns the pointer to the character array of the string. +/** Return a pointer to the underlying character array of a string. - @param str pointer to the string. The data must be - a valid string. - @return a null terminated character array. -*/ + @param str + a valid string. + + @return + a pointer to the null-terminated character array. + */ sal_Unicode * SAL_CALL rtl_uString_getStr( rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Concatenates the right string to the end of the left string and - returns the result in a new instance. - The new instance isn't in every case a new instance (for example, - if one or both strings are empty). The new string object could - be a shared instance and can't be modified without checking the - refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param left a valid string. - @param right a valid string. -*/ +/** Create a new string that is the concatenation of two other strings. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param left + a valid string. + + @param right + a valid string. + */ void SAL_CALL rtl_uString_newConcat( rtl_uString ** newStr, rtl_uString * left, rtl_uString * right ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from replacing a number of characters (count) - from the specified position (index) in the string (str) and inserting - the string (subStr) at the specified position (index). - If subStr is 0, than only a number of characters (count) are deleted - at the specified position (index). - The new instance isn't in every case a new instance. The new string - object could be a shared instance and can't be modified without - checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param index the replacing index in str. - The index must be greater or equal as 0 and - less or equal as the length of the string. - @param count the count of charcters that will replaced - The count must be greater or equal as 0 and - less or equal as the length of the string minus index. - @param subStr 0 or a valid string, which is inserted at nIndex. - If subStr is 0, only a number of characters (count) - are deleted at the specified position (index). -*/ +/** Create a new string by replacing a substring of another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param index + the index into str at which to start replacement. Must be between 0 and + the length of str, inclusive. + + @param 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. + + @param subStr + either null or a valid string to be inserted. + */ void SAL_CALL rtl_uString_newReplaceStrAt( rtl_uString ** newStr, rtl_uString * str, sal_Int32 index, sal_Int32 count, rtl_uString * subStr ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from replacing all occurrences of - oldChar in this string with newChar. - If the character oldChar does not occur in the character sequence - represented by this object, then the string is assigned with - str. The new instance isn't in every case a new instance. The new - string object could be a shared instance and can't be modified without - checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param oldChar the old character. - @param newChar the new character. -*/ +/** Create a new string by replacing all occurrences of a single character + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param oldChar + the old character. + + @param newChar + the new character. + */ void SAL_CALL rtl_uString_newReplace( rtl_uString ** newStr, rtl_uString * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from converting all - ASCII uppercase characters (65-90) in the string to - ASCII lowercase characters (97-122). - This function can't be used for language specific conversion. - If the string doesn't contain characters which must be converted, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. -*/ +/** Create a new string by converting all ASCII uppercase letters to lowercase + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + */ void SAL_CALL rtl_uString_newToAsciiLowerCase( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from converting all - ASCII lowercase characters (97-122) in the string to - ASCII uppercase characters (65-90). - This function can't be used for language specific conversion. - If the string doesn't contain characters which must be converted, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. +/** Create a new string by converting all ASCII lowercase letters to uppercase + within another string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. */ void SAL_CALL rtl_uString_newToAsciiUpperCase( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string resulting from removing white space from both ends - of the string. - All characters that have codes less than or equal to - 32 (the space character) are considered to be white space. - Also the Unicode space characters between 0x2000 and 0x200B, - 0x2028 (LINE SEPARATOR) and 0x2029 (PARAGRAPH SEPARATOR) are - considered to be white space. - If the string doesn't contain white spaces at both ends, - then the new string is assigned with str. The new instance isn't - in every case a new instance. The new string object could be a shared - instance and can't be modified without checking the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. -*/ +/** Create a new string by removing white space from both ends of another + string. + + 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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + */ void SAL_CALL rtl_uString_newTrim( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C(); -/** - Returns a new string for the token specified by nToken. If nToken is - greater than the last possible Token then the result is an empty string. - The return value is the position of the next token or -1, if the queried - token is the last one. - Example: - rtl_uString* pToken = 0; - sal_Int32 nIndex = 0; - do - { - ... - nIndex = rtl_uString_getToken( &pToken, pStr, 0, ';', nIndex ); - ... - } - while ( nIndex >= 0 ); - The new instance isn't in every case a new instance. The new string - object could be a shared instance and can't be modified without checking - the refercence count. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a valid string. - @param token the number of the token to return. The number - must be greater or equal as 0. - @param cTok the character which seperate the tokens. - @param index the position at which the token is searched in the - string. - The index must be greater or equal as 0 and - less or equal as the length of the string. - @return the index of the next token or -1, if the current token is - the last one -*/ +/** Create a new string by extracting a single token from another string. + + 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_uString * pToken = NULL; + sal_Int32 nIndex = 0; + do + { + ... + nIndex = rtl_uString_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. + + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a valid string. + + @param token + the number of the token to return, starting at index. Must be + non-negative. + + @param cTok + the character that seperates the tokens. + + @param index + the position at which searching for the token starts. Must be between 0 + and the length of str, inclusive. + + @return + the index of the next token, or -1 if no more tokens follow. + */ sal_Int32 SAL_CALL rtl_uString_getToken( rtl_uString ** newStr , rtl_uString * str, sal_Int32 token, sal_Unicode cTok, sal_Int32 index ) SAL_THROW_EXTERN_C(); /* ======================================================================= */ +/* constAsciiStr must be a "..." or char const aFoo[] = "..." */ +#define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) constAsciiStr, sizeof( constAsciiStr )-1, RTL_TEXTENCODING_ASCII_US + +/* ======================================================================= */ + /* predefined constants for String-Conversion */ #define OSTRING_TO_OUSTRING_CVTFLAGS (RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_MAPTOPRIVATE |\ RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_DEFAULT |\ @@ -1147,39 +1353,40 @@ sal_Int32 SAL_CALL rtl_uString_getToken( rtl_uString ** newStr , rtl_uString * s /* ----------------------------------------------------------------------- */ -/** - Allocates a new Unicode string from a seequence of bytes and convert - the byte sequence to Unicode with the specified text encoding. - The string length could be a different one as the specified length, - because not all text conversions result in the same unicode length - (for example double byte encodings, UTF-7, UTF-8, ...). - The reference count of the new string is 1 or an empty string. - This function doesn't handle "Out of Memory" or other - "bad memory allocations". - - @param newStr pointer to the new string. The data must be 0 or - a valid string. - @param str a byte array. - @param len the number of character which should be converted. - The byte array length must be greater or - equal than this value. - @param encoding the text encoding from the byte array. - @param convertFlags flags which controls the conversion. - see RTL_TEXTTOUNICODE_FLAGS_... -*/ -void SAL_CALL rtl_string2UString( rtl_uString ** newStr, const sal_Char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C(); +/** Create a new Unicode string by converting a byte string, using a specific + text encoding. -/* ======================================================================= */ + The lengths of the byte string and the Unicode string may differ (e.g., + for double-byte encodings, UTF-7, UTF-8). -/* constAsciiStr must be a "..." or char const aFoo[] = "..." */ -#define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) constAsciiStr, sizeof( constAsciiStr )-1, RTL_TEXTENCODING_ASCII_US + If the length of the byte string is greater than zero, the reference count + of the new string will be 1. This function does not handle out-of-memory + conditions. -/* ======================================================================= */ + @param newStr + pointer to the new string. The pointed-to data must be null or a valid + string. + + @param str + a byte character array. Need not be null-terminated, but must be at + least as long as the specified len. + + @param len + the length of the byte character array. + + @param encoding + the text encoding to use for conversion. + + @param convertFlags + flags which control the conversion. Either use + OSTRING_TO_OUSTRING_CVTFLAGS, or see + <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more + details. + */ +void SAL_CALL rtl_string2UString( rtl_uString ** newStr, const sal_Char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C(); #ifdef __cplusplus } #endif #endif /* _RTL_USTRING_H_ */ - - diff --git a/sal/inc/rtl/ustring.hxx b/sal/inc/rtl/ustring.hxx index 6fc8a9d26555..6e183396967b 100644 --- a/sal/inc/rtl/ustring.hxx +++ b/sal/inc/rtl/ustring.hxx @@ -2,9 +2,9 @@ * * $RCSfile: ustring.hxx,v $ * - * $Revision: 1.9 $ + * $Revision: 1.10 $ * - * last change: $Author: hr $ $Date: 2001-09-11 13:07:14 $ + * last change: $Author: sb $ $Date: 2001-10-30 13:41:07 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -86,7 +86,7 @@ namespace rtl handle all the memory managament for you - and it do it more efficient. 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 change the string. This class + memory allocation) as long as you do not change the string. This class stores also the length of the string, so that many operations are faster as the C-str-functions. @@ -109,10 +109,14 @@ class OUString friend class ::String; public: + /** @internal */ rtl_uString * pData; private: + /** @internal */ class DO_NOT_ACQUIRE; + + /** @internal */ OUString( rtl_uString * value, DO_NOT_ACQUIRE * ) { pData = value; @@ -195,6 +199,11 @@ public: rtl_string2UString( &pData, value, length, encoding, convertFlags ); } + /** Convert a String (from the tools module) into an OUString. + + Since both String and OUString internally use the same data structure, + this is a very cheap operation. + */ OUString( const String & value ) SAL_THROW(()); /** @@ -229,6 +238,7 @@ public: /** Returns the length of this string. + The length is equal to the number of Unicode characters in this string. @return the length of the sequence of characters represented by this @@ -238,6 +248,7 @@ public: /** Returns a pointer to the Unicode character buffer from this string. + It isn't necessarily NULL terminated. @return a pointer to the Unicode characters buffer from this object. @@ -246,6 +257,7 @@ public: /** Returns a pointer to the Unicode character buffer from this string. + It isn't necessarily NULL terminated. @return a pointer to the Unicode characters buffer from this object. @@ -254,14 +266,15 @@ public: /** 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. @param str the object to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareTo( const OUString & str ) const SAL_THROW(()) { @@ -271,15 +284,16 @@ public: /** Compares two strings with an 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. @param str the object to be compared. @param maxLength the maximum count of characters to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareTo( const OUString & str, sal_Int32 maxLength ) const SAL_THROW(()) { @@ -289,14 +303,15 @@ public: /** 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. @param str the object to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 reverseCompareTo( const OUString & str ) const SAL_THROW(()) { @@ -306,6 +321,7 @@ public: /** 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. @@ -326,6 +342,7 @@ public: /** 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. @@ -349,6 +366,7 @@ public: /** Perform a comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -370,6 +388,7 @@ public: /** Perform a ASCII lowercase comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -394,6 +413,7 @@ public: /** 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 @@ -403,9 +423,9 @@ public: This function can't be used for language specific sorting. @param asciiStr the 8-Bit ASCII character string to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareToAscii( const sal_Char* asciiStr ) const SAL_THROW(()) { @@ -414,6 +434,7 @@ public: /** Compares two strings with an 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. Since this method is optimized for performance, the ASCII character @@ -424,9 +445,9 @@ public: @param asciiStr the 8-Bit ASCII character string to be compared. @param maxLength the maximum count of characters to be compared. - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 compareToAscii( const sal_Char * asciiStr, sal_Int32 maxLength ) const SAL_THROW(()) { @@ -435,10 +456,11 @@ public: } /** - Compares two strings in reverse order. This could be useful, - if normally both strings start with the same content. - The comparison is based on the numeric value of each character in - the strings and return a value indicating their relationship. + Compares two strings in reverse order. + + This could be useful, if normally both strings start with the same + content. 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 @@ -448,9 +470,9 @@ public: @param asciiStr the 8-Bit ASCII character string to be compared. @param asciiStrLength the length of the ascii string - @return <code>0</code> - if both strings are equal - <code>< 0</code> - if this string is less than the string argument - <code>> 0</code> - if this string is greater than the string argument + @return 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 reverseCompareToAsciiL( const sal_Char * asciiStr, sal_Int32 asciiStrLength ) const SAL_THROW(()) { @@ -460,6 +482,7 @@ public: /** 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. Since this method is optimized for performance, the ASCII character @@ -480,6 +503,7 @@ public: /** 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. Since this method is optimized for performance, the ASCII character @@ -505,6 +529,7 @@ public: /** 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. @@ -527,6 +552,7 @@ public: /** 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. @@ -554,6 +580,7 @@ public: /** Perform a comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -580,6 +607,7 @@ public: /** Perform a ASCII lowercase comparison of a substring in this string. + The result is true if and only if second string represents the same sequence of characters in the first string at the given position. @@ -651,7 +679,7 @@ public: @return the index of the first occurrence of the character in the character sequence represented by this string that is greater than or equal to fromIndex, or - <code>-1</code> if the character does not occur. + -1 if the character does not occur. */ sal_Int32 indexOf( sal_Unicode ch, sal_Int32 fromIndex = 0 ) const SAL_THROW(()) { @@ -666,7 +694,7 @@ public: @param ch character to be located. @return the index of the last occurrence of the character in the character sequence represented by this string, or - <code>-1</code> if the character does not occur. + -1 if the character does not occur. */ sal_Int32 lastIndexOf( sal_Unicode ch ) const SAL_THROW(()) { @@ -680,7 +708,7 @@ public: @param ch character to be located. @return the index of the last occurrence of the character in the character sequence represented by this string that - is less or than or equal to fromIndex, or <code>-1</code> + is less or than or equal to fromIndex, or -1 if the character does not occur before that point. */ sal_Int32 lastIndexOf( sal_Unicode ch, sal_Int32 fromIndex ) const SAL_THROW(()) @@ -691,7 +719,8 @@ public: /** Returns the index within this string of the first occurrence of the specified substring, starting at the specified index. - If str doesn't include any character, always <code>-1</code> is + + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @@ -700,7 +729,7 @@ public: within this string at the starting index, then the index of the first character of the first such substring is returned. If it does not occur as a substring starting - at fromIndex or beyond, <code>-1</code> is returned. + at fromIndex or beyond, -1 is returned. */ sal_Int32 indexOf( const OUString & str, sal_Int32 fromIndex = 0 ) const SAL_THROW(()) { @@ -712,16 +741,17 @@ public: /** Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end. + The returned index indicates the starting index of the substring in this string. - If str doesn't include any character, always <code>-1</code> is + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @return If the string argument occurs one or more times as a substring within this string, then the index of the first character of the last such substring is returned. If it does not occur as - a substring, <code>-1</code> is returned. + a substring, -1 is returned. */ sal_Int32 lastIndexOf( const OUString & str ) const SAL_THROW(()) { @@ -732,9 +762,10 @@ public: /** Returns the index within this string of the last occurrence of the specified substring, searching backward starting at the end. + The returned index indicates the starting index of the substring in this string. - If str doesn't include any character, always <code>-1</code> is + If str doesn't include any character, always -1 is returned. This is also the case, if both strings are empty. @param str the substring to search for. @@ -743,7 +774,7 @@ public: within this string at the starting index, then the index of the first character of the last such substring is returned. If it does not occur as a substring starting - at fromIndex or earlier, <code>-1</code> is returned. + at fromIndex or earlier, -1 is returned. */ sal_Int32 lastIndexOf( const OUString & str, sal_Int32 fromIndex ) const SAL_THROW(()) { @@ -752,8 +783,9 @@ public: } /** - Returns a new string that is a substring of this string. The - substring begins at the specified beginIndex. + Returns a new string that is a substring of this string. + + The substring begins at the specified beginIndex. @param beginIndex the beginning index, inclusive. @return the specified substring. @@ -771,8 +803,9 @@ public: } /** - Returns a new string that is a substring of this string. The - substring begins at the specified beginIndex and + Returns a new string that is a substring of this string. + + The substring begins at the specified beginIndex and extends to the character at index endIndex - 1. @param beginIndex the beginning index, inclusive. @@ -834,6 +867,7 @@ public: /** Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar. + If the character oldChar does not occur in the character sequence represented by this object, then the string is assigned with str. @@ -853,6 +887,7 @@ public: /** Converts from this string all ASCII uppercase characters (65-90) to ASCII lowercase characters (97-122). + This function can't be used for language specific conversion. If the string doesn't contain characters which must be converted, then the new string is assigned with str. @@ -869,6 +904,7 @@ public: /** Converts from this string all ASCII lowercase characters (97-122) to ASCII uppercase characters (65-90). + This function can't be used for language specific conversion. If the string doesn't contain characters which must be converted, then the new string is assigned with str. @@ -884,7 +920,9 @@ public: /** Returns a new string resulting from removing white space from both ends - of the string. All characters that have codes less than or equal to + of the string. + + All characters that have codes less than or equal to 32 (the space character) are considered to be white space. If the string doesn't contain white spaces at both ends, then the new string is assigned with str. @@ -931,6 +969,7 @@ public: /** Returns the Boolean value from this string. + This function can't be used for language specific conversion. @return sal_True, if the string is 1 or "True" in any ASCII case. @@ -954,6 +993,7 @@ public: /** Returns the int32 value from this string. + This function can't be used for language specific conversion. @param radix the radix (between 2 and 36) @@ -967,6 +1007,7 @@ public: /** Returns the int64 value from this string. + This function can't be used for language specific conversion. @param radix the radix (between 2 and 36) @@ -980,6 +1021,7 @@ public: /** Returns the float value from this string. + This function can't be used for language specific conversion. @return the float represented from this string. @@ -992,6 +1034,7 @@ public: /** Returns the double value from this string. + This function can't be used for language specific conversion. @return the double represented from this string. @@ -1004,6 +1047,7 @@ public: /** Returns the string representation of the sal_Bool argument. + If the sal_Bool is true, the string "true" is returned. If the sal_Bool is false, the string "false" is returned. This function can't be used for language specific conversion. @@ -1032,6 +1076,7 @@ public: /** Returns the string representation of the int argument. + This function can't be used for language specific conversion. @param i a int32. @@ -1048,6 +1093,7 @@ public: /** Returns the string representation of the long argument. + This function can't be used for language specific conversion. @param l a int64. @@ -1064,6 +1110,7 @@ public: /** Returns the string representation of the float argument. + This function can't be used for language specific conversion. @param f a float. @@ -1079,6 +1126,7 @@ public: /** Returns the string representation of the double argument. + This function can't be used for language specific conversion. @param d a double. @@ -1095,6 +1143,7 @@ public: /** Returns a OUString copied without conversion from an ASCII character string. + 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 @@ -1113,14 +1162,45 @@ public: /* ======================================================================= */ +/** A helper to use OUStrings with hash maps. + + Instances of this class are unary function objects that can be used as + hash function arguments to STLPort's hash_map and similar constructs. + */ struct OUStringHash { + /** Compute a hash code for a string. + + @param rString + a string. + + @return + a hash code for the string. This hash code should not be stored + persistently, as its computation may change in later revisions. + */ size_t operator()(const rtl::OUString& rString) const { return (size_t)rString.hashCode(); } }; /* ======================================================================= */ +/** Convert an OString to an OUString, using a specific text encoding. + + The lengths of the two strings may differ (e.g., for double-byte + encodings, UTF-7, UTF-8). + + @param rStr + an OString to convert. + + @param encoding + the text encoding to use for conversion. + + @param convertFlags + flags which control the conversion. Either use + OSTRING_TO_OUSTRING_CVTFLAGS, or see + <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more + details. + */ inline OUString OStringToOUString( const OString & rStr, rtl_TextEncoding encoding, sal_uInt32 convertFlags = OSTRING_TO_OUSTRING_CVTFLAGS ) @@ -1128,6 +1208,23 @@ inline OUString OStringToOUString( const OString & rStr, return OUString( rStr.getStr(), rStr.getLength(), encoding, convertFlags ); } +/** Convert an OUString to an OString, using a specific text encoding. + + The lengths of the two strings may differ (e.g., for double-byte + encodings, UTF-7, UTF-8). + + @param rStr + an OUString to convert. + + @param encoding + the text encoding to use for conversion. + + @param convertFlags + flags which control the conversion. Either use + OUSTRING_TO_OSTRING_CVTFLAGS, or see + <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more + details. + */ inline OString OUStringToOString( const OUString & rUnicode, rtl_TextEncoding encoding, sal_uInt32 convertFlags = OUSTRING_TO_OSTRING_CVTFLAGS ) |