cleanups for number() string function

- add sal_uInt64 valueOf helper to handle its full value range
- group deprecated valueOf() together
- forward to the number() taking the largest type instead of repeating
  the same code every time
- various doc improvements:
    - add missing @since
    - do not refer to non-existent number() overloads in docs
    - "use number" - "huh, of course I use a number?"
    - "code your own" - my own function? why?
    - + or += operators are not, strictly speaking, replacements for valueOf()

Change-Id: Ib138a06c4ac4365cfffc534e6ab115d55180a70d

sal/inc/rtl/string.h

@@ -649,6 +649,29 @@ SAL_DLLPUBLIC 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
 
+/** Create the string representation of an unsigned 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_VALUEOFUINT64 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_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfUInt64(
+        sal_Char * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
+#define RTL_STR_MAX_VALUEOFUINT64 65
+
 /** Create the string representation of a float.
 
     This function cannot be used for language-specific conversion.

sal/inc/rtl/ustring.h

@@ -979,6 +979,29 @@ SAL_DLLPUBLIC 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
 
+/** Create the string representation of an unsigned 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_VALUEOFUINT64 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_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfUInt64(
+        sal_Unicode * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
+#define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64
+
 /** Create the string representation of a float.
 
     This function cannot be used for language-specific conversion.

sal/rtl/source/strtmpl.cxx

@@ -844,6 +844,51 @@ sal_Int32 SAL_CALL IMPL_RTL_STRNAME( valueOfInt64 )( IMPL_RTL_STRCODE* pStr,
 
 /* ----------------------------------------------------------------------- */
 
+sal_Int32 SAL_CALL IMPL_RTL_STRNAME( valueOfUInt64 )( IMPL_RTL_STRCODE* pStr,
+                                                      sal_uInt64 n,
+                                                      sal_Int16 nRadix )
+    SAL_THROW_EXTERN_C()
+{
+    sal_Char    aBuf[RTL_STR_MAX_VALUEOFUINT64];
+    sal_Char*   pBuf = aBuf;
+    sal_Int32   nLen = 0;
+    sal_uInt64  nValue;
+
+    /* Radix must be valid */
+    if ( (nRadix < RTL_STR_MIN_RADIX) || (nRadix > RTL_STR_MAX_RADIX) )
+        nRadix = 10;
+
+    nValue = n;
+
+    /* create a recursive buffer with all values, except the last one */
+    do
+    {
+        sal_Char nDigit = (sal_Char)(nValue % nRadix);
+        nValue /= nRadix;
+        if ( nDigit > 9 )
+            *pBuf = (nDigit-10) + 'a';
+        else
+            *pBuf = (nDigit + '0' );
+        pBuf++;
+    }
+    while ( nValue > 0 );
+
+    /* copy the values in the right direction into the destination buffer */
+    do
+    {
+        pBuf--;
+        *pStr = *pBuf;
+        pStr++;
+        nLen++;
+    }
+    while ( pBuf != aBuf );
+    *pStr = 0;
+
+    return nLen;
+}
+
+/* ----------------------------------------------------------------------- */
+
 sal_Bool SAL_CALL IMPL_RTL_STRNAME( toBoolean )( const IMPL_RTL_STRCODE* pStr )
     SAL_THROW_EXTERN_C()
 {

sal/util/sal.map

@@ -658,6 +658,8 @@ LIBO_UDK_4.1 { # symbols available in >= LibO 4.1
         rtl_uString_ensureCapacity;
         rtl_string_alloc;
         rtl_uString_alloc;
+        rtl_str_valueOfUInt64;
+        rtl_ustr_valueOfUInt64;
 } LIBO_UDK_4.0;
 
 PRIVATE_1.0 {