Changeset 21741 in vbox

Timestamp:

Jul 21, 2009 12:13:13 PM (16 years ago)

Author:

vboxsync

Message:

iprt/string.h: documentation correction for the extended conversion functions.

File:

• trunk/include/iprt/string.h (modified) (6 diffs)

trunk/include/iprt/string.h

@@ -256 +256 @@
  *                          If a buffer was requested it must be freed using RTUtf16Free().
  * @param   cCps            The number of code points in the unicode string. This includes the terminator.
- * @param   pcCps           Where to store the length of the translated string. (Optional)
- *                          This field will be updated even on failure, however the value is only
- *                          specified for the following two error codes. On VERR_BUFFER_OVERFLOW
- *                          and VERR_NO_STR_MEMORY it contains the required buffer space.
+ * @param   pcCps           Where to store the length of the translated string,
+ *                          excluding the terminator. (Optional)
+ *
+ *                          This may be set under some error conditions,
+ *                          however, only for VERR_BUFFER_OVERFLOW and
+ *                          VERR_NO_STR_MEMORY will it contain a valid string
+ *                          length that can be used to resize the buffer.
  */
 RTDECL(int)  RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
@@ -315 +318 @@
  *                          If a buffer was requested it must be freed using RTUtf16Free().
  * @param   cwc             The buffer size in RTUTF16s. This includes the terminator.
- * @param   pcwc            Where to store the length of the translated string. (Optional)
- *                          This field will be updated even on failure, however the value is only
- *                          specified for the following two error codes. On VERR_BUFFER_OVERFLOW
- *                          and VERR_NO_STR_MEMORY it contains the required buffer space.
+ * @param   pcwc            Where to store the length of the translated string,
+ *                          excluding the terminator. (Optional)
+ *
+ *                          This may be set under some error conditions,
+ *                          however, only for VERR_BUFFER_OVERFLOW and
+ *                          VERR_NO_STR_MEMORY will it contain a valid string
+ *                          length that can be used to resize the buffer.
  */
 RTDECL(int)  RTStrToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
@@ -1383 +1389 @@
  * @param   uBase       The base of the representation used.
  *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi8        Where to store the converted number. (optional)
+ * @param   pi8         Where to store the converted number. (optional)
  */
 RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
@@ -1671 +1677 @@
  *                          If a buffer was requested it must be freed using RTUtf16Free().
  * @param   cch             The buffer size in chars (the type). This includes the terminator.
- * @param   pcch            Where to store the length of the translated string. (Optional)
- *                          This field will be updated even on failure, however the value is only
- *                          specified for the following two error codes. On VERR_BUFFER_OVERFLOW
- *                          and VERR_NO_STR_MEMORY it contains the required buffer space.
+ * @param   pcch            Where to store the length of the translated string,
+ *                          excluding the terminator. (Optional)
+ *
+ *                          This may be set under some error conditions,
+ *                          however, only for VERR_BUFFER_OVERFLOW and
+ *                          VERR_NO_STR_MEMORY will it contain a valid string
+ *                          length that can be used to resize the buffer.
  */
 RTDECL(int)  RTUtf16ToUtf8Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
@@ -1745 +1754 @@
  * @param   cch             The buffer size in chars (the type). This includes
  *                          the terminator.
- * @param   pcch            Where to store the length of the translated string.
- *                          (Optional)
- *                          This will be set even on failure, however the value
- *                          is only specified for the following two error
- *                          codes. On VERR_BUFFER_OVERFLOW and
- *                          VERR_NO_STR_MEMORY it contains the required buffer
- *                          space.
+ * @param   pcch            Where to store the length of the translated string,
+ *                          excluding the terminator. (Optional)
+ *
+ *                          This may be set under some error conditions,
+ *                          however, only for VERR_BUFFER_OVERFLOW and
+ *                          VERR_NO_STR_MEMORY will it contain a valid string
+ *                          length that can be used to resize the buffer.
  */
 RTDECL(int)  RTUtf16ToLatin1Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
@@ -2018 +2027 @@
  * @param   cwc             The buffer size in RTUTF16s. This includes the
  *                          terminator.
- * @param   pcwc            Where to store the length of the translated
- *                          string. (Optional) This will be set even on failure,
- *                          however the value is only specified for the
- *                          following two error codes. On VERR_BUFFER_OVERFLOW
- *                          and VERR_NO_STR_MEMORY it contains the required
- *                          buffer space.
+ * @param   pcwc            Where to store the length of the translated string,
+ *                          excluding the terminator. (Optional)
+ *
+ *                          This may be set under some error conditions,
+ *                          however, only for VERR_BUFFER_OVERFLOW and
+ *                          VERR_NO_STR_MEMORY will it contain a valid string
+ *                          length that can be used to resize the buffer.
  */
 RTDECL(int) RTLatin1ToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);