Changeset 57941 in vbox

Timestamp:

Sep 29, 2015 1:45:26 PM (9 years ago)

Author:

vboxsync

Message:

iprt/string.h: split out the UTF-16 and Latin-1 parts.

Location:

trunk/include/iprt

Files:

: 1 edited
: 2 copied

latin1.h (copied) (copied from trunk/include/iprt/string.h ) (13 diffs)
string.h (modified) (6 diffs)
utf16.h (copied) (copied from trunk/include/iprt/string.h ) (3 diffs)

Legend:

: Unmodified
: Added
: Removed

trunk/include/iprt/latin1.h

-              r57927
+              r57941
 /** @file
  * IPRT - String Manipulation.
+ * IPRT - String Manipulation, Latin-1 (ISO-8859-1) encoding.
  */
 …
  */
+#ifndef ___iprt_string_h
+#define ___iprt_string_h
+#include <iprt/cdefs.h>
+#include <iprt/types.h>
+#include <iprt/assert.h>
+#include <iprt/stdarg.h>
+#include <iprt/err.h> /* for VINF_SUCCESS */
+#if defined(RT_OS_LINUX) && defined(__KERNEL__)
+  RT_C_DECLS_BEGIN
+# define new newhack /* string.h: strreplace */
+# include <linux/string.h>
+# undef new
+  RT_C_DECLS_END
+#elif defined(IN_XF86_MODULE) && !defined(NO_ANSIC)
+  RT_C_DECLS_BEGIN
+# include "xf86_ansic.h"
+  RT_C_DECLS_END
+#elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
+  RT_C_DECLS_BEGIN
+  /** @todo
+   * XXX: Very ugly hack to get things build on recent FreeBSD builds. They have
+   * memchr now and we need to include param.h to get __FreeBSD_version and make
+   * memchr available based on the version below or we can't compile the kernel
+   * module on older versions anymore.
+   *
+   * But including param.h here opens Pandora's box because we clash with a few
+   * defines namely PVM and PAGE_SIZE. We can safely undefine PVM here but not
+   * PAGE_SIZE because this results in build errors sooner or later. Luckily this
+   * define is in a header included by param.h (machine/param.h). We define the
+   * guards here to prevent inclusion of it if PAGE_SIZE was defined already.
+   *
+   * @todo aeichner: Search for an elegant solution and cleanup this mess ASAP!
+   */
+# ifdef PAGE_SIZE
+#  define _AMD64_INCLUDE_PARAM_H_
+#  define _I386_INCLUDE_PARAM_H_
+#  define _MACHINE_PARAM_H_
+# endif
+# include <sys/param.h> /* __FreeBSD_version */
+# undef PVM
+# include <sys/libkern.h>
+  /*
+   * No memmove on versions < 7.2
+   * Defining a macro using bcopy here
+   */
+# define memmove(dst, src, size) bcopy(src, dst, size)
+  RT_C_DECLS_END
+#elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
+  /*
+   * Same case as with FreeBSD kernel:
+   * The string.h stuff clashes with sys/system.h
+   * ffs = find first set bit.
+   */
+# define ffs ffs_string_h
+# include <string.h>
+# undef ffs
+# undef strpbrk
+#else
+# include <string.h>
+#endif
+/*
+ * Supply prototypes for standard string functions provided by
+ * IPRT instead of the operating environment.
+ */
+#if defined(RT_OS_DARWIN) && defined(KERNEL)
+#ifndef ___iprt_latin1_h
+#define ___iprt_latin1_h
+#include <iprt/string.h>
 RT_C_DECLS_BEGIN
+void *memchr(const void *pv, int ch, size_t cb);
+char *strpbrk(const char *pszStr, const char *pszChars);
+RT_C_DECLS_END
+#endif
+#if defined(RT_OS_FREEBSD) && defined(_KERNEL)
+RT_C_DECLS_BEGIN
+#if __FreeBSD_version < 900000
+void *memchr(const void *pv, int ch, size_t cb);
+#endif
+char *strpbrk(const char *pszStr, const char *pszChars);
+RT_C_DECLS_END
+#endif
+#if !defined(RT_OS_LINUX) || !defined(_GNU_SOURCE)
+RT_C_DECLS_BEGIN
+void *memrchr(const char *pv, int ch, size_t cb);
+RT_C_DECLS_END
+#endif
+/** @def RT_USE_RTC_3629
+ * When defined the UTF-8 range will stop at  0x10ffff.  If not defined, the
+ * range stops at 0x7fffffff.
+ * @remarks Must be defined both when building and using the IPRT.  */
+#ifdef DOXYGEN_RUNNING
+# define RT_USE_RTC_3629
+#endif
+/**
+ * Byte zero the specified object.
+ *
+ * This will use sizeof(Obj) to figure the size and will call memset, bzero
+ * or some compiler intrinsic to perform the actual zeroing.
+ *
+ * @param   Obj     The object to zero. Make sure to dereference pointers.
+ *
+ * @remarks Because the macro may use memset it has been placed in string.h
+ *          instead of cdefs.h to avoid build issues because someone forgot
+ *          to include this header.
+ *
+ * @ingroup grp_rt_cdefs
+ */
+#define RT_ZERO(Obj)        RT_BZERO(&(Obj), sizeof(Obj))
+/**
+ * Byte zero the specified memory area.
+ *
+ * This will call memset, bzero or some compiler intrinsic to clear the
+ * specified bytes of memory.
+ *
+ * @param   pv          Pointer to the memory.
+ * @param   cb          The number of bytes to clear. Please, don't pass 0.
+ *
+ * @remarks Because the macro may use memset it has been placed in string.h
+ *          instead of cdefs.h to avoid build issues because someone forgot
+ *          to include this header.
+ *
+ * @ingroup grp_rt_cdefs
+ */
+#define RT_BZERO(pv, cb)    do { memset((pv), 0, cb); } while (0)
+/** @defgroup grp_rt_str    RTStr - String Manipulation
+ * Mostly UTF-8 related helpers where the standard string functions won't do.
+ * @ingroup grp_rt
+/** @defgroup rt_str_latin1     Latin-1 (ISO-8859-1) String Manipulation
+ * @ingroup grp_rt_str
+ *
+ * Deals with Latin-1 encoded strings.
+ *
+ * @warning Make sure to name all variables dealing with Latin-1 strings
+ *          suchthat there is no way to mistake them for normal UTF-8 strings.
+ *          There may be severe security issues resulting from mistaking Latin-1
+ *          for UTF-8!
+ *
  * @{
  */
+RT_C_DECLS_BEGIN
+/**
+ * The maximum string length.
+ */
+#define RTSTR_MAX       (~(size_t)0)
+/** @def RTSTR_TAG
+ * The default allocation tag used by the RTStr allocation APIs.
+ *
+ * When not defined before the inclusion of iprt/string.h, this will default to
+ * the pointer to the current file name.  The string API will make of use of
+ * this as pointer to a volatile but read-only string.
+ */
+#if !defined(RTSTR_TAG) || defined(DOXYGEN_RUNNING)
+# define RTSTR_TAG      (__FILE__)
+#endif
+#ifdef IN_RING3
+/**
+ * Allocates tmp buffer with default tag, translates pszString from UTF8 to
+ * current codepage.
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of allocated native CP string.
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   pszLatin1   The Latin-1 string.
+ */
+DECLINLINE(RTUNICP) RTLatin1GetCp(const char *pszLatin1)
+{
+    return *(const unsigned char *)pszLatin1;
+}
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code.
+ * @param   ppszLatin1  Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point. This
+ *                      is advanced one character forward on failure.
+ * @param   pCp         Where to store the code point. RTUNICP_INVALID is stored
+ *                      here on failure.
+ */
+DECLINLINE(int) RTLatin1GetCpEx(const char **ppszLatin1, PRTUNICP pCp)
+{
+    const unsigned char uch = **(const unsigned char **)ppszLatin1;
+    (*ppszLatin1)++;
+    *pCp = uch;
+    return VINF_SUCCESS;
+}
+/**
+ * Get the unicode code point at the given string position for a string of a
+ * given maximum length.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
+ * @param   ppszLatin1  Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ * @param   pcchLatin1  Pointer to the maximum string length.  This will be
+ *                      decremented by the size of the code point found.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ */
+DECLINLINE(int) RTLatin1GetCpNEx(const char **ppszLatin1, size_t *pcchLatin1, PRTUNICP pCp)
+{
+    if (RT_LIKELY(*pcchLatin1 != 0))
+    {
+        const unsigned char uch = **(const unsigned char **)ppszLatin1;
+        (*ppszLatin1)++;
+        (*pcchLatin1)--;
+        *pCp = uch;
+        return VINF_SUCCESS;
+    }
+    *pCp = RTUNICP_INVALID;
+    return VERR_END_OF_STRING;
+}
+/**
+ * Get the Latin-1 size in characters of a given Unicode code point.
+ *
+ * The code point is expected to be a valid Unicode one, but not necessarily in
+ * the range supported by Latin-1.
+ *
+ * @returns the size in characters, or zero if there is no Latin-1 encoding
+ */
+DECLINLINE(size_t) RTLatin1CpSize(RTUNICP CodePoint)
+{
+    if (CodePoint < 0x100)
+        return 1;
+    return 0;
+}
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by psz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   pszLatin1   The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the Latin-1 range.
+ */
+DECLINLINE(char *) RTLatin1PutCp(char *pszLatin1, RTUNICP CodePoint)
+{
+    AssertReturn(CodePoint < 0x100, NULL);
+    *pszLatin1++ = (unsigned char)CodePoint;
+    return pszLatin1;
+}
+/**
+ * Skips ahead, past the current code point.
+ *
+ * @returns Pointer to the char after the current code point.
+ * @param   pszLatin1   Pointer to the current code point.
+ * @remark  This will not move the next valid code point, only past the current one.
+ */
+DECLINLINE(char *) RTLatin1NextCp(const char *pszLatin1)
+{
+    pszLatin1++;
+    return (char *)pszLatin1;
+}
+/**
+ * Skips back to the previous code point.
+ *
+ * @returns Pointer to the char before the current code point.
+ * @returns pszLatin1Start on failure.
+ * @param   pszLatin1Start  Pointer to the start of the string.
+ * @param   pszLatin1       Pointer to the current code point.
+ */
+DECLINLINE(char *) RTLatin1PrevCp(const char *pszLatin1Start, const char *pszLatin1)
+{
+    if ((uintptr_t)pszLatin1 > (uintptr_t)pszLatin1Start)
+    {
+        pszLatin1--;
+        return (char *)pszLatin1;
+    }
+    return (char *)pszLatin1Start;
+}
+/**
+ * Translate a Latin1 string into a UTF-8 allocating the result buffer (default
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszLatin1       Latin1 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
  *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszString       UTF-8 string to convert.
+ */
+#define RTStrUtf8ToCurrentCP(ppszString, pszString)     RTStrUtf8ToCurrentCPTag((ppszString), (pszString), RTSTR_TAG)
+/**
+ * Allocates tmp buffer with custom tag, translates pszString from UTF8 to
+ * current codepage.
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of allocated native CP string.
+ *                          The returned pointer must be freed using
+ *                          RTStrFree()., const char *pszTag
+ * @param   pszString       UTF-8 string to convert.
+ */
+#define RTLatin1ToUtf8(pszLatin1, ppszString)       RTLatin1ToUtf8Tag((pszLatin1), (ppszString), RTSTR_TAG)
+/**
+ * Translate a Latin-1 string into a UTF-8 allocating the result buffer.
+ *
+ * @returns iprt status code.
+ * @param   pszLatin1       Latin-1 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
  * @param   pszTag          Allocation tag used for statistics and such.
  */
+RTR3DECL(int)  RTStrUtf8ToCurrentCPTag(char **ppszString, const char *pszString, const char *pszTag);
+/**
+ * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszString       Native string to convert.
+ */
+#define RTStrCurrentCPToUtf8(ppszString, pszString)     RTStrCurrentCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
+/**
+ * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszString       Native string to convert.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTR3DECL(int)  RTStrCurrentCPToUtf8Tag(char **ppszString, const char *pszString, const char *pszTag);
+#endif /* IN_RING3 */
+/**
+ * Free string allocated by any of the non-UCS-2 string functions.
+ *
+ * @returns iprt status code.
+ * @param   pszString      Pointer to buffer with string to free.
+ *                         NULL is accepted.
+ */
+RTDECL(void)  RTStrFree(char *pszString);
+/**
+ * Allocates a new copy of the given UTF-8 string (default tag).
+ *
+ * @returns Pointer to the allocated UTF-8 string.
+ * @param   pszString       UTF-8 string to duplicate.
+ */
+#define RTStrDup(pszString)             RTStrDupTag((pszString), RTSTR_TAG)
+/**
+ * Allocates a new copy of the given UTF-8 string (custom tag).
+ *
+ * @returns Pointer to the allocated UTF-8 string.
+ * @param   pszString       UTF-8 string to duplicate.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(char *) RTStrDupTag(const char *pszString, const char *pszTag);
+/**
+ * Allocates a new copy of the given UTF-8 string (default tag).
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of the allocated UTF-8 string.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszString       UTF-8 string to duplicate.
+ */
+#define RTStrDupEx(ppszString, pszString)   RTStrDupExTag((ppszString), (pszString), RTSTR_TAG)
+/**
+ * Allocates a new copy of the given UTF-8 string (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   ppszString      Receives pointer of the allocated UTF-8 string.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszString       UTF-8 string to duplicate.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTStrDupExTag(char **ppszString, const char *pszString, const char *pszTag);
+/**
+ * Allocates a new copy of the given UTF-8 substring (default tag).
+ *
+ * @returns Pointer to the allocated UTF-8 substring.
+ * @param   pszString       UTF-8 string to duplicate.
+ * @param   cchMax          The max number of chars to duplicate, not counting
+ *                          the terminator.
+ */
+#define RTStrDupN(pszString, cchMax)        RTStrDupNTag((pszString), (cchMax), RTSTR_TAG)
+/**
+ * Allocates a new copy of the given UTF-8 substring (custom tag).
+ *
+ * @returns Pointer to the allocated UTF-8 substring.
+ * @param   pszString       UTF-8 string to duplicate.
+ * @param   cchMax          The max number of chars to duplicate, not counting
+ *                          the terminator.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(char *) RTStrDupNTag(const char *pszString, size_t cchMax, const char *pszTag);
+/**
+ * Appends a string onto an existing IPRT allocated string (default tag).
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   pszAppend           The string to append.  NULL and empty strings
+ *                              are quietly ignored.
+ */
+#define RTStrAAppend(ppsz, pszAppend)   RTStrAAppendTag((ppsz), (pszAppend), RTSTR_TAG)
+/**
+ * Appends a string onto an existing IPRT allocated string (custom tag).
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   pszAppend           The string to append.  NULL and empty strings
+ *                              are quietly ignored.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrAAppendTag(char **ppsz, const char *pszAppend, const char *pszTag);
+/**
+ * Appends N bytes from a strings onto an existing IPRT allocated string
+ * (default tag).
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   pszAppend           The string to append.  Can be NULL if cchAppend
+ *                              is NULL.
+ * @param   cchAppend           The number of chars (not code points) to append
+ *                              from pszAppend.   Must not be more than
+ *                              @a pszAppend contains, except for the special
+ *                              value RTSTR_MAX that can be used to indicate all
+ *                              of @a pszAppend without having to strlen it.
+ */
+#define RTStrAAppendN(ppsz, pszAppend, cchAppend)   RTStrAAppendNTag((ppsz), (pszAppend), (cchAppend), RTSTR_TAG)
+/**
+ * Appends N bytes from a strings onto an existing IPRT allocated string (custom
+ * tag).
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   pszAppend           The string to append.  Can be NULL if cchAppend
+ *                              is NULL.
+ * @param   cchAppend           The number of chars (not code points) to append
+ *                              from pszAppend.   Must not be more than
+ *                              @a pszAppend contains, except for the special
+ *                              value RTSTR_MAX that can be used to indicate all
+ *                              of @a pszAppend without having to strlen it.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrAAppendNTag(char **ppsz, const char *pszAppend, size_t cchAppend, const char *pszTag);
+/**
+ * Appends one or more strings onto an existing IPRT allocated string.
+ *
+ * This is a very flexible and efficient alternative to using RTStrAPrintf to
+ * combine several strings together.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   cPairs              The number of string / length pairs in the
+ *                              @a va.
+ * @param   va                  List of string (const char *) and length
+ *                              (size_t) pairs.  The strings will be appended to
+ *                              the string in the first argument.
+ */
+#define RTStrAAppendExNV(ppsz, cPairs, va)  RTStrAAppendExNVTag((ppsz), (cPairs), (va), RTSTR_TAG)
+/**
+ * Appends one or more strings onto an existing IPRT allocated string.
+ *
+ * This is a very flexible and efficient alternative to using RTStrAPrintf to
+ * combine several strings together.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   cPairs              The number of string / length pairs in the
+ *                              @a va.
+ * @param   va                  List of string (const char *) and length
+ *                              (size_t) pairs.  The strings will be appended to
+ *                              the string in the first argument.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrAAppendExNVTag(char **ppsz, size_t cPairs, va_list va, const char *pszTag);
+/**
+ * Appends one or more strings onto an existing IPRT allocated string
+ * (untagged).
+ *
+ * This is a very flexible and efficient alternative to using RTStrAPrintf to
+ * combine several strings together.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   cPairs              The number of string / length pairs in the
+ *                              ellipsis.
+ * @param   ...                 List of string (const char *) and length
+ *                              (size_t) pairs.  The strings will be appended to
+ *                              the string in the first argument.
+ */
+DECLINLINE(int) RTStrAAppendExN(char **ppsz, size_t cPairs, ...)
+{
+    int     rc;
+    va_list va;
+    va_start(va, cPairs);
+    rc = RTStrAAppendExNVTag(ppsz, cPairs, va, RTSTR_TAG);
+    va_end(va);
+    return rc;
+}
+/**
+ * Appends one or more strings onto an existing IPRT allocated string (custom
+ * tag).
+ *
+ * This is a very flexible and efficient alternative to using RTStrAPrintf to
+ * combine several strings together.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer must either be NULL or point to a string
+ *                              returned by an IPRT string API.  (In/Out)
+ * @param   pszTag              Allocation tag used for statistics and such.
+ * @param   cPairs              The number of string / length pairs in the
+ *                              ellipsis.
+ * @param   ...                 List of string (const char *) and length
+ *                              (size_t) pairs.  The strings will be appended to
+ *                              the string in the first argument.
+ */
+DECLINLINE(int) RTStrAAppendExNTag(char **ppsz, const char *pszTag, size_t cPairs, ...)
+{
+    int     rc;
+    va_list va;
+    va_start(va, cPairs);
+    rc = RTStrAAppendExNVTag(ppsz, cPairs, va, pszTag);
+    va_end(va);
+    return rc;
+}
+/**
+ * Truncates an IPRT allocated string (default tag).
+ *
+ * @retval  VINF_SUCCESS.
+ * @retval  VERR_OUT_OF_RANGE if cchNew is too long.  Nothing is done.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer can be NULL if @a cchNew is 0, no change
+ *                              is made then.  If we actually reallocate the
+ *                              string, the string pointer might be changed by
+ *                              this call.  (In/Out)
+ * @param   cchNew              The new string length (excluding the
+ *                              terminator).  The string must be at least this
+ *                              long or we'll return VERR_OUT_OF_RANGE and
+ *                              assert on you.
+ */
+#define RTStrATruncate(ppsz, cchNew)    RTStrATruncateTag((ppsz), (cchNew), RTSTR_TAG)
+/**
+ * Truncates an IPRT allocated string.
+ *
+ * @retval  VINF_SUCCESS.
+ * @retval  VERR_OUT_OF_RANGE if cchNew is too long.  Nothing is done.
+ *
+ * @param   ppsz                Pointer to the string pointer.  The string
+ *                              pointer can be NULL if @a cchNew is 0, no change
+ *                              is made then.  If we actually reallocate the
+ *                              string, the string pointer might be changed by
+ *                              this call.  (In/Out)
+ * @param   cchNew              The new string length (excluding the
+ *                              terminator).  The string must be at least this
+ *                              long or we'll return VERR_OUT_OF_RANGE and
+ *                              assert on you.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrATruncateTag(char **ppsz, size_t cchNew, const char *pszTag);
+/**
+ * Allocates memory for string storage (default tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @returns Pointer to the allocated string.  The first byte is always set
+ *          to the string terminator char, the contents of the remainder of the
+ *          memory is undefined.  The string must be freed by calling RTStrFree.
+ *
+ *          NULL is returned if the allocation failed.  Please translate this to
+ *          VERR_NO_STR_MEMORY and not VERR_NO_MEMORY.  Also consider
+ *          RTStrAllocEx if an IPRT status code is required.
+ *
+ * @param   cb                  How many bytes to allocate.  If this is zero, we
+ *                              will allocate a terminator byte anyway.
+ */
+#define RTStrAlloc(cb)                  RTStrAllocTag((cb), RTSTR_TAG)
+/**
+ * Allocates memory for string storage (custom tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @returns Pointer to the allocated string.  The first byte is always set
+ *          to the string terminator char, the contents of the remainder of the
+ *          memory is undefined.  The string must be freed by calling RTStrFree.
+ *
+ *          NULL is returned if the allocation failed.  Please translate this to
+ *          VERR_NO_STR_MEMORY and not VERR_NO_MEMORY.  Also consider
+ *          RTStrAllocEx if an IPRT status code is required.
+ *
+ * @param   cb                  How many bytes to allocate.  If this is zero, we
+ *                              will allocate a terminator byte anyway.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(char *) RTStrAllocTag(size_t cb, const char *pszTag);
+/**
+ * Allocates memory for string storage, with status code (default tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY
+ *
+ * @param   ppsz                Where to return the allocated string.  This will
+ *                              be set to NULL on failure.  On success, the
+ *                              returned memory will always start with a
+ *                              terminator char so that it is considered a valid
+ *                              C string, the contents of rest of the memory is
+ *                              undefined.
+ * @param   cb                  How many bytes to allocate.  If this is zero, we
+ *                              will allocate a terminator byte anyway.
+ */
+#define RTStrAllocEx(ppsz, cb)      RTStrAllocExTag((ppsz), (cb), RTSTR_TAG)
+/**
+ * Allocates memory for string storage, with status code (custom tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_STR_MEMORY
+ *
+ * @param   ppsz                Where to return the allocated string.  This will
+ *                              be set to NULL on failure.  On success, the
+ *                              returned memory will always start with a
+ *                              terminator char so that it is considered a valid
+ *                              C string, the contents of rest of the memory is
+ *                              undefined.
+ * @param   cb                  How many bytes to allocate.  If this is zero, we
+ *                              will allocate a terminator byte anyway.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrAllocExTag(char **ppsz, size_t cb, const char *pszTag);
+/**
+ * Reallocates the specified string (default tag).
+ *
+ * You should normally not have use this function, except perhaps to truncate a
+ * really long string you've got from some IPRT string API, but then you should
+ * use RTStrATruncate.
+ *
+ * @returns VINF_SUCCESS.
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string variable containing the
+ *                              input and output string.
+ *
+ *                              When not freeing the string, the result will
+ *                              always have the last byte set to the terminator
+ *                              character so that when used for string
+ *                              truncation the result will be a valid C string
+ *                              (your job to keep it a valid UTF-8 string).
+ *
+ *                              When the input string is NULL and we're supposed
+ *                              to reallocate, the returned string will also
+ *                              have the first byte set to the terminator char
+ *                              so it will be a valid C string.
+ *
+ * @param   cbNew               When @a cbNew is zero, we'll behave like
+ *                              RTStrFree and @a *ppsz will be set to NULL.
+ *
+ *                              When not zero, this will be the new size of the
+ *                              memory backing the string, i.e. it includes the
+ *                              terminator char.
+ */
+#define RTStrRealloc(ppsz, cbNew)       RTStrReallocTag((ppsz), (cbNew), RTSTR_TAG)
+/**
+ * Reallocates the specified string (custom tag).
+ *
+ * You should normally not have use this function, except perhaps to truncate a
+ * really long string you've got from some IPRT string API, but then you should
+ * use RTStrATruncate.
+ *
+ * @returns VINF_SUCCESS.
+ * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
+ *          remains unchanged.
+ *
+ * @param   ppsz                Pointer to the string variable containing the
+ *                              input and output string.
+ *
+ *                              When not freeing the string, the result will
+ *                              always have the last byte set to the terminator
+ *                              character so that when used for string
+ *                              truncation the result will be a valid C string
+ *                              (your job to keep it a valid UTF-8 string).
+ *
+ *                              When the input string is NULL and we're supposed
+ *                              to reallocate, the returned string will also
+ *                              have the first byte set to the terminator char
+ *                              so it will be a valid C string.
+ *
+ * @param   cbNew               When @a cbNew is zero, we'll behave like
+ *                              RTStrFree and @a *ppsz will be set to NULL.
+ *
+ *                              When not zero, this will be the new size of the
+ *                              memory backing the string, i.e. it includes the
+ *                              terminator char.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrReallocTag(char **ppsz, size_t cbNew, const char *pszTag);
+/**
+ * Validates the UTF-8 encoding of the string.
+ *
+ * @returns iprt status code.
+ * @param   psz         The string.
+ */
+RTDECL(int) RTStrValidateEncoding(const char *psz);
+/** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
+ */
+/** Check that the string is zero terminated within the given size.
+ * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
+#define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED     RT_BIT_32(0)
+/** Check that the string is exactly the given length.
+ * If it terminates early, VERR_BUFFER_UNDERFLOW will be returned.  When used
+ * together with RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED, the given length must
+ * include the terminator or VERR_BUFFER_OVERFLOW will be returned. */
+#define RTSTR_VALIDATE_ENCODING_EXACT_LENGTH        RT_BIT_32(1)
+/** @} */
+/**
+ * Validates the UTF-8 encoding of the string.
+ *
+ * @returns iprt status code.
+ * @param   psz         The string.
+ * @param   cch         The max string length (/ size).  Use RTSTR_MAX to
+ *                      process the entire string.
+ * @param   fFlags      Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
+ */
+RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
+/**
+ * Checks if the UTF-8 encoding is valid.
+ *
+ * @returns true / false.
+ * @param   psz         The string.
+ */
+RTDECL(bool) RTStrIsValidEncoding(const char *psz);
+/**
+ * Purge all bad UTF-8 encoding in the string, replacing it with '?'.
+ *
+ * @returns The number of bad characters (0 if nothing was done).
+ * @param   psz         The string to purge.
+ */
+RTDECL(size_t) RTStrPurgeEncoding(char *psz);
+/**
+ * Sanitise a (valid) UTF-8 string by replacing all characters outside a white
+ * list in-place by an ASCII replacement character.  Multi-byte characters will
+ * be replaced byte by byte.
+ *
+ * @returns The number of code points replaced, or a negative value if the
+ *          string is not correctly encoded.  In this last case the string
+ *          may be partially processed.
+ * @param   psz            The string to sanitise.
+ * @param   puszValidSet   A zero-terminated array of pairs of Unicode points.
+ *                         Each pair is the start and end point of a range,
+ *                         and the union of these ranges forms the white list.
+ * @param   chReplacement  The ASCII replacement character.
+ */
+RTDECL(ssize_t) RTStrPurgeComplementSet(char *psz, PCRTUNICP puszValidSet, char chReplacement);
+/**
+ * Gets the number of code points the string is made up of, excluding
+ * the terminator.
+ *
+ *
+ * @returns Number of code points (RTUNICP).
+ * @returns 0 if the string was incorrectly encoded.
+ * @param   psz         The string.
+ */
+RTDECL(size_t) RTStrUniLen(const char *psz);
+/**
+ * Gets the number of code points the string is made up of, excluding
+ * the terminator.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-8
+ * strings will be rejected.
+ *
+ * @returns iprt status code.
+ * @param   psz         The string.
+ * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
+ * @param   pcuc        Where to store the code point count.
+ *                      This is undefined on failure.
+ */
+RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
+/**
+ * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   ppUniString     Receives pointer to the allocated unicode string.
+ *                          The returned string must be freed using RTUniFree().
+ */
+RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
+/**
+ * Translates pszString from UTF-8 to an array of code points, allocating the result
+ * array if requested.
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
+ *                          when it reaches cchString or the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppaCps          If cCps is non-zero, this must either be pointing to pointer to
+ *                          a buffer of the specified size, or pointer to a NULL pointer.
+ *                          If *ppusz is NULL or cCps is zero a buffer of at least cCps items
+ *                          will be allocated to hold the translated string.
+ *                          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,
+RTDECL(int)  RTLatin1ToUtf8Tag(const char *pszLatin1, char **ppszString, const char *pszTag);
+/**
+ * Translates Latin-1 to UTF-8 using buffer provided by the caller or a fittingly
+ * sized buffer allocated by the function (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszLatin1       The Latin-1 string to convert.
+ * @param   cchLatin1       The number of Latin-1 characters to translate from
+ *                          pszLatin1. The translation will stop when reaching
+ *                          cchLatin1 or the terminator ('\\0').  Use RTSTR_MAX
+ *                          to translate the entire string.
+ * @param   ppsz            If @a cch is non-zero, this must either be pointing
+ *                          to a pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.  If *ppsz is NULL or
+ *                          @a cch is zero a buffer of at least @a cch chars
+ *                          will be allocated to hold the translated string. If
+ *                          a buffer was requested it must be freed using
+ *                          RTStrFree().
+ * @param   cch             The buffer size in chars (the type). This includes the terminator.
+ * @param   pcch            Where to store the length of the translated string,
  *                          excluding the terminator. (Optional)
+ *
 …
  *                          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);
+/**
+ * Calculates the length of the string in RTUTF16 items.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-8
+ * strings will be rejected. The primary purpose of this function is to
+ * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
+ * other purposes RTStrCalcUtf16LenEx() should be used.
+ *
+ * @returns Number of RTUTF16 items.
+ * @returns 0 if the string was incorrectly encoded.
+ * @param   psz         The string.
+ */
+RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
+/**
+ * Calculates the length of the string in RTUTF16 items.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-8
+ * strings will be rejected.
+ *
+ * @returns iprt status code.
+ * @param   psz         The string.
+ * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
+ * @param   pcwc        Where to store the string length. Optional.
+ *                      This is undefined on failure.
+ */
+RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
+/**
+ * Translate a UTF-8 string into a UTF-16 allocating the result buffer (default
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string.
+ *                          The returned string must be freed using RTUtf16Free().
+ */
+#define RTStrToUtf16(pszString, ppwszString)    RTStrToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
+/**
+ * Translate a UTF-8 string into a UTF-16 allocating the result buffer (custom
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string.
+ *                          The returned string must be freed using RTUtf16Free().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
+/**
+ * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
+ *                          when it reaches cchString or the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing to pointer to
+ *                          a buffer of the specified size, or pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
+ *                          will be allocated to hold the translated string.
+ *                          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,
+ *                          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.
+ */
+#define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
+    RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
+/**
+ * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
+ * requested (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
+ *                          when it reaches cchString or the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing to pointer to
+ *                          a buffer of the specified size, or pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
+ *                          will be allocated to hold the translated string.
+ *                          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,
+ *                          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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTStrToUtf16ExTag(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
+/**
+ * Calculates the length of the string in Latin-1 characters.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-8
+ * strings as well as string with codepoints outside the latin-1 range will be
+ * rejected.  The primary purpose of this function is to help allocate buffers
+ * for RTStrToLatin1Ex of the correct size.  For most other purposes
+ * RTStrCalcLatin1LenEx() should be used.
+ *
+ * @returns Number of Latin-1 characters.
+ * @returns 0 if the string was incorrectly encoded.
+ * @param   psz         The string.
+ */
+RTDECL(size_t) RTStrCalcLatin1Len(const char *psz);
+/**
+ * Calculates the length of the string in Latin-1 characters.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-8
+ * strings as well as string with codepoints outside the latin-1 range will be
+ * rejected.
+ *
+ * @returns iprt status code.
+ * @param   psz         The string.
+ * @param   cch         The max string length. Use RTSTR_MAX to process the
+ *                      entire string.
+ * @param   pcch        Where to store the string length. Optional.
+ *                      This is undefined on failure.
+ */
+RTDECL(int) RTStrCalcLatin1LenEx(const char *psz, size_t cch, size_t *pcch);
+/**
+ * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   ppszString      Receives pointer to the allocated Latin-1 string.
+ *                          The returned string must be freed using RTStrFree().
+ */
+#define RTStrToLatin1(pszString, ppszString)    RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
+/**
+ * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   ppszString      Receives pointer to the allocated Latin-1 string.
+ *                          The returned string must be freed using RTStrFree().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrToLatin1Tag(const char *pszString, char **ppszString, const char *pszTag);
+/**
+ * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stop when it reaches cchString or
+ *                          the string terminator ('\\0'). Use RTSTR_MAX to
+ *                          translate the entire string.
+ * @param   ppsz            If cch is non-zero, this must either be pointing to
+ *                          pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
+ *                          is zero a buffer of at least cch items will be
+ *                          allocated to hold the translated string. If a
+ *                          buffer was requested it must be freed using
+ *                          RTStrFree().
+ * @param   cch             The buffer size in bytes. This includes the
+ *                          terminator.
+ * @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.
+ */
+#define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
+    RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
+/**
+ * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
+ * requested (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       UTF-8 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stop when it reaches cchString or
+ *                          the string terminator ('\\0'). Use RTSTR_MAX to
+ *                          translate the entire string.
+ * @param   ppsz            If cch is non-zero, this must either be pointing to
+ *                          pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
+ *                          is zero a buffer of at least cch items will be
+ *                          allocated to hold the translated string. If a
+ *                          buffer was requested it must be freed using
+ *                          RTStrFree().
+ * @param   cch             The buffer size in bytes.  This includes the
+ *                          terminator.
+ * @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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTStrToLatin1ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
+/**
+ * Translate a Latin1 string into a UTF-8 allocating the result buffer (default
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       Latin1 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ */
+#define RTLatin1ToUtf8(pszString, ppszString)       RTLatin1ToUtf8Tag((pszString), (ppszString), RTSTR_TAG)
+/**
+ * Translate a Latin-1 string into a UTF-8 allocating the result buffer.
+ *
+ * @returns iprt status code.
+ * @param   pszString       Latin-1 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTLatin1ToUtf8Tag(const char *pszString, char **ppszString, const char *pszTag);
+/**
+ * Translates Latin-1 to UTF-8 using buffer provided by the caller or a fittingly
+ * sized buffer allocated by the function (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   cchString       The number of Latin-1 characters to translate from
+ *                          pszString. The translation will stop when reaching
+ *                          cchString or the terminator ('\\0').  Use RTSTR_MAX
+ *                          to translate the entire string.
+ * @param   ppsz            If cch is non-zero, this must either be pointing to
+ *                          a pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
+ *                          is zero a buffer of at least cch chars will be
+ *                          allocated to hold the translated string. If a
+ *                          buffer was requested it must be freed using
+ *                          RTStrFree().
+ * @param   cch             The buffer size in chars (the type). This includes the terminator.
+ * @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.
+ */
+#define RTLatin1ToUtf8Ex(pszString, cchString, ppsz, cch, pcch) \
+    RTLatin1ToUtf8ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
+#define RTLatin1ToUtf8Ex(pszLatin1, cchLatin1, ppsz, cch, pcch) \
+    RTLatin1ToUtf8ExTag((pszLatin1), (cchLatin1), (ppsz), (cch), (pcch), RTSTR_TAG)
 /**
 …
+ *
  * @returns iprt status code.
  * @param   pszString       The Latin1 string to convert.
  * @param   cchString       The number of Latin1 characters to translate from
+ * @param   pszLatin1       The Latin1 string to convert.
+ * @param   cchLatin1       The number of Latin1 characters to translate from
  *                          pwszString.  The translation will stop when
  *                          reaching cchString or the terminator ('\\0').  Use
+ *                          reaching cchLatin1 or the terminator ('\\0').  Use
  *                          RTSTR_MAX to translate the entire string.
  * @param   ppsz            If cch is non-zero, this must either be pointing to
 …
  * @param   pszTag          Allocation tag used for statistics and such.
  */
+RTDECL(int)  RTLatin1ToUtf8ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
+RTDECL(int)  RTLatin1ToUtf8ExTag(const char *pszLatin1, size_t cchLatin1, char **ppsz, size_t cch, size_t *pcch,
+                                 const char *pszTag);
 /**
 …
  * @returns Number of chars (bytes).
  * @returns 0 if the string was incorrectly encoded.
  * @param   psz        The Latin-1 string.
  */
 RTDECL(size_t) RTLatin1CalcUtf8Len(const char *psz);
+ * @param   pszLatin1     The Latin-1 string.
+ */
+RTDECL(size_t) RTLatin1CalcUtf8Len(const char *pszLatin1);
 /**
 …
+ *
  * @returns iprt status code.
+ * @param   psz         The string.
+ * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
+ * @param   pszLatin1   The Latin-1 string.
+ * @param   cchLatin1   The max string length. Use RTSTR_MAX to process the
+ *                      entire string.
  * @param   pcch        Where to store the string length (in bytes).  Optional.
  *                      This is undefined on failure.
  */
+RTDECL(int) RTLatin1CalcUtf8LenEx(const char *psz, size_t cch, size_t *pcch);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   psz         The string.
+ */
+RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code
+ * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
+ * @param   ppsz        The string cursor.
+ *                      This is advanced one character forward on failure.
+ * @param   pCp         Where to store the unicode code point.
+ *                      Stores RTUNICP_INVALID if the encoding is invalid.
+ */
+RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
+/**
+ * Get the unicode code point at the given string position for a string of a
+ * given length.
+ *
+ * @returns iprt status code
+ * @retval  VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
+ * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
+ * @param   ppsz        The string.
+ * @param   pcch        Pointer to the length of the string.  This will be
+ *                      decremented by the size of the code point.
+ * @param   pCp         Where to store the unicode code point.
+ *                      Stores RTUNICP_INVALID if the encoding is invalid.
+ */
+RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by psz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   psz         The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the UTF-8 range.
+ *
+ * @remark  This is a worker function for RTStrPutCp().
+ *
+ */
+RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   psz         The string.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          the most frequent and simplest sequence, the rest is
+ *          handled by RTStrGetCpInternal().
+ */
+DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
+{
+    const unsigned char uch = *(const unsigned char *)psz;
+    if (!(uch & RT_BIT(7)))
+        return uch;
+    return RTStrGetCpInternal(psz);
+}
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code.
+ * @param   ppsz        Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ *                      This is advanced one character forward on failure.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          the most frequent and simplest sequence, the rest is
+ *          handled by RTStrGetCpExInternal().
+ */
+DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
+{
+    const unsigned char uch = **(const unsigned char **)ppsz;
+    if (!(uch & RT_BIT(7)))
+    {
+        (*ppsz)++;
+        *pCp = uch;
+        return VINF_SUCCESS;
+    }
+    return RTStrGetCpExInternal(ppsz, pCp);
+}
+/**
+ * Get the unicode code point at the given string position for a string of a
+ * given maximum length.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
+ * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
+ * @param   ppsz        Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ * @param   pcch        Pointer to the maximum string length.  This will be
+ *                      decremented by the size of the code point found.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          the most frequent and simplest sequence, the rest is
+ *          handled by RTStrGetCpNExInternal().
+ */
+DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
+{
+    if (RT_LIKELY(*pcch != 0))
+    {
+        const unsigned char uch = **(const unsigned char **)ppsz;
+        if (!(uch & RT_BIT(7)))
+        {
+            (*ppsz)++;
+            (*pcch)--;
+            *pCp = uch;
+            return VINF_SUCCESS;
+        }
+    }
+    return RTStrGetCpNExInternal(ppsz, pcch, pCp);
+}
+/**
+ * Get the UTF-8 size in characters of a given Unicode code point.
+ *
+ * The code point is expected to be a valid Unicode one, but not necessarily in
+ * the range supported by UTF-8.
+ *
+ * @returns The number of chars (bytes) required to encode the code point, or
+ *          zero if there is no UTF-8 encoding.
+ * @param   CodePoint       The unicode code point.
+ */
+DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint)
+{
+    if (CodePoint < 0x00000080)
+        return 1;
+    if (CodePoint < 0x00000800)
+        return 2;
+    if (CodePoint < 0x00010000)
+        return 3;
+#ifdef RT_USE_RTC_3629
+    if (CodePoint < 0x00011000)
+        return 4;
+#else
+    if (CodePoint < 0x00200000)
+        return 4;
+    if (CodePoint < 0x04000000)
+        return 5;
+    if (CodePoint < 0x7fffffff)
+        return 6;
+#endif
+    return 0;
+}
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by psz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   psz         The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the UTF-8 range.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          the most frequent and simplest sequence, the rest is
+ *          handled by RTStrPutCpInternal().
+ */
+DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
+{
+    if (CodePoint < 0x80)
+    {
+        *psz++ = (unsigned char)CodePoint;
+        return psz;
+    }
+    return RTStrPutCpInternal(psz, CodePoint);
+}
+/**
+ * Skips ahead, past the current code point.
+ *
+ * @returns Pointer to the char after the current code point.
+ * @param   psz     Pointer to the current code point.
+ * @remark  This will not move the next valid code point, only past the current one.
+ */
+DECLINLINE(char *) RTStrNextCp(const char *psz)
+{
+    RTUNICP Cp;
+    RTStrGetCpEx(&psz, &Cp);
+    return (char *)psz;
+}
+/**
+ * Skips back to the previous code point.
+ *
+ * @returns Pointer to the char before the current code point.
+ * @returns pszStart on failure.
+ * @param   pszStart    Pointer to the start of the string.
+ * @param   psz         Pointer to the current code point.
+ */
+RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   psz         The string.
+ */
+DECLINLINE(RTUNICP) RTLatin1GetCp(const char *psz)
+{
+    return *(const unsigned char *)psz;
+}
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code.
+ * @param   ppsz        Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ *                      This is advanced one character forward on failure.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          the most frequent and simplest sequence, the rest is
+ *          handled by RTStrGetCpExInternal().
+ */
+DECLINLINE(int) RTLatin1GetCpEx(const char **ppsz, PRTUNICP pCp)
+{
+    const unsigned char uch = **(const unsigned char **)ppsz;
+    (*ppsz)++;
+    *pCp = uch;
+    return VINF_SUCCESS;
+}
+/**
+ * Get the unicode code point at the given string position for a string of a
+ * given maximum length.
+ *
+ * @returns iprt status code.
+ * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
+ * @param   ppsz        Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ * @param   pcch        Pointer to the maximum string length.  This will be
+ *                      decremented by the size of the code point found.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ */
+DECLINLINE(int) RTLatin1GetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
+{
+    if (RT_LIKELY(*pcch != 0))
+    {
+        const unsigned char uch = **(const unsigned char **)ppsz;
+        (*ppsz)++;
+        (*pcch)--;
+        *pCp = uch;
+        return VINF_SUCCESS;
+    }
+    *pCp = RTUNICP_INVALID;
+    return VERR_END_OF_STRING;
+}
+/**
+ * Get the Latin-1 size in characters of a given Unicode code point.
+ *
+ * The code point is expected to be a valid Unicode one, but not necessarily in
+ * the range supported by Latin-1.
+ *
+ * @returns the size in characters, or zero if there is no Latin-1 encoding
+ */
+DECLINLINE(size_t) RTLatin1CpSize(RTUNICP CodePoint)
+{
+    if (CodePoint < 0x100)
+        return 1;
+    return 0;
+}
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by psz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   psz         The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the Latin-1 range.
+ */
+DECLINLINE(char *) RTLatin1PutCp(char *psz, RTUNICP CodePoint)
+{
+    AssertReturn(CodePoint < 0x100, NULL);
+    *psz++ = (unsigned char)CodePoint;
+    return psz;
+}
+/**
+ * Skips ahead, past the current code point.
+ *
+ * @returns Pointer to the char after the current code point.
+ * @param   psz     Pointer to the current code point.
+ * @remark  This will not move the next valid code point, only past the current one.
+ */
+DECLINLINE(char *) RTLatin1NextCp(const char *psz)
+{
+    psz++;
+    return (char *)psz;
+}
+/**
+ * Skips back to the previous code point.
+ *
+ * @returns Pointer to the char before the current code point.
+ * @returns pszStart on failure.
+ * @param   pszStart    Pointer to the start of the string.
+ * @param   psz         Pointer to the current code point.
+ */
+DECLINLINE(char *) RTLatin1PrevCp(const char *pszStart, const char *psz)
+{
+    if ((uintptr_t)psz > (uintptr_t)pszStart)
+    {
+        psz--;
+        return (char *)psz;
+    }
+    return (char *)pszStart;
+}
+/** @page pg_rt_str_format  The IPRT Format Strings
+ *
+ * IPRT implements most of the commonly used format types and flags with the
+ * exception of floating point which is completely missing.  In addition IPRT
+ * provides a number of IPRT specific format types for the IPRT typedefs and
+ * other useful things.  Note that several of these extensions are similar to
+ * \%p and doesn't care much if you try add formating flags/width/precision.
+ *
+ *
+ * Group 0a, The commonly used format types:
+ *      - \%s   - Takes a pointer to a zero terminated string (UTF-8) and
+ *                prints it with the optionally adjustment (width, -) and
+ *                length restriction (precision).
+ *      - \%ls  - Same as \%s except that the input is UTF-16 (output UTF-8).
+ *      - \%Ls  - Same as \%s except that the input is UCS-32 (output UTF-8).
+ *      - \%S   - Same as \%s, used to convert to current codeset but this is
+ *                now done by the streams code.  Deprecated, use \%s.
+ *      - \%lS  - Ditto. Deprecated, use \%ls.
+ *      - \%LS  - Ditto. Deprecated, use \%Ls.
+ *      - \%c   - Takes a char and prints it.
+ *      - \%d   - Takes a signed integer and prints it as decimal. Thousand
+ *                separator (\'), zero padding (0), adjustment (-+), width,
+ *                precision
+ *      - \%i   - Same as \%d.
+ *      - \%u   - Takes an unsigned integer and prints it as decimal. Thousand
+ *                separator (\'), zero padding (0), adjustment (-+), width,
+ *                precision
+ *      - \%x   - Takes an unsigned integer and prints it as lowercased
+ *                hexadecimal.  The special hash (\#) flag causes a '0x'
+ *                prefixed to be printed. Zero padding (0), adjustment (-+),
+ *                width, precision.
+ *      - \%X   - Same as \%x except that it is uppercased.
+ *      - \%o   - Takes an unsigned (?) integer and prints it as octal. Zero
+ *                padding (0), adjustment (-+), width, precision.
+ *      - \%p   - Takes a pointer (void technically) and prints it. Zero
+ *                padding (0), adjustment (-+), width, precision.
+ *
+ * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
+ * argument type specifiers:
+ *      - \%ll  - long long (uint64_t).
+ *      - \%L   - long long (uint64_t).
+ *      - \%l   - long (uint32_t, uint64_t)
+ *      - \%h   - short (int16_t).
+ *      - \%hh  - char (int8_t).
+ *      - \%H   - char (int8_t).
+ *      - \%z   - size_t.
+ *      - \%j   - intmax_t (int64_t).
+ *      - \%t   - ptrdiff_t.
+ * The type in parentheses is typical sizes, however when printing those types
+ * you are better off using the special group 2 format types below (\%RX32 and
+ * such).
+ *
+ *
+ * Group 0b, IPRT format tricks:
+ *      - %M    - Replaces the format string, takes a string pointer.
+ *      - %N    - Nested formatting, takes a pointer to a format string
+ *                followed by the pointer to a va_list variable.  The va_list
+ *                variable will not be modified and the caller must do va_end()
+ *                on it.  Make sure the va_list variable is NOT in a parameter
+ *                list or some gcc versions/targets may get it all wrong.
+ *
+ *
+ * Group 1, the basic runtime typedefs (excluding those which obviously are
+ * pointer):
+ *      - \%RTbool          - Takes a bool value and prints 'true', 'false', or '!%d!'.
+ *      - \%RTfile          - Takes a #RTFILE value.
+ *      - \%RTfmode         - Takes a #RTFMODE value.
+ *      - \%RTfoff          - Takes a #RTFOFF value.
+ *      - \%RTfp16          - Takes a #RTFAR16 value.
+ *      - \%RTfp32          - Takes a #RTFAR32 value.
+ *      - \%RTfp64          - Takes a #RTFAR64 value.
+ *      - \%RTgid           - Takes a #RTGID value.
+ *      - \%RTino           - Takes a #RTINODE value.
+ *      - \%RTint           - Takes a #RTINT value.
+ *      - \%RTiop           - Takes a #RTIOPORT value.
+ *      - \%RTldrm          - Takes a #RTLDRMOD value.
+ *      - \%RTmac           - Takes a #PCRTMAC pointer.
+ *      - \%RTnaddr         - Takes a #PCRTNETADDR value.
+ *      - \%RTnaipv4        - Takes a #RTNETADDRIPV4 value.
+ *      - \%RTnaipv6        - Takes a #PCRTNETADDRIPV6 value.
+ *      - \%RTnthrd         - Takes a #RTNATIVETHREAD value.
+ *      - \%RTnthrd         - Takes a #RTNATIVETHREAD value.
+ *      - \%RTproc          - Takes a #RTPROCESS value.
+ *      - \%RTptr           - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
+ *      - \%RTreg           - Takes a #RTCCUINTREG value.
+ *      - \%RTsel           - Takes a #RTSEL value.
+ *      - \%RTsem           - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
+ *      - \%RTsock          - Takes a #RTSOCKET value.
+ *      - \%RTthrd          - Takes a #RTTHREAD value.
+ *      - \%RTuid           - Takes a #RTUID value.
+ *      - \%RTuint          - Takes a #RTUINT value.
+ *      - \%RTunicp         - Takes a #RTUNICP value.
+ *      - \%RTutf16         - Takes a #RTUTF16 value.
+ *      - \%RTuuid          - Takes a #PCRTUUID and will print the UUID as a string.
+ *      - \%RTxuint         - Takes a #RTUINT or #RTINT value, formatting it as hex.
+ *      - \%RGi             - Takes a #RTGCINT value.
+ *      - \%RGp             - Takes a #RTGCPHYS value.
+ *      - \%RGr             - Takes a #RTGCUINTREG value.
+ *      - \%RGu             - Takes a #RTGCUINT value.
+ *      - \%RGv             - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
+ *      - \%RGx             - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
+ *      - \%RHi             - Takes a #RTHCINT value.
+ *      - \%RHp             - Takes a #RTHCPHYS value.
+ *      - \%RHr             - Takes a #RTHCUINTREG value.
+ *      - \%RHu             - Takes a #RTHCUINT value.
+ *      - \%RHv             - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
+ *      - \%RHx             - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
+ *      - \%RRv             - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
+ *      - \%RCi             - Takes a #RTINT value.
+ *      - \%RCp             - Takes a #RTCCPHYS value.
+ *      - \%RCr             - Takes a #RTCCUINTREG value.
+ *      - \%RCu             - Takes a #RTUINT value.
+ *      - \%RCv             - Takes a #uintptr_t, #intptr_t, void * value.
+ *      - \%RCx             - Takes a #RTUINT or #RTINT value, formatting it as hex.
+ *
+ *
+ * Group 2, the generic integer types which are prefered over relying on what
+ * bit-count a 'long', 'short',  or 'long long' has on a platform. This are
+ * highly prefered for the [u]intXX_t kind of types:
+ *      - \%RI[8|16|32|64]  - Signed integer value of the specifed bit count.
+ *      - \%RU[8|16|32|64]  - Unsigned integer value of the specifed bit count.
+ *      - \%RX[8|16|32|64]  - Hexadecimal integer value of the specifed bit count.
+ *
+ *
+ * Group 3, hex dumpers and other complex stuff which requires more than simple
+ * formatting:
+ *      - \%Rhxd            - Takes a pointer to the memory which is to be dumped in typical
+ *                            hex format. Use the precision to specify the length, and the width to
+ *                            set the number of bytes per line. Default width and precision is 16.
+ *      - \%Rhxs            - Takes a pointer to the memory to be displayed as a hex string,
+ *                            i.e. a series of space separated bytes formatted as two digit hex value.
+ *                            Use the precision to specify the length. Default length is 16 bytes.
+ *                            The width, if specified, is ignored.
+ *      - \%Rrc             - Takes an integer iprt status code as argument. Will insert the
+ *                            status code define corresponding to the iprt status code.
+ *      - \%Rrs             - Takes an integer iprt status code as argument. Will insert the
+ *                            short description of the specified status code.
+ *      - \%Rrf             - Takes an integer iprt status code as argument. Will insert the
+ *                            full description of the specified status code.
+ *      - \%Rra             - Takes an integer iprt status code as argument. Will insert the
+ *                            status code define + full description.
+ *      - \%Rwc             - Takes a long Windows error code as argument. Will insert the status
+ *                            code define corresponding to the Windows error code.
+ *      - \%Rwf             - Takes a long Windows error code as argument. Will insert the
+ *                            full description of the specified status code.
+ *      - \%Rwa             - Takes a long Windows error code as argument. Will insert the
+ *                            error code define + full description.
+ *
+ *      - \%Rhrc            - Takes a COM/XPCOM status code as argument. Will insert the status
+ *                            code define corresponding to the Windows error code.
+ *      - \%Rhrf            - Takes a COM/XPCOM status code as argument. Will insert the
+ *                            full description of the specified status code.
+ *      - \%Rhra            - Takes a COM/XPCOM error code as argument. Will insert the
+ *                            error code define + full description.
+ *
+ *      - \%Rfn             - Pretty printing of a function or method. It drops the
+ *                            return code and parameter list.
+ *      - \%Rbn             - Prints the base name.  For dropping the path in
+ *                            order to save space when printing a path name.
+ *
+ * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
+ *
+ *
+ * Group 4, structure dumpers:
+ *      - \%RDtimespec      - Takes a PCRTTIMESPEC.
+ *
+ *
+ * Group 5, XML / HTML escapers:
+ *      - \%RMas            - Takes a string pointer (const char *) and outputs
+ *                            it as an attribute value with the proper escaping.
+ *                            This typically ends up in double quotes.
+ *
+ *      - \%RMes            - Takes a string pointer (const char *) and outputs
+ *                            it as an element with the necessary escaping.
+ *
+ * Group 6, CPU Architecture Register dumpers:
+ *      - \%RAx86[reg]      - Takes a 64-bit register value if the register is
+ *                            64-bit or smaller.  Check the code wrt which
+ *                            registers are implemented.
+ *
+ */
+#ifndef DECLARED_FNRTSTROUTPUT          /* duplicated in iprt/log.h */
+# define DECLARED_FNRTSTROUTPUT
+/**
+ * Output callback.
+ *
+ * @returns number of bytes written.
+ * @param   pvArg       User argument.
+ * @param   pachChars   Pointer to an array of utf-8 characters.
+ * @param   cbChars     Number of bytes in the character array pointed to by pachChars.
+ */
+typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
+/** Pointer to callback function. */
+typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
+#endif
+/** Format flag.
+ * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
+ * that not all flags makes sense to both of the functions.
+ * @{ */
+#define RTSTR_F_CAPITAL         0x0001
+#define RTSTR_F_LEFT            0x0002
+#define RTSTR_F_ZEROPAD         0x0004
+#define RTSTR_F_SPECIAL         0x0008
+#define RTSTR_F_VALSIGNED       0x0010
+#define RTSTR_F_PLUS            0x0020
+#define RTSTR_F_BLANK           0x0040
+#define RTSTR_F_WIDTH           0x0080
+#define RTSTR_F_PRECISION       0x0100
+#define RTSTR_F_THOUSAND_SEP    0x0200
+#define RTSTR_F_BIT_MASK        0xf800
+#define RTSTR_F_8BIT            0x0800
+#define RTSTR_F_16BIT           0x1000
+#define RTSTR_F_32BIT           0x2000
+#define RTSTR_F_64BIT           0x4000
+#define RTSTR_F_128BIT          0x8000
+/** @} */
+/** @def RTSTR_GET_BIT_FLAG
+ * Gets the bit flag for the specified type.
+ */
+#define RTSTR_GET_BIT_FLAG(type) \
+    ( sizeof(type) * 8 == 32  ? RTSTR_F_32BIT \
+    : sizeof(type) * 8 == 64  ? RTSTR_F_64BIT \
+    : sizeof(type) * 8 == 16  ? RTSTR_F_16BIT \
+    : sizeof(type) * 8 == 8   ? RTSTR_F_8BIT \
+    : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
+    : 0)
+/**
+ * Callback to format non-standard format specifiers.
+ *
+ * @returns The number of bytes formatted.
+ * @param   pvArg           Formatter argument.
+ * @param   pfnOutput       Pointer to output function.
+ * @param   pvArgOutput     Argument for the output function.
+ * @param   ppszFormat      Pointer to the format string pointer. Advance this till the char
+ *                          after the format specifier.
+ * @param   pArgs           Pointer to the argument list. Use this to fetch the arguments.
+ * @param   cchWidth        Format Width. -1 if not specified.
+ * @param   cchPrecision    Format Precision. -1 if not specified.
+ * @param   fFlags          Flags (RTSTR_NTFS_*).
+ * @param   chArgSize       The argument size specifier, 'l' or 'L'.
+ */
+typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
+                                         const char **ppszFormat, va_list *pArgs, int cchWidth,
+                                         int cchPrecision, unsigned fFlags, char chArgSize);
+/** Pointer to a FNSTRFORMAT() function. */
+typedef FNSTRFORMAT *PFNSTRFORMAT;
+/**
+ * Partial implementation of a printf like formatter.
+ * It doesn't do everything correct, and there is no floating point support.
+ * However, it supports custom formats by the means of a format callback.
+ *
+ * @returns number of bytes formatted.
+ * @param   pfnOutput   Output worker.
+ *                      Called in two ways. Normally with a string and its length.
+ *                      For termination, it's called with NULL for string, 0 for length.
+ * @param   pvArgOutput Argument to the output worker.
+ * @param   pfnFormat   Custom format worker.
+ * @param   pvArgFormat Argument to the format worker.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   InArgs      Argument list.
+ */
+RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
+                            const char *pszFormat, va_list InArgs) RT_IPRT_FORMAT_ATTR(5, 0);
+/**
+ * Partial implementation of a printf like formatter.
+ * It doesn't do everything correct, and there is no floating point support.
+ * However, it supports custom formats by the means of a format callback.
+ *
+ * @returns number of bytes formatted.
+ * @param   pfnOutput   Output worker.
+ *                      Called in two ways. Normally with a string and its length.
+ *                      For termination, it's called with NULL for string, 0 for length.
+ * @param   pvArgOutput Argument to the output worker.
+ * @param   pfnFormat   Custom format worker.
+ * @param   pvArgFormat Argument to the format worker.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         Argument list.
+ */
+RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
+                           const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
+/**
+ * Formats an integer number according to the parameters.
+ *
+ * @returns Length of the formatted number.
+ * @param   psz             Pointer to output string buffer of sufficient size.
+ * @param   u64Value        Value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision,
+                              unsigned int fFlags);
+/**
+ * Formats an unsigned 8-bit number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   u8Value         The value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatU8(char *pszBuf, size_t cbBuf, uint8_t u8Value, unsigned int uiBase,
+                              signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an unsigned 16-bit number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   u16Value        The value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatU16(char *pszBuf, size_t cbBuf, uint16_t u16Value, unsigned int uiBase,
+                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an unsigned 32-bit number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   u32Value        The value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatU32(char *pszBuf, size_t cbBuf, uint32_t u32Value, unsigned int uiBase,
+                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an unsigned 64-bit number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   u64Value        The value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatU64(char *pszBuf, size_t cbBuf, uint64_t u64Value, unsigned int uiBase,
+                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an unsigned 128-bit number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   pu128Value      The value to format.
+ * @param   uiBase          Number representation base.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatU128(char *pszBuf, size_t cbBuf, PCRTUINT128U pu128Value, unsigned int uiBase,
+                                signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an 80-bit extended floating point number.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   pr80Value       The value to format.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatR80(char *pszBuf, size_t cbBuf, PCRTFLOAT80U pr80Value, signed int cchWidth,
+                               signed int cchPrecision, uint32_t fFlags);
+/**
+ * Formats an 80-bit extended floating point number, version 2.
+ *
+ * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
+ * @param   pszBuf          The output buffer.
+ * @param   cbBuf           The size of the output buffer.
+ * @param   pr80Value       The value to format.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags, RTSTR_F_XXX.
+ */
+RTDECL(ssize_t) RTStrFormatR80u2(char *pszBuf, size_t cbBuf, PCRTFLOAT80U2 pr80Value, signed int cchWidth,
+                                 signed int cchPrecision, uint32_t fFlags);
+/**
+ * Callback for formatting a type.
+ *
+ * This is registered using the RTStrFormatTypeRegister function and will
+ * be called during string formatting to handle the specified %R[type].
+ * The argument for this format type is assumed to be a pointer and it's
+ * passed in the @a pvValue argument.
+ *
+ * @returns Length of the formatted output.
+ * @param   pfnOutput       Output worker.
+ * @param   pvArgOutput     Argument to the output worker.
+ * @param   pszType         The type name.
+ * @param   pvValue         The argument value.
+ * @param   cchWidth        Width.
+ * @param   cchPrecision    Precision.
+ * @param   fFlags          Flags (NTFS_*).
+ * @param   pvUser          The user argument.
+ */
+typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
+                                               const char *pszType, void const *pvValue,
+                                               int cchWidth, int cchPrecision, unsigned fFlags,
+                                               void *pvUser);
+/** Pointer to a FNRTSTRFORMATTYPE. */
+typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
+/**
+ * Register a format handler for a type.
+ *
+ * The format handler is used to handle '%R[type]' format types, where the argument
+ * in the vector is a pointer value (a bit restrictive, but keeps it simple).
+ *
+ * The caller must ensure that no other thread will be making use of any of
+ * the dynamic formatting type facilities simultaneously with this call.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_ALREADY_EXISTS if the type has already been registered.
+ * @retval  VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
+ *
+ * @param   pszType         The type name.
+ * @param   pfnHandler      The handler address. See FNRTSTRFORMATTYPE for details.
+ * @param   pvUser          The user argument to pass to the handler. See RTStrFormatTypeSetUser
+ *                          for how to update this later.
+ */
+RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
+/**
+ * Deregisters a format type.
+ *
+ * The caller must ensure that no other thread will be making use of any of
+ * the dynamic formatting type facilities simultaneously with this call.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_FILE_NOT_FOUND if not found.
+ *
+ * @param   pszType     The type to deregister.
+ */
+RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
+/**
+ * Sets the user argument for a type.
+ *
+ * This can be used if a user argument needs relocating in GC.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_FILE_NOT_FOUND if not found.
+ *
+ * @param   pszType     The type to update.
+ * @param   pvUser      The new user argument value.
+ */
+RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
+/**
+ * String printf.
+ *
+ * @returns The length of the returned string (in pszBuffer) excluding the
+ *          terminator.
+ * @param   pszBuffer   Output buffer.
+ * @param   cchBuffer   Size of the output buffer.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ */
+RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
+/**
+ * String printf.
+ *
+ * @returns The length of the returned string (in pszBuffer) excluding the
+ *          terminator.
+ * @param   pszBuffer   Output buffer.
+ * @param   cchBuffer   Size of the output buffer.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
+/**
+ * String printf with custom formatting.
+ *
+ * @returns The length of the returned string (in pszBuffer) excluding the
+ *          terminator.
+ * @param   pfnFormat   Pointer to handler function for the custom formats.
+ * @param   pvArg       Argument to the pfnFormat function.
+ * @param   pszBuffer   Output buffer.
+ * @param   cchBuffer   Size of the output buffer.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ */
+RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
+                              const char *pszFormat, va_list args)  RT_IPRT_FORMAT_ATTR(5, 0);
+/**
+ * String printf with custom formatting.
+ *
+ * @returns The length of the returned string (in pszBuffer) excluding the
+ *          terminator.
+ * @param   pfnFormat   Pointer to handler function for the custom formats.
+ * @param   pvArg       Argument to the pfnFormat function.
+ * @param   pszBuffer   Output buffer.
+ * @param   cchBuffer   Size of the output buffer.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
+                             const char *pszFormat, ...)  RT_IPRT_FORMAT_ATTR(5, 6);
+/**
+ * Allocating string printf (default tag).
+ *
+ * @returns The length of the string in the returned *ppszBuffer excluding the
+ *          terminator.
+ * @returns -1 on failure.
+ * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
+ *                      The buffer should be freed using RTStrFree().
+ *                      On failure *ppszBuffer will be set to NULL.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ */
+#define RTStrAPrintfV(ppszBuffer, pszFormat, args)      RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
+/**
+ * Allocating string printf (custom tag).
+ *
+ * @returns The length of the string in the returned *ppszBuffer excluding the
+ *          terminator.
+ * @returns -1 on failure.
+ * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
+ *                      The buffer should be freed using RTStrFree().
+ *                      On failure *ppszBuffer will be set to NULL.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ * @param   pszTag      Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer, const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(2, 0);
+/**
+ * Allocating string printf.
+ *
+ * @returns The length of the string in the returned *ppszBuffer excluding the
+ *          terminator.
+ * @returns -1 on failure.
+ * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
+ *                      The buffer should be freed using RTStrFree().
+ *                      On failure *ppszBuffer will be set to NULL.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...)
+{
+    int     cbRet;
+    va_list va;
+    va_start(va, pszFormat);
+    cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, RTSTR_TAG);
+    va_end(va);
+    return cbRet;
+}
+/**
+ * Allocating string printf (custom tag).
+ *
+ * @returns The length of the string in the returned *ppszBuffer excluding the
+ *          terminator.
+ * @returns -1 on failure.
+ * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
+ *                      The buffer should be freed using RTStrFree().
+ *                      On failure *ppszBuffer will be set to NULL.
+ * @param   pszTag      Allocation tag used for statistics and such.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer, const char *pszTag, const char *pszFormat, ...)
+{
+    int     cbRet;
+    va_list va;
+    va_start(va, pszFormat);
+    cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, pszTag);
+    va_end(va);
+    return cbRet;
+}
+/**
+ * Allocating string printf, version 2.
+ *
+ * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
+ *          memory.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ */
+#define RTStrAPrintf2V(pszFormat, args)     RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
+/**
+ * Allocating string printf, version 2.
+ *
+ * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
+ *          memory.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   args        The format argument.
+ * @param   pszTag      Allocation tag used for statistics and such.
+ */
+RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(1, 0);
+/**
+ * Allocating string printf, version 2 (default tag).
+ *
+ * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
+ *          memory.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat, ...)
+{
+    char   *pszRet;
+    va_list va;
+    va_start(va, pszFormat);
+    pszRet = RTStrAPrintf2VTag(pszFormat, va, RTSTR_TAG);
+    va_end(va);
+    return pszRet;
+}
+/**
+ * Allocating string printf, version 2 (custom tag).
+ *
+ * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
+ *          memory.
+ * @param   pszTag      Allocation tag used for statistics and such.
+ * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
+ * @param   ...         The format argument.
+ */
+DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag, const char *pszFormat, ...)
+{
+    char   *pszRet;
+    va_list va;
+    va_start(va, pszFormat);
+    pszRet = RTStrAPrintf2VTag(pszFormat, va, pszTag);
+    va_end(va);
+    return pszRet;
+}
+/**
+ * Strips blankspaces from both ends of the string.
+ *
+ * @returns Pointer to first non-blank char in the string.
+ * @param   psz     The string to strip.
+ */
+RTDECL(char *) RTStrStrip(char *psz);
+/**
+ * Strips blankspaces from the start of the string.
+ *
+ * @returns Pointer to first non-blank char in the string.
+ * @param   psz     The string to strip.
+ */
+RTDECL(char *) RTStrStripL(const char *psz);
+/**
+ * Strips blankspaces from the end of the string.
+ *
+ * @returns psz.
+ * @param   psz     The string to strip.
+ */
+RTDECL(char *) RTStrStripR(char *psz);
+/**
+ * String copy with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pszDst              The destination buffer.
+ * @param   cbDst               The size of the destination buffer (in bytes).
+ * @param   pszSrc              The source string.  NULL is not OK.
+ */
+RTDECL(int) RTStrCopy(char *pszDst, size_t cbDst, const char *pszSrc);
+/**
+ * String copy with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pszDst              The destination buffer.
+ * @param   cbDst               The size of the destination buffer (in bytes).
+ * @param   pszSrc              The source string.  NULL is not OK.
+ * @param   cchSrcMax           The maximum number of chars (not code points) to
+ *                              copy from the source string, not counting the
+ *                              terminator as usual.
+ */
+RTDECL(int) RTStrCopyEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
+/**
+ * String copy with overflow handling and buffer advancing.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   ppszDst             Pointer to the destination buffer pointer.
+ *                              This will be advanced to the end of the copied
+ *                              bytes (points at the terminator).  This is also
+ *                              updated on overflow.
+ * @param   pcbDst              Pointer to the destination buffer size
+ *                              variable.  This will be updated in accord with
+ *                              the buffer pointer.
+ * @param   pszSrc              The source string.  NULL is not OK.
+ */
+RTDECL(int) RTStrCopyP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
+/**
+ * String copy with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   ppszDst             Pointer to the destination buffer pointer.
+ *                              This will be advanced to the end of the copied
+ *                              bytes (points at the terminator).  This is also
+ *                              updated on overflow.
+ * @param   pcbDst              Pointer to the destination buffer size
+ *                              variable.  This will be updated in accord with
+ *                              the buffer pointer.
+ * @param   pszSrc              The source string.  NULL is not OK.
+ * @param   cchSrcMax           The maximum number of chars (not code points) to
+ *                              copy from the source string, not counting the
+ *                              terminator as usual.
+ */
+RTDECL(int) RTStrCopyPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
+/**
+ * String concatenation with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pszDst              The destination buffer.
+ * @param   cbDst               The size of the destination buffer (in bytes).
+ * @param   pszSrc              The source string.  NULL is not OK.
+ */
+RTDECL(int) RTStrCat(char *pszDst, size_t cbDst, const char *pszSrc);
+/**
+ * String concatenation with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pszDst              The destination buffer.
+ * @param   cbDst               The size of the destination buffer (in bytes).
+ * @param   pszSrc              The source string.  NULL is not OK.
+ * @param   cchSrcMax           The maximum number of chars (not code points) to
+ *                              copy from the source string, not counting the
+ *                              terminator as usual.
+ */
+RTDECL(int) RTStrCatEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
+/**
+ * String concatenation with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   ppszDst             Pointer to the destination buffer pointer.
+ *                              This will be advanced to the end of the copied
+ *                              bytes (points at the terminator).  This is also
+ *                              updated on overflow.
+ * @param   pcbDst              Pointer to the destination buffer size
+ *                              variable.  This will be updated in accord with
+ *                              the buffer pointer.
+ * @param   pszSrc              The source string.  NULL is not OK.
+ */
+RTDECL(int) RTStrCatP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
+/**
+ * String concatenation with overflow handling and buffer advancing.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   ppszDst             Pointer to the destination buffer pointer.
+ *                              This will be advanced to the end of the copied
+ *                              bytes (points at the terminator).  This is also
+ *                              updated on overflow.
+ * @param   pcbDst              Pointer to the destination buffer size
+ *                              variable.  This will be updated in accord with
+ *                              the buffer pointer.
+ * @param   pszSrc              The source string.  NULL is not OK.
+ * @param   cchSrcMax           The maximum number of chars (not code points) to
+ *                              copy from the source string, not counting the
+ *                              terminator as usual.
+ */
+RTDECL(int) RTStrCatPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
+/**
+ * Performs a case sensitive string compare between two UTF-8 strings.
+ *
+ * Encoding errors are ignored by the current implementation. So, the only
+ * difference between this and the CRT strcmp function is the handling of
+ * NULL arguments.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   psz1        First UTF-8 string. Null is allowed.
+ * @param   psz2        Second UTF-8 string. Null is allowed.
+ */
+RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
+/**
+ * Performs a case sensitive string compare between two UTF-8 strings, given
+ * a maximum string length.
+ *
+ * Encoding errors are ignored by the current implementation. So, the only
+ * difference between this and the CRT strncmp function is the handling of
+ * NULL arguments.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   psz1        First UTF-8 string. Null is allowed.
+ * @param   psz2        Second UTF-8 string. Null is allowed.
+ * @param   cchMax      The maximum string length
+ */
+RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
+/**
+ * Performs a case insensitive string compare between two UTF-8 strings.
+ *
+ * This is a simplified compare, as only the simplified lower/upper case folding
+ * specified by the unicode specs are used. It does not consider character pairs
+ * as they are used in some languages, just simple upper & lower case compares.
+ *
+ * The result is the difference between the mismatching codepoints after they
+ * both have been lower cased.
+ *
+ * If the string encoding is invalid the function will assert (strict builds)
+ * and use RTStrCmp for the remainder of the string.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   psz1        First UTF-8 string. Null is allowed.
+ * @param   psz2        Second UTF-8 string. Null is allowed.
+ */
+RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
+/**
+ * Performs a case insensitive string compare between two UTF-8 strings, given a
+ * maximum string length.
+ *
+ * This is a simplified compare, as only the simplified lower/upper case folding
+ * specified by the unicode specs are used. It does not consider character pairs
+ * as they are used in some languages, just simple upper & lower case compares.
+ *
+ * The result is the difference between the mismatching codepoints after they
+ * both have been lower cased.
+ *
+ * If the string encoding is invalid the function will assert (strict builds)
+ * and use RTStrCmp for the remainder of the string.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   psz1        First UTF-8 string. Null is allowed.
+ * @param   psz2        Second UTF-8 string. Null is allowed.
+ * @param   cchMax      Maximum string length
+ */
+RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
+/**
+ * Locates a case sensitive substring.
+ *
+ * If any of the two strings are NULL, then NULL is returned. If the needle is
+ * an empty string, then the haystack is returned (i.e. matches anything).
+ *
+ * @returns Pointer to the first occurrence of the substring if found, NULL if
+ *          not.
+ *
+ * @param   pszHaystack The string to search.
+ * @param   pszNeedle   The substring to search for.
+ *
+ * @remarks The difference between this and strstr is the handling of NULL
+ *          pointers.
+ */
+RTDECL(char *) RTStrStr(const char *pszHaystack, const char *pszNeedle);
+/**
+ * Locates a case insensitive substring.
+ *
+ * If any of the two strings are NULL, then NULL is returned. If the needle is
+ * an empty string, then the haystack is returned (i.e. matches anything).
+ *
+ * @returns Pointer to the first occurrence of the substring if found, NULL if
+ *          not.
+ *
+ * @param   pszHaystack The string to search.
+ * @param   pszNeedle   The substring to search for.
+ *
+ */
+RTDECL(char *) RTStrIStr(const char *pszHaystack, const char *pszNeedle);
+/**
+ * Converts the string to lower case.
+ *
+ * @returns Pointer to the converted string.
+ * @param   psz     The string to convert.
+ */
+RTDECL(char *) RTStrToLower(char *psz);
+/**
+ * Converts the string to upper case.
+ *
+ * @returns Pointer to the converted string.
+ * @param   psz     The string to convert.
+ */
+RTDECL(char *) RTStrToUpper(char *psz);
+/**
+ * Checks if the string is case foldable, i.e. whether it would change if
+ * subject to RTStrToLower or RTStrToUpper.
+ *
+ * @returns true / false
+ * @param   psz     The string in question.
+ */
+RTDECL(bool) RTStrIsCaseFoldable(const char *psz);
+/**
+ * Checks if the string is upper cased (no lower case chars in it).
+ *
+ * @returns true / false
+ * @param   psz     The string in question.
+ */
+RTDECL(bool) RTStrIsUpperCased(const char *psz);
+/**
+ * Checks if the string is lower cased (no upper case chars in it).
+ *
+ * @returns true / false
+ * @param   psz     The string in question.
+ */
+RTDECL(bool) RTStrIsLowerCased(const char *psz);
+/**
+ * Find the length of a zero-terminated byte string, given
+ * a max string length.
+ *
+ * See also RTStrNLenEx.
+ *
+ * @returns The string length or cbMax. The returned length does not include
+ *          the zero terminator if it was found.
+ *
+ * @param   pszString   The string.
+ * @param   cchMax      The max string length.
+ */
+RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
+/**
+ * Find the length of a zero-terminated byte string, given
+ * a max string length.
+ *
+ * See also RTStrNLen.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS if the string has a length less than cchMax.
+ * @retval  VERR_BUFFER_OVERFLOW if the end of the string wasn't found
+ *          before cchMax was reached.
+ *
+ * @param   pszString   The string.
+ * @param   cchMax      The max string length.
+ * @param   pcch        Where to store the string length excluding the
+ *                      terminator. This is set to cchMax if the terminator
+ *                      isn't found.
+ */
+RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
+RT_C_DECLS_END
+/** The maximum size argument of a memchr call. */
+#define RTSTR_MEMCHR_MAX            ((~(size_t)0 >> 1) - 15)
+/**
+ * Find the zero terminator in a string with a limited length.
+ *
+ * @returns Pointer to the zero terminator.
+ * @returns NULL if the zero terminator was not found.
+ *
+ * @param   pszString   The string.
+ * @param   cchMax      The max string length.  RTSTR_MAX is fine.
+ */
+#if defined(__cplusplus) && !defined(DOXYGEN_RUNNING)
+DECLINLINE(char const *) RTStrEnd(char const *pszString, size_t cchMax)
+{
+    /* Avoid potential issues with memchr seen in glibc.
+     * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
+    while (cchMax > RTSTR_MEMCHR_MAX)
+    {
+        char const *pszRet = (char const *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
+        if (RT_LIKELY(pszRet))
+            return pszRet;
+        pszString += RTSTR_MEMCHR_MAX;
+        cchMax    -= RTSTR_MEMCHR_MAX;
+    }
+    return (char const *)memchr(pszString, '\0', cchMax);
+}
+DECLINLINE(char *) RTStrEnd(char *pszString, size_t cchMax)
+#else
+DECLINLINE(char *) RTStrEnd(const char *pszString, size_t cchMax)
+#endif
+{
+    /* Avoid potential issues with memchr seen in glibc.
+     * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
+    while (cchMax > RTSTR_MEMCHR_MAX)
+    {
+        char *pszRet = (char *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
+        if (RT_LIKELY(pszRet))
+            return pszRet;
+        pszString += RTSTR_MEMCHR_MAX;
+        cchMax    -= RTSTR_MEMCHR_MAX;
+    }
+    return (char *)memchr(pszString, '\0', cchMax);
+}
+RT_C_DECLS_BEGIN
+/**
+ * Finds the offset at which a simple character first occurs in a string.
+ *
+ * @returns The offset of the first occurence or the terminator offset.
+ * @param   pszHaystack The string to search.
+ * @param   chNeedle    The character to search for.
+ */
+DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack, char chNeedle)
+{
+    const char *psz = pszHaystack;
+    char ch;
+    while (   (ch = *psz) != chNeedle
+           && ch != '\0')
+        psz++;
+    return psz - pszHaystack;
+}
+/**
+ * Matches a simple string pattern.
+ *
+ * @returns true if the string matches the pattern, otherwise false.
+ *
+ * @param  pszPattern   The pattern. Special chars are '*' and '?', where the
+ *                      asterisk matches zero or more characters and question
+ *                      mark matches exactly one character.
+ * @param  pszString    The string to match against the pattern.
+ */
+RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
+/**
+ * Matches a simple string pattern, neither which needs to be zero terminated.
+ *
+ * This is identical to RTStrSimplePatternMatch except that you can optionally
+ * specify the length of both the pattern and the string.  The function will
+ * stop when it hits a string terminator or either of the lengths.
+ *
+ * @returns true if the string matches the pattern, otherwise false.
+ *
+ * @param  pszPattern   The pattern. Special chars are '*' and '?', where the
+ *                      asterisk matches zero or more characters and question
+ *                      mark matches exactly one character.
+ * @param  cchPattern   The pattern length. Pass RTSTR_MAX if you don't know the
+ *                      length and wish to stop at the string terminator.
+ * @param  pszString    The string to match against the pattern.
+ * @param  cchString    The string length. Pass RTSTR_MAX if you don't know the
+ *                      length and wish to match up to the string terminator.
+ */
+RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
+                                      const char *pszString, size_t cchString);
+/**
+ * Matches multiple patterns against a string.
+ *
+ * The patterns are separated by the pipe character (|).
+ *
+ * @returns true if the string matches the pattern, otherwise false.
+ *
+ * @param   pszPatterns The patterns.
+ * @param   cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
+ *                      stop at the terminator.
+ * @param   pszString   The string to match against the pattern.
+ * @param   cchString   The string length. Pass RTSTR_MAX stop stop at the
+ *                      terminator.
+ * @param   poffPattern Offset into the patterns string of the patttern that
+ *                      matched. If no match, this will be set to RTSTR_MAX.
+ *                      This is optional, NULL is fine.
+ */
+RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
+                                          const char *pszString, size_t cchString,
+                                          size_t *poffPattern);
+/**
+ * Compares two version strings RTStrICmp fashion.
+ *
+ * The version string is split up into sections at punctuation, spaces,
+ * underscores, dashes and plus signs.  The sections are then split up into
+ * numeric and string sub-sections.  Finally, the sub-sections are compared
+ * in a numeric or case insesntivie fashion depending on what they are.
+ *
+ * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
+ * "1".  These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ *
+ * @param   pszVer1     First version string to compare.
+ * @param   pszVer2     Second version string to compare first version with.
+ */
+RTDECL(int) RTStrVersionCompare(const char *pszVer1, const char *pszVer2);
+/** @defgroup rt_str_conv   String To/From Number Conversions
+ * @{ */
+/**
+ * Converts a string representation of a number to a 64-bit unsigned number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu64        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
+/**
+ * Converts a string representation of a number to a 64-bit unsigned number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_TRAILING_CHARS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu64        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
+/**
+ * Converts a string representation of a number to a 64-bit unsigned number.
+ * The base is guessed.
+ *
+ * @returns 64-bit unsigned number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 32-bit unsigned number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu32        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
+/**
+ * Converts a string representation of a number to a 32-bit unsigned number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_TRAILING_CHARS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu32        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
+/**
+ * Converts a string representation of a number to a 64-bit unsigned number.
+ * The base is guessed.
+ *
+ * @returns 32-bit unsigned number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 16-bit unsigned number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu16        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
+/**
+ * Converts a string representation of a number to a 16-bit unsigned number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_TRAILING_CHARS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu16        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
+/**
+ * Converts a string representation of a number to a 16-bit unsigned number.
+ * The base is guessed.
+ *
+ * @returns 16-bit unsigned number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 8-bit unsigned number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu8         Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
+/**
+ * Converts a string representation of a number to a 8-bit unsigned number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_NEGATIVE_UNSIGNED
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_TRAILING_CHARS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pu8         Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
+/**
+ * Converts a string representation of a number to a 8-bit unsigned number.
+ * The base is guessed.
+ *
+ * @returns 8-bit unsigned number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 64-bit signed number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi64        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
+/**
+ * Converts a string representation of a number to a 64-bit signed number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_TRAILING_CHARS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi64        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
+/**
+ * Converts a string representation of a number to a 64-bit signed number.
+ * The base is guessed.
+ *
+ * @returns 64-bit signed number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(int64_t) RTStrToInt64(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 32-bit signed number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi32        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
+/**
+ * Converts a string representation of a number to a 32-bit signed number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_TRAILING_CHARS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi32        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
+/**
+ * Converts a string representation of a number to a 32-bit signed number.
+ * The base is guessed.
+ *
+ * @returns 32-bit signed number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(int32_t) RTStrToInt32(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 16-bit signed number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi16        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
+/**
+ * Converts a string representation of a number to a 16-bit signed number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_TRAILING_CHARS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   uBase       The base of the representation used.
+ *                      If 0 the function will look for known prefixes before defaulting to 10.
+ * @param   pi16        Where to store the converted number. (optional)
+ */
+RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
+/**
+ * Converts a string representation of a number to a 16-bit signed number.
+ * The base is guessed.
+ *
+ * @returns 16-bit signed number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(int16_t) RTStrToInt16(const char *pszValue);
+/**
+ * Converts a string representation of a number to a 8-bit signed number.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
+ * @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)
+ */
+RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
+/**
+ * Converts a string representation of a number to a 8-bit signed number,
+ * making sure the full string is converted.
+ *
+ * @returns iprt status code.
+ *          Warnings are used to indicate conversion problems.
+ * @retval  VWRN_NUMBER_TOO_BIG
+ * @retval  VINF_SUCCESS
+ * @retval  VERR_TRAILING_CHARS
+ * @retval  VERR_TRAILING_SPACES
+ * @retval  VERR_NO_DIGITS
+ *
+ * @param   pszValue    Pointer to the string value.
+ * @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)
+ */
+RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
+/**
+ * Converts a string representation of a number to a 8-bit signed number.
+ * The base is guessed.
+ *
+ * @returns 8-bit signed number on success.
+ * @returns 0 on failure.
+ * @param   pszValue    Pointer to the string value.
+ */
+RTDECL(int8_t) RTStrToInt8(const char *pszValue);
+/**
+ * Formats a buffer stream as hex bytes.
+ *
+ * The default is no separating spaces or line breaks or anything.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
+ *
+ * @param   pszBuf      Output string buffer.
+ * @param   cchBuf      The size of the output buffer.
+ * @param   pv          Pointer to the bytes to stringify.
+ * @param   cb          The number of bytes to stringify.
+ * @param   fFlags      Combination of RTSTRPRINTHEXBYTES_F_XXX values.
+ * @sa      RTUtf16PrintHexBytes.
+ */
+RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cchBuf, void const *pv, size_t cb, uint32_t fFlags);
+/** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
+ * @{ */
+/** Upper case hex digits, the default is lower case. */
+#define RTSTRPRINTHEXBYTES_F_UPPER      RT_BIT(0)
+/** @} */
+/**
+ * Converts a string of hex bytes back into binary data.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
+ * @retval  VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
+ * @retval  VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
+ *          the output buffer.
+ * @retval  VERR_UNEVEN_INPUT if the input contains a half byte.
+ * @retval  VERR_NO_DIGITS
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ *
+ * @param   pszHex      The string containing the hex bytes.
+ * @param   pv          Output buffer.
+ * @param   cb          The size of the output buffer.
+ * @param   fFlags      Must be zero, reserved for future use.
+ */
+RTDECL(int) RTStrConvertHexBytes(char const *pszHex, void *pv, size_t cb, uint32_t fFlags);
+/** @} */
+/** @defgroup rt_str_space  Unique String Space
+ * @{
+ */
+/** Pointer to a string name space container node core. */
+typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
+/** Pointer to a pointer to a string name space container node core. */
+typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
+/**
+ * String name space container node core.
+ */
+typedef struct RTSTRSPACECORE
+{
+    /** Hash key. Don't touch. */
+    uint32_t        Key;
+    /** Pointer to the left leaf node. Don't touch. */
+    PRTSTRSPACECORE pLeft;
+    /** Pointer to the left right node. Don't touch. */
+    PRTSTRSPACECORE pRight;
+    /** Pointer to the list of string with the same key. Don't touch. */
+    PRTSTRSPACECORE pList;
+    /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
+    unsigned char   uchHeight;
+    /** The string length. Read only! */
+    size_t          cchString;
+    /** Pointer to the string. Read only! */
+    const char     *pszString;
+} RTSTRSPACECORE;
+/** String space. (Initialize with NULL.) */
+typedef PRTSTRSPACECORE     RTSTRSPACE;
+/** Pointer to a string space. */
+typedef PPRTSTRSPACECORE    PRTSTRSPACE;
+/**
+ * Inserts a string into a unique string space.
+ *
+ * @returns true on success.
+ * @returns false if the string collided with an existing string.
+ * @param   pStrSpace       The space to insert it into.
+ * @param   pStr            The string node.
+ */
+RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
+/**
+ * Removes a string from a unique string space.
+ *
+ * @returns Pointer to the removed string node.
+ * @returns NULL if the string was not found in the string space.
+ * @param   pStrSpace       The space to remove it from.
+ * @param   pszString       The string to remove.
+ */
+RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
+/**
+ * Gets a string from a unique string space.
+ *
+ * @returns Pointer to the string node.
+ * @returns NULL if the string was not found in the string space.
+ * @param   pStrSpace       The space to get it from.
+ * @param   pszString       The string to get.
+ */
+RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
+/**
+ * Gets a string from a unique string space.
+ *
+ * @returns Pointer to the string node.
+ * @returns NULL if the string was not found in the string space.
+ * @param   pStrSpace       The space to get it from.
+ * @param   pszString       The string to get.
+ * @param   cchMax          The max string length to evaluate.  Passing
+ *                          RTSTR_MAX is ok and makes it behave just like
+ *                          RTStrSpaceGet.
+ */
+RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax);
+/**
+ * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
+ *
+ * @returns 0 on continue.
+ * @returns Non-zero to aborts the operation.
+ * @param   pStr        The string node
+ * @param   pvUser      The user specified argument.
+ */
+typedef DECLCALLBACK(int)   FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
+/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
+typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
+/**
+ * Destroys the string space.
+ *
+ * The caller supplies a callback which will be called for each of the string
+ * nodes in for freeing their memory and other resources.
+ *
+ * @returns 0 or what ever non-zero return value pfnCallback returned
+ *          when aborting the destruction.
+ * @param   pStrSpace       The space to destroy.
+ * @param   pfnCallback     The callback.
+ * @param   pvUser          The user argument.
+ */
+RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
+/**
+ * Enumerates the string space.
+ * The caller supplies a callback which will be called for each of
+ * the string nodes.
+ *
+ * @returns 0 or what ever non-zero return value pfnCallback returned
+ *          when aborting the destruction.
+ * @param   pStrSpace       The space to enumerate.
+ * @param   pfnCallback     The callback.
+ * @param   pvUser          The user argument.
+ */
+RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
+/** @} */
+/** @defgroup rt_str_hash       Sting hashing
+ * @{ */
+/**
+ * Hashes the given string using algorithm \#1.
+ *
+ * @returns String hash.
+ * @param   pszString       The string to hash.
+ */
+RTDECL(uint32_t)    RTStrHash1(const char *pszString);
+/**
+ * Hashes the given string using algorithm \#1.
+ *
+ * @returns String hash.
+ * @param   pszString       The string to hash.
+ * @param   cchString       The max length to hash. Hashing will stop if the
+ *                          terminator character is encountered first. Passing
+ *                          RTSTR_MAX is fine.
+ */
+RTDECL(uint32_t)    RTStrHash1N(const char *pszString, size_t cchString);
+/**
+ * Hashes the given strings as if they were concatenated using algorithm \#1.
+ *
+ * @returns String hash.
+ * @param   cPairs          The number of string / length pairs in the
+ *                          ellipsis.
+ * @param   ...             List of string (const char *) and length
+ *                          (size_t) pairs.  Passing RTSTR_MAX as the size is
+ *                          fine.
+ */
+RTDECL(uint32_t)    RTStrHash1ExN(size_t cPairs, ...);
+/**
+ * Hashes the given strings as if they were concatenated using algorithm \#1.
+ *
+ * @returns String hash.
+ * @param   cPairs          The number of string / length pairs in the @a va.
+ * @param   va              List of string (const char *) and length
+ *                          (size_t) pairs.  Passing RTSTR_MAX as the size is
+ *                          fine.
+ */
+RTDECL(uint32_t)    RTStrHash1ExNV(size_t cPairs, va_list va);
+/** @}  */
+/** @defgroup rt_str_utf16      UTF-16 String Manipulation
+ * @{
+ */
+/**
+ * Allocates memory for UTF-16 string storage (default tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @returns Pointer to the allocated UTF-16 string.  The first wide char is
+ *          always set to the string terminator char, the contents of the
+ *          remainder of the memory is undefined.  The string must be freed by
+ *          calling RTUtf16Free.
+ *
+ *          NULL is returned if the allocation failed.  Please translate this to
+ *          VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY.  Also consider
+ *          RTUtf16AllocEx if an IPRT status code is required.
+ *
+ * @param   cb                  How many bytes to allocate, will be rounded up
+ *                              to a multiple of two. If this is zero, we will
+ *                              allocate a terminator wide char anyway.
+ */
+#define RTUtf16Alloc(cb)                    RTUtf16AllocTag((cb), RTSTR_TAG)
+/**
+ * Allocates memory for UTF-16 string storage (custom tag).
+ *
+ * You should normally not use this function, except if there is some very
+ * custom string handling you need doing that isn't covered by any of the other
+ * APIs.
+ *
+ * @returns Pointer to the allocated UTF-16 string.  The first wide char is
+ *          always set to the string terminator char, the contents of the
+ *          remainder of the memory is undefined.  The string must be freed by
+ *          calling RTUtf16Free.
+ *
+ *          NULL is returned if the allocation failed.  Please translate this to
+ *          VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY.  Also consider
+ *          RTUtf16AllocExTag if an IPRT status code is required.
+ *
+ * @param   cb                  How many bytes to allocate, will be rounded up
+ *                              to a multiple of two. If this is zero, we will
+ *                              allocate a terminator wide char anyway.
+ * @param   pszTag              Allocation tag used for statistics and such.
+ */
+RTDECL(PRTUTF16) RTUtf16AllocTag(size_t cb, const char *pszTag);
+/**
+ * Free a UTF-16 string allocated by RTStrToUtf16(), RTStrToUtf16Ex(),
+ * RTLatin1ToUtf16(), RTLatin1ToUtf16Ex(), RTUtf16Dup() or RTUtf16DupEx().
+ *
+ * @returns iprt status code.
+ * @param   pwszString      The UTF-16 string to free. NULL is accepted.
+ */
+RTDECL(void)  RTUtf16Free(PRTUTF16 pwszString);
+/**
+ * Allocates a new copy of the specified UTF-16 string (default tag).
+ *
+ * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
+ * @returns NULL when out of memory.
+ * @param   pwszString      UTF-16 string to duplicate.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+#define RTUtf16Dup(pwszString)          RTUtf16DupTag((pwszString), RTSTR_TAG)
+/**
+ * Allocates a new copy of the specified UTF-16 string (custom tag).
+ *
+ * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
+ * @returns NULL when out of memory.
+ * @param   pwszString      UTF-16 string to duplicate.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+RTDECL(PRTUTF16) RTUtf16DupTag(PCRTUTF16 pwszString, const char *pszTag);
+/**
+ * Allocates a new copy of the specified UTF-16 string (default tag).
+ *
+ * @returns iprt status code.
+ * @param   ppwszString     Receives pointer of the allocated UTF-16 string.
+ *                          The returned pointer must be freed using RTUtf16Free().
+ * @param   pwszString      UTF-16 string to duplicate.
+ * @param   cwcExtra        Number of extra RTUTF16 items to allocate.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+#define RTUtf16DupEx(ppwszString, pwszString, cwcExtra) \
+    RTUtf16DupExTag((ppwszString), (pwszString), (cwcExtra), RTSTR_TAG)
+/**
+ * Allocates a new copy of the specified UTF-16 string (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   ppwszString     Receives pointer of the allocated UTF-16 string.
+ *                          The returned pointer must be freed using RTUtf16Free().
+ * @param   pwszString      UTF-16 string to duplicate.
+ * @param   cwcExtra        Number of extra RTUTF16 items to allocate.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+RTDECL(int) RTUtf16DupExTag(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra, const char *pszTag);
+/**
+ * Returns the length of a UTF-16 string in UTF-16 characters
+ * without trailing '\\0'.
+ *
+ * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
+ * to get the exact number of code points in the string.
+ *
+ * @returns The number of RTUTF16 items in the string.
+ * @param   pwszString  Pointer the UTF-16 string.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
+/**
+ * Find the length of a zero-terminated byte string, given a max string length.
+ *
+ * @returns The string length or cbMax. The returned length does not include
+ *          the zero terminator if it was found.
+ *
+ * @param   pwszString  The string.
+ * @param   cwcMax      The max string length in RTUTF16s.
+ * @sa      RTUtf16NLenEx, RTStrNLen.
+ */
+RTDECL(size_t) RTUtf16NLen(PCRTUTF16 pwszString, size_t cwcMax);
+/**
+ * Find the length of a zero-terminated byte string, given
+ * a max string length.
+ *
+ * @returns IPRT status code.
+ * @retval  VINF_SUCCESS if the string has a length less than cchMax.
+ * @retval  VERR_BUFFER_OVERFLOW if the end of the string wasn't found
+ *          before cwcMax was reached.
+ *
+ * @param   pwszString  The string.
+ * @param   cwcMax      The max string length in RTUTF16s.
+ * @param   pcwc        Where to store the string length excluding the
+ *                      terminator.  This is set to cwcMax if the terminator
+ *                      isn't found.
+ * @sa      RTUtf16NLen, RTStrNLenEx.
+ */
+RTDECL(int) RTUtf16NLenEx(PCRTUTF16 pwszString, size_t cwcMax, size_t *pcwc);
+/**
+ * Find the zero terminator in a string with a limited length.
+ *
+ * @returns Pointer to the zero terminator.
+ * @returns NULL if the zero terminator was not found.
+ *
+ * @param   pwszString  The string.
+ * @param   cwcMax      The max string length.  RTSTR_MAX is fine.
+ */
+RTDECL(PCRTUTF16) RTUtf16End(PCRTUTF16 pwszString, size_t cwcMax);
+/**
+ * Strips blankspaces from both ends of the string.
+ *
+ * @returns Pointer to first non-blank char in the string.
+ * @param   pwsz    The string to strip.
+ */
+RTDECL(PRTUTF16) RTUtf16Strip(PRTUTF16 pwsz);
+/**
+ * Strips blankspaces from the start of the string.
+ *
+ * @returns Pointer to first non-blank char in the string.
+ * @param   pwsz    The string to strip.
+ */
+RTDECL(PRTUTF16) RTUtf16StripL(PCRTUTF16 pwsz);
+/**
+ * Strips blankspaces from the end of the string.
+ *
+ * @returns pwsz.
+ * @param   pwsz    The string to strip.
+ */
+RTDECL(PRTUTF16) RTUtf16StripR(PRTUTF16 pwsz);
+/**
+ * String copy with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pwszSrc             The source string.  NULL is not OK.
+ */
+RTDECL(int) RTUtf16Copy(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
+/**
+ * String copy with overflow handling, ASCII source.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pszSrc              The source string, pure ASCII.  NULL is not OK.
+ */
+RTDECL(int) RTUtf16CopyAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
+/**
+ * String copy with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pwszSrc             The source string.  NULL is not OK.
+ * @param   cwcSrcMax           The maximum number of chars (not code points) to
+ *                              copy from the source string, not counting the
+ *                              terminator as usual.
+ */
+RTDECL(int) RTUtf16CopyEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
+/**
+ * String concatenation with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pwszSrc             The source string.  NULL is not OK.
+ */
+RTDECL(int) RTUtf16Cat(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
+/**
+ * String concatenation with overflow handling, ASCII source.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pszSrc              The source string, pure ASCII.  NULL is not OK.
+ */
+RTDECL(int) RTUtf16CatAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
+/**
+ * String concatenation with overflow handling.
+ *
+ * @retval  VINF_SUCCESS on success.
+ * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
+ *          buffer will contain as much of the string as it can hold, fully
+ *          terminated.
+ *
+ * @param   pwszDst             The destination buffer.
+ * @param   cwcDst              The size of the destination buffer in RTUTF16s.
+ * @param   pwszSrc             The source string.  NULL is not OK.
+ * @param   cwcSrcMax           The maximum number of UTF-16 chars (not code
+ *                              points) to copy from the source string, not
+ *                              counting the terminator as usual.
+ */
+RTDECL(int) RTUtf16CatEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
+/**
+ * Performs a case sensitive string compare between two UTF-16 strings.
+ *
+ * @returns < 0 if the first string less than the second string.s
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   pwsz1       First UTF-16 string. Null is allowed.
+ * @param   pwsz2       Second UTF-16 string. Null is allowed.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+RTDECL(int) RTUtf16Cmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
+/**
+ * Performs a case sensitive string compare between an UTF-16 string and a pure
+ * ASCII string.
+ *
+ * @returns < 0 if the first string less than the second string.s
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   pwsz1       First UTF-16 string. Null is allowed.
+ * @param   psz2        Second string, pure ASCII. Null is allowed.
+ * @remark  This function will not make any attempt to validate the encoding.
+ */
+RTDECL(int) RTUtf16CmpAscii(PCRTUTF16 pwsz1, const char *psz2);
+/**
+ * Performs a case insensitive string compare between two UTF-16 strings.
+ *
+ * This is a simplified compare, as only the simplified lower/upper case folding
+ * specified by the unicode specs are used. It does not consider character pairs
+ * as they are used in some languages, just simple upper & lower case compares.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   pwsz1       First UTF-16 string. Null is allowed.
+ * @param   pwsz2       Second UTF-16 string. Null is allowed.
+ */
+RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
+/**
+ * Performs a case insensitive string compare between an UTF-16 string and an
+ * pure ASCII string.
+ *
+ * Since this compare only takes cares about the first 128 codepoints in
+ * unicode, no tables are needed and there aren't any real complications.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   pwsz1       First UTF-16 string. Null is allowed.
+ * @param   psz2        Second string, pure ASCII. Null is allowed.
+ */
+RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1, const char *psz2);
+/**
+ * Performs a case insensitive string compare between two UTF-16 strings
+ * using the current locale of the process (if applicable).
+ *
+ * This differs from RTUtf16ICmp() in that it will try, if a locale with the
+ * required data is available, to do a correct case-insensitive compare. It
+ * follows that it is more complex and thereby likely to be more expensive.
+ *
+ * @returns < 0 if the first string less than the second string.
+ * @returns 0 if the first string identical to the second string.
+ * @returns > 0 if the first string greater than the second string.
+ * @param   pwsz1       First UTF-16 string. Null is allowed.
+ * @param   pwsz2       Second UTF-16 string. Null is allowed.
+ */
+RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
+/**
+ * Folds a UTF-16 string to lowercase.
+ *
+ * This is a very simple folding; is uses the simple lowercase
+ * code point, it is not related to any locale just the most common
+ * lowercase codepoint setup by the unicode specs, and it will not
+ * create new surrogate pairs or remove existing ones.
+ *
+ * @returns Pointer to the passed in string.
+ * @param   pwsz        The string to fold.
+ */
+RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
+/**
+ * Folds a UTF-16 string to uppercase.
+ *
+ * This is a very simple folding; is uses the simple uppercase
+ * code point, it is not related to any locale just the most common
+ * uppercase codepoint setup by the unicode specs, and it will not
+ * create new surrogate pairs or remove existing ones.
+ *
+ * @returns Pointer to the passed in string.
+ * @param   pwsz        The string to fold.
+ */
+RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
+/**
+ * Validates the UTF-16 encoding of the string.
+ *
+ * @returns iprt status code.
+ * @param   pwsz        The string.
+ */
+RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz);
+/**
+ * Validates the UTF-16 encoding of the string.
+ *
+ * @returns iprt status code.
+ * @param   pwsz        The string.
+ * @param   cwc         The max string length (/ size) in UTF-16 units. Use
+ *                      RTSTR_MAX to process the entire string.
+ * @param   fFlags      Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
+ */
+RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz, size_t cwc, uint32_t fFlags);
+/**
+ * Checks if the UTF-16 encoding is valid.
+ *
+ * @returns true / false.
+ * @param   pwsz        The string.
+ */
+RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz);
+/**
+ * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
+ * list in-place by an ASCII replacement character.  Multi-byte characters will
+ * be replaced byte by byte.
+ *
+ * @returns The number of code points replaced, or a negative value if the
+ *          string is not correctly encoded.  In this last case the string
+ *          may be partially processed.
+ * @param   pwsz           The string to sanitise.
+ * @param   puszValidSet   A zero-terminated array of pairs of Unicode points.
+ *                         Each pair is the start and end point of a range,
+ *                         and the union of these ranges forms the white list.
+ * @param   chReplacement  The ASCII replacement character.
+ */
+RTDECL(ssize_t) RTUtf16PurgeComplementSet(PRTUTF16 pwsz, PCRTUNICP puszValidSet, char chReplacement);
+/**
+ * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
+ * tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      UTF-16 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ */
+#define RTUtf16ToUtf8(pwszString, ppszString)       RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
+/**
+ * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
+ *
+ * @returns iprt status code.
+ * @param   pwszString      UTF-16 string to convert.
+ * @param   ppszString      Receives pointer of allocated UTF-8 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTUtf16ToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
+/**
+ * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
+ * sized buffer allocated by the function (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      The UTF-16 string to convert.
+ * @param   cwcString       The number of RTUTF16 items to translate from pwszString.
+ *                          The translation will stop when reaching cwcString or the terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppsz            If cch is non-zero, this must either be pointing to a pointer to
+ *                          a buffer of the specified size, or pointer to a NULL pointer.
+ *                          If *ppsz is NULL or cch is zero a buffer of at least cch chars
+ *                          will be allocated to hold the translated string.
+ *                          If a buffer was requested it must be freed using RTStrFree().
+ * @param   cch             The buffer size in chars (the type). This includes the terminator.
+ * @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.
+ */
+#define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
+    RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
+/**
+ * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
+ * sized buffer allocated by the function (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      The UTF-16 string to convert.
+ * @param   cwcString       The number of RTUTF16 items to translate from pwszString.
+ *                          The translation will stop when reaching cwcString or the terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppsz            If cch is non-zero, this must either be pointing to a pointer to
+ *                          a buffer of the specified size, or pointer to a NULL pointer.
+ *                          If *ppsz is NULL or cch is zero a buffer of at least cch chars
+ *                          will be allocated to hold the translated string.
+ *                          If a buffer was requested it must be freed using RTStrFree().
+ * @param   cch             The buffer size in chars (the type). This includes the terminator.
+ * @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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
+/**
+ * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
+ *
+ * This function will validate the string, and incorrectly encoded UTF-16
+ * strings will be rejected. The primary purpose of this function is to
+ * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
+ * other purposes RTUtf16ToUtf8Ex() should be used.
+ *
+ * @returns Number of char (bytes).
+ * @returns 0 if the string was incorrectly encoded.
+ * @param   pwsz        The UTF-16 string.
+ */
+RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
+/**
+ * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
+ *
+ * This function will validate the string, and incorrectly encoded UTF-16
+ * strings will be rejected.
+ *
+ * @returns iprt status code.
+ * @param   pwsz        The string.
+ * @param   cwc         The max string length. Use RTSTR_MAX to process the entire string.
+ * @param   pcch        Where to store the string length (in bytes). Optional.
+ *                      This is undefined on failure.
+ */
+RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
+/**
+ * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
+ * buffer (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      UTF-16 string to convert.
+ * @param   ppszString      Receives pointer of allocated Latin1 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ */
+#define RTUtf16ToLatin1(pwszString, ppszString)     RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
+/**
+ * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
+ * buffer (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      UTF-16 string to convert.
+ * @param   ppszString      Receives pointer of allocated Latin1 string on
+ *                          success, and is always set to NULL on failure.
+ *                          The returned pointer must be freed using RTStrFree().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTUtf16ToLatin1Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
+/**
+ * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
+ * or a fittingly sized buffer allocated by the function (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      The UTF-16 string to convert.
+ * @param   cwcString       The number of RTUTF16 items to translate from
+ *                          pwszString. The translation will stop when reaching
+ *                          cwcString or the terminator ('\\0'). Use RTSTR_MAX
+ *                          to translate the entire string.
+ * @param   ppsz            Pointer to the pointer to the Latin-1 string. The
+ *                          buffer can optionally be preallocated by the caller.
+ *
+ *                          If cch is zero, *ppsz is undefined.
+ *
+ *                          If cch is non-zero and *ppsz is not NULL, then this
+ *                          will be used as the output buffer.
+ *                          VERR_BUFFER_OVERFLOW will be returned if this is
+ *                          insufficient.
+ *
+ *                          If cch is zero or *ppsz is NULL, then a buffer of
+ *                          sufficient size is allocated. cch can be used to
+ *                          specify a minimum size of this buffer. Use
+ *                          RTUtf16Free() to free the result.
+ *
+ * @param   cch             The buffer size in chars (the type). This includes
+ *                          the terminator.
+ * @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.
+ */
+#define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
+    RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
+/**
+ * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
+ * or a fittingly sized buffer allocated by the function (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pwszString      The UTF-16 string to convert.
+ * @param   cwcString       The number of RTUTF16 items to translate from
+ *                          pwszString. The translation will stop when reaching
+ *                          cwcString or the terminator ('\\0'). Use RTSTR_MAX
+ *                          to translate the entire string.
+ * @param   ppsz            Pointer to the pointer to the Latin-1 string. The
+ *                          buffer can optionally be preallocated by the caller.
+ *
+ *                          If cch is zero, *ppsz is undefined.
+ *
+ *                          If cch is non-zero and *ppsz is not NULL, then this
+ *                          will be used as the output buffer.
+ *                          VERR_BUFFER_OVERFLOW will be returned if this is
+ *                          insufficient.
+ *
+ *                          If cch is zero or *ppsz is NULL, then a buffer of
+ *                          sufficient size is allocated. cch can be used to
+ *                          specify a minimum size of this buffer. Use
+ *                          RTUtf16Free() to free the result.
+ *
+ * @param   cch             The buffer size in chars (the type). This includes
+ *                          the terminator.
+ * @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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int)  RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
+/**
+ * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-16
+ * strings will be rejected. The primary purpose of this function is to
+ * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
+ * other purposes RTUtf16ToLatin1Ex() should be used.
+ *
+ * @returns Number of char (bytes).
+ * @returns 0 if the string was incorrectly encoded.
+ * @param   pwsz        The UTF-16 string.
+ */
+RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
+/**
+ * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
+ *
+ * This function will validate the string, and incorrectly encoded UTF-16
+ * strings will be rejected.
+ *
+ * @returns iprt status code.
+ * @param   pwsz        The string.
+ * @param   cwc         The max string length. Use RTSTR_MAX to process the
+ *                      entire string.
+ * @param   pcch        Where to store the string length (in bytes). Optional.
+ *                      This is undefined on failure.
+ */
+RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   pwsz        The string.
+ *
+ * @remark  This is an internal worker for RTUtf16GetCp().
+ */
+RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code.
+ * @param   ppwsz       Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ *
+ * @remark  This is an internal worker for RTUtf16GetCpEx().
+ */
+RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by pwsz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   pwsz        The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the UTF-16 range.
+ *
+ * @remark  This is an internal worker for RTUtf16GetCpEx().
+ */
+RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns unicode code point.
+ * @returns RTUNICP_INVALID if the encoding is invalid.
+ * @param   pwsz        The string.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          everything which isn't a surrogate pair or an endian indicator.
+ */
+DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
+{
+    const RTUTF16 wc = *pwsz;
+    if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
+        return wc;
+    return RTUtf16GetCpInternal(pwsz);
+}
+/**
+ * Get the unicode code point at the given string position.
+ *
+ * @returns iprt status code.
+ * @param   ppwsz       Pointer to the string pointer. This will be updated to
+ *                      point to the char following the current code point.
+ * @param   pCp         Where to store the code point.
+ *                      RTUNICP_INVALID is stored here on failure.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          everything which isn't a surrogate pair or and endian indicator.
+ */
+DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
+{
+    const RTUTF16 wc = **ppwsz;
+    if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
+    {
+        (*ppwsz)++;
+        *pCp = wc;
+        return VINF_SUCCESS;
+    }
+    return RTUtf16GetCpExInternal(ppwsz, pCp);
+}
+/**
+ * Put the unicode code point at the given string position
+ * and return the pointer to the char following it.
+ *
+ * This function will not consider anything at or following the
+ * buffer area pointed to by pwsz. It is therefore not suitable for
+ * inserting code points into a string, only appending/overwriting.
+ *
+ * @returns pointer to the char following the written code point.
+ * @param   pwsz        The string.
+ * @param   CodePoint   The code point to write.
+ *                      This should not be RTUNICP_INVALID or any other
+ *                      character out of the UTF-16 range.
+ *
+ * @remark  We optimize this operation by using an inline function for
+ *          everything which isn't a surrogate pair or and endian indicator.
+ */
+DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
+{
+    if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
+    {
+        *pwsz++ = (RTUTF16)CodePoint;
+        return pwsz;
+    }
+    return RTUtf16PutCpInternal(pwsz, CodePoint);
+}
+/**
+ * Skips ahead, past the current code point.
+ *
+ * @returns Pointer to the char after the current code point.
+ * @param   pwsz    Pointer to the current code point.
+ * @remark  This will not move the next valid code point, only past the current one.
+ */
+DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
+{
+    RTUNICP Cp;
+    RTUtf16GetCpEx(&pwsz, &Cp);
+    return (PRTUTF16)pwsz;
+}
+/**
+ * Skips backwards, to the previous code point.
+ *
+ * @returns Pointer to the char after the current code point.
+ * @param   pwszStart   Pointer to the start of the string.
+ * @param   pwsz        Pointer to the current code point.
+ */
+RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
+/**
+ * Checks if the UTF-16 char is the high surrogate char (i.e.
+ * the 1st char in the pair).
+ *
+ * @returns true if it is.
+ * @returns false if it isn't.
+ * @param   wc      The character to investigate.
+ */
+DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
+{
+    return wc >= 0xd800 && wc <= 0xdbff;
+}
+/**
+ * Checks if the UTF-16 char is the low surrogate char (i.e.
+ * the 2nd char in the pair).
+ *
+ * @returns true if it is.
+ * @returns false if it isn't.
+ * @param   wc      The character to investigate.
+ */
+DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
+{
+    return wc >= 0xdc00 && wc <= 0xdfff;
+}
+/**
+ * Checks if the two UTF-16 chars form a valid surrogate pair.
+ *
+ * @returns true if they do.
+ * @returns false if they doesn't.
+ * @param   wcHigh      The high (1st) character.
+ * @param   wcLow       The low (2nd) character.
+ */
+DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
+{
+    return RTUtf16IsHighSurrogate(wcHigh)
+        && RTUtf16IsLowSurrogate(wcLow);
+}
+/**
+ * Formats a buffer stream as hex bytes.
+ *
+ * The default is no separating spaces or line breaks or anything.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
+ *
+ * @param   pwszBuf     Output string buffer.
+ * @param   cwcBuf      The size of the output buffer in RTUTF16 units.
+ * @param   pv          Pointer to the bytes to stringify.
+ * @param   cb          The number of bytes to stringify.
+ * @param   fFlags      Combination of RTSTRPRINTHEXBYTES_F_XXX values.
+ * @sa      RTStrPrintHexBytes.
+ */
+RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf, size_t cwcBuf, void const *pv, size_t cb, uint32_t fFlags);
+/** @} */
+/** @defgroup rt_str_latin1     Latin-1 (ISO-8859-1) String Manipulation
+ * @{
+ */
+RTDECL(int) RTLatin1CalcUtf8LenEx(const char *pszLatin1, size_t cchLatin1, size_t *pcch);
 /**
 …
+ *
  * @returns Number of RTUTF16 items.
  * @param   psz             The Latin-1 string.
  */
 RTDECL(size_t) RTLatin1CalcUtf16Len(const char *psz);
+ * @param   pszLatin1       The Latin-1 string.
+ */
+RTDECL(size_t) RTLatin1CalcUtf16Len(const char *pszLatin1);
 /**
 …
+ *
  * @returns iprt status code.
  * @param   psz             The Latin-1 string.
  * @param   cch             The max string length. Use RTSTR_MAX to process the
+ * @param   pszLatin1       The Latin-1 string.
+ * @param   cchLatin1       The max string length. Use RTSTR_MAX to process the
  *                          entire string.
  * @param   pcwc            Where to store the string length. Optional.
  *                          This is undefined on failure.
  */
 RTDECL(int) RTLatin1CalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
+RTDECL(int) RTLatin1CalcUtf16LenEx(const char *pszLatin1, size_t cchLatin1, size_t *pcwc);
 /**
 …
+ *
  * @returns iprt status code.
  * @param   pszString       The Latin-1 string to convert.
+ * @param   pszLatin1       The Latin-1 string to convert.
  * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
  *                          returned string must be freed using RTUtf16Free().
  */
 #define RTLatin1ToUtf16(pszString, ppwszString)     RTLatin1ToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
+#define RTLatin1ToUtf16(pszLatin1, ppwszString)     RTLatin1ToUtf16Tag((pszLatin1), (ppwszString), RTSTR_TAG)
 /**
 …
+ *
  * @returns iprt status code.
  * @param   pszString       The Latin-1 string to convert.
+ * @param   pszLatin1       The Latin-1 string to convert.
  * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
  *                          returned string must be freed using RTUtf16Free().
  * @param   pszTag          Allocation tag used for statistics and such.
  */
 RTDECL(int) RTLatin1ToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
 /**
  * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+RTDECL(int) RTLatin1ToUtf16Tag(const char *pszLatin1, PRTUTF16 *ppwszString, const char *pszTag);
+/**
+ * Translates pszLatin1 from Latin-1 (ISO-8859-1) to UTF-16, allocating the
  * result buffer if requested (default tag).
+ *
  * @returns iprt status code.
  * @param   pszString       The Latin-1 string to convert.
  * @param   cchString       The maximum size in chars (the type) to convert.
  *                          The conversion stops when it reaches cchString or
  *                          the string terminator ('\\0').
  *                          Use RTSTR_MAX to translate the entire string.
+ * @param   pszLatin1       The Latin-1 string to convert.
+ * @param   cchLatin1       The maximum size in chars (the type) to convert. The
+ *                          conversion stops when it reaches cchLatin1 or the
+ *                          string terminator ('\\0'). Use RTSTR_MAX to
+ *                          translate the entire string.
  * @param   ppwsz           If cwc is non-zero, this must either be pointing
  *                          to pointer to a buffer of the specified size, or
 …
  *                          length that can be used to resize the buffer.
  */
 #define RTLatin1ToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
     RTLatin1ToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
 /**
  * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+#define RTLatin1ToUtf16Ex(pszLatin1, cchLatin1, ppwsz, cwc, pcwc) \
+    RTLatin1ToUtf16ExTag((pszLatin1), (cchLatin1), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
+/**
+ * Translates pszLatin1 from Latin-1 (ISO-8859-1) to UTF-16, allocating the
  * result buffer if requested.
+ *
  * @returns iprt status code.
  * @param   pszString       The Latin-1 string to convert.
  * @param   cchString       The maximum size in chars (the type) to convert.
  *                          The conversion stops when it reaches cchString or
  *                          the string terminator ('\\0').
  *                          Use RTSTR_MAX to translate the entire string.
+ * @param   pszLatin1       The Latin-1 string to convert.
+ * @param   cchLatin1       The maximum size in chars (the type) to convert. The
+ *                          conversion stops when it reaches cchLatin1 or the
+ *                          string terminator ('\\0'). Use RTSTR_MAX to
+ *                          translate the entire string.
  * @param   ppwsz           If cwc is non-zero, this must either be pointing
  *                          to pointer to a buffer of the specified size, or
 …
  * @param   pszTag          Allocation tag used for statistics and such.
  */
 RTDECL(int) RTLatin1ToUtf16ExTag(const char *pszString, size_t cchString,
+RTDECL(int) RTLatin1ToUtf16ExTag(const char *pszLatin1, size_t cchLatin1,
                                  PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
 /** @} */
+#ifndef ___iprt_nocrt_string_h
+# if defined(RT_OS_WINDOWS)
+RTDECL(void *) mempcpy(void *pvDst, const void *pvSrc, size_t cb);
+# endif
+RT_C_DECLS_END
+/** @} */
 #endif
-RT_C_DECLS_END
-/** @} */
-#endif

trunk/include/iprt/string.h

-              r57927
+              r57941
 #endif
+/* For the time being: */
+#include <iprt/utf16.h>
+#include <iprt/latin1.h>
 /*
  * Supply prototypes for standard string functions provided by
 …
 /** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
+ * @{
  */
 /** Check that the string is zero terminated within the given size.
 …
  */
 RTDECL(int)  RTStrToLatin1ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Translate a Latin1 string into a UTF-8 allocating the result buffer (default
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       Latin1 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- */
-#define RTLatin1ToUtf8(pszString, ppszString)       RTLatin1ToUtf8Tag((pszString), (ppszString), RTSTR_TAG)
-/**
- * Translate a Latin-1 string into a UTF-8 allocating the result buffer.
+ *
- * @returns iprt status code.
- * @param   pszString       Latin-1 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTLatin1ToUtf8Tag(const char *pszString, char **ppszString, const char *pszTag);
-/**
- * Translates Latin-1 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (default tag).
+ *
- * @returns iprt status code.
- * @param   pszString       The Latin-1 string to convert.
- * @param   cchString       The number of Latin-1 characters to translate from
- *                          pszString. The translation will stop when reaching
- *                          cchString or the terminator ('\\0').  Use RTSTR_MAX
- *                          to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          a pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch chars will be
- *                          allocated to hold the translated string. If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in chars (the type). This includes the terminator.
- * @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.
- */
-#define RTLatin1ToUtf8Ex(pszString, cchString, ppsz, cch, pcch) \
-    RTLatin1ToUtf8ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
-/**
- * Translates Latin1 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (custom tag).
+ *
- * @returns iprt status code.
- * @param   pszString       The Latin1 string to convert.
- * @param   cchString       The number of Latin1 characters to translate from
- *                          pwszString.  The translation will stop when
- *                          reaching cchString or the terminator ('\\0').  Use
- *                          RTSTR_MAX to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          a pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch chars will be
- *                          allocated to hold the translated string.  If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in chars (the type).  This includes
- *                          the terminator.
- * @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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTLatin1ToUtf8ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Calculates the length of the Latin-1 string in UTF-8 chars (bytes).
+ *
- * The primary purpose of this function is to help allocate buffers for
- * RTLatin1ToUtf8() of the correct size. For most other purposes
- * RTLatin1ToUtf8Ex() should be used.
+ *
- * @returns Number of chars (bytes).
- * @returns 0 if the string was incorrectly encoded.
- * @param   psz        The Latin-1 string.
- */
-RTDECL(size_t) RTLatin1CalcUtf8Len(const char *psz);
-/**
- * Calculates the length of the Latin-1 string in UTF-8 chars (bytes).
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
- * @param   pcch        Where to store the string length (in bytes).  Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTLatin1CalcUtf8LenEx(const char *psz, size_t cch, size_t *pcch);
 /**
 …
  */
 RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   psz         The string.
- */
-DECLINLINE(RTUNICP) RTLatin1GetCp(const char *psz)
+{
-    return *(const unsigned char *)psz;
+}
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code.
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- *                      This is advanced one character forward on failure.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrGetCpExInternal().
- */
-DECLINLINE(int) RTLatin1GetCpEx(const char **ppsz, PRTUNICP pCp)
+{
-    const unsigned char uch = **(const unsigned char **)ppsz;
-    (*ppsz)++;
-    *pCp = uch;
-    return VINF_SUCCESS;
+}
-/**
- * Get the unicode code point at the given string position for a string of a
- * given maximum length.
+ *
- * @returns iprt status code.
- * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- * @param   pcch        Pointer to the maximum string length.  This will be
- *                      decremented by the size of the code point found.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
- */
-DECLINLINE(int) RTLatin1GetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
+{
-    if (RT_LIKELY(*pcch != 0))
+    {
-        const unsigned char uch = **(const unsigned char **)ppsz;
-        (*ppsz)++;
-        (*pcch)--;
-        *pCp = uch;
-        return VINF_SUCCESS;
+    }
-    *pCp = RTUNICP_INVALID;
-    return VERR_END_OF_STRING;
+}
-/**
- * Get the Latin-1 size in characters of a given Unicode code point.
+ *
- * The code point is expected to be a valid Unicode one, but not necessarily in
- * the range supported by Latin-1.
+ *
- * @returns the size in characters, or zero if there is no Latin-1 encoding
- */
-DECLINLINE(size_t) RTLatin1CpSize(RTUNICP CodePoint)
+{
-    if (CodePoint < 0x100)
-        return 1;
-    return 0;
+}
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by psz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   psz         The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the Latin-1 range.
- */
-DECLINLINE(char *) RTLatin1PutCp(char *psz, RTUNICP CodePoint)
+{
-    AssertReturn(CodePoint < 0x100, NULL);
-    *psz++ = (unsigned char)CodePoint;
-    return psz;
+}
-/**
- * Skips ahead, past the current code point.
+ *
- * @returns Pointer to the char after the current code point.
- * @param   psz     Pointer to the current code point.
- * @remark  This will not move the next valid code point, only past the current one.
- */
-DECLINLINE(char *) RTLatin1NextCp(const char *psz)
+{
-    psz++;
-    return (char *)psz;
+}
-/**
- * Skips back to the previous code point.
+ *
- * @returns Pointer to the char before the current code point.
- * @returns pszStart on failure.
- * @param   pszStart    Pointer to the start of the string.
- * @param   psz         Pointer to the current code point.
- */
-DECLINLINE(char *) RTLatin1PrevCp(const char *pszStart, const char *psz)
+{
-    if ((uintptr_t)psz > (uintptr_t)pszStart)
+    {
-        psz--;
-        return (char *)psz;
+    }
-    return (char *)pszStart;
+}
 …
 #endif
 /** Format flag.
+/** @name Format flag.
  * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
  * that not all flags makes sense to both of the functions.
 …
 /** @}  */
-/** @defgroup rt_str_utf16      UTF-16 String Manipulation
- * @{
- */
-/**
- * Allocates memory for UTF-16 string storage (default tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @returns Pointer to the allocated UTF-16 string.  The first wide char is
- *          always set to the string terminator char, the contents of the
- *          remainder of the memory is undefined.  The string must be freed by
- *          calling RTUtf16Free.
+ *
- *          NULL is returned if the allocation failed.  Please translate this to
- *          VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY.  Also consider
- *          RTUtf16AllocEx if an IPRT status code is required.
+ *
- * @param   cb                  How many bytes to allocate, will be rounded up
- *                              to a multiple of two. If this is zero, we will
- *                              allocate a terminator wide char anyway.
- */
-#define RTUtf16Alloc(cb)                    RTUtf16AllocTag((cb), RTSTR_TAG)
-/**
- * Allocates memory for UTF-16 string storage (custom tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @returns Pointer to the allocated UTF-16 string.  The first wide char is
- *          always set to the string terminator char, the contents of the
- *          remainder of the memory is undefined.  The string must be freed by
- *          calling RTUtf16Free.
+ *
- *          NULL is returned if the allocation failed.  Please translate this to
- *          VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY.  Also consider
- *          RTUtf16AllocExTag if an IPRT status code is required.
+ *
- * @param   cb                  How many bytes to allocate, will be rounded up
- *                              to a multiple of two. If this is zero, we will
- *                              allocate a terminator wide char anyway.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(PRTUTF16) RTUtf16AllocTag(size_t cb, const char *pszTag);
-/**
- * Free a UTF-16 string allocated by RTStrToUtf16(), RTStrToUtf16Ex(),
- * RTLatin1ToUtf16(), RTLatin1ToUtf16Ex(), RTUtf16Dup() or RTUtf16DupEx().
+ *
- * @returns iprt status code.
- * @param   pwszString      The UTF-16 string to free. NULL is accepted.
- */
-RTDECL(void)  RTUtf16Free(PRTUTF16 pwszString);
-/**
- * Allocates a new copy of the specified UTF-16 string (default tag).
+ *
- * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
- * @returns NULL when out of memory.
- * @param   pwszString      UTF-16 string to duplicate.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-#define RTUtf16Dup(pwszString)          RTUtf16DupTag((pwszString), RTSTR_TAG)
-/**
- * Allocates a new copy of the specified UTF-16 string (custom tag).
+ *
- * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
- * @returns NULL when out of memory.
- * @param   pwszString      UTF-16 string to duplicate.
- * @param   pszTag          Allocation tag used for statistics and such.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-RTDECL(PRTUTF16) RTUtf16DupTag(PCRTUTF16 pwszString, const char *pszTag);
-/**
- * Allocates a new copy of the specified UTF-16 string (default tag).
+ *
- * @returns iprt status code.
- * @param   ppwszString     Receives pointer of the allocated UTF-16 string.
- *                          The returned pointer must be freed using RTUtf16Free().
- * @param   pwszString      UTF-16 string to duplicate.
- * @param   cwcExtra        Number of extra RTUTF16 items to allocate.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-#define RTUtf16DupEx(ppwszString, pwszString, cwcExtra) \
-    RTUtf16DupExTag((ppwszString), (pwszString), (cwcExtra), RTSTR_TAG)
-/**
- * Allocates a new copy of the specified UTF-16 string (custom tag).
+ *
- * @returns iprt status code.
- * @param   ppwszString     Receives pointer of the allocated UTF-16 string.
- *                          The returned pointer must be freed using RTUtf16Free().
- * @param   pwszString      UTF-16 string to duplicate.
- * @param   cwcExtra        Number of extra RTUTF16 items to allocate.
- * @param   pszTag          Allocation tag used for statistics and such.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-RTDECL(int) RTUtf16DupExTag(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra, const char *pszTag);
-/**
- * Returns the length of a UTF-16 string in UTF-16 characters
- * without trailing '\\0'.
+ *
- * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
- * to get the exact number of code points in the string.
+ *
- * @returns The number of RTUTF16 items in the string.
- * @param   pwszString  Pointer the UTF-16 string.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
-/**
- * Find the length of a zero-terminated byte string, given a max string length.
+ *
- * @returns The string length or cbMax. The returned length does not include
- *          the zero terminator if it was found.
+ *
- * @param   pwszString  The string.
- * @param   cwcMax      The max string length in RTUTF16s.
- * @sa      RTUtf16NLenEx, RTStrNLen.
- */
-RTDECL(size_t) RTUtf16NLen(PCRTUTF16 pwszString, size_t cwcMax);
-/**
- * Find the length of a zero-terminated byte string, given
- * a max string length.
+ *
- * @returns IPRT status code.
- * @retval  VINF_SUCCESS if the string has a length less than cchMax.
- * @retval  VERR_BUFFER_OVERFLOW if the end of the string wasn't found
- *          before cwcMax was reached.
+ *
- * @param   pwszString  The string.
- * @param   cwcMax      The max string length in RTUTF16s.
- * @param   pcwc        Where to store the string length excluding the
- *                      terminator.  This is set to cwcMax if the terminator
- *                      isn't found.
- * @sa      RTUtf16NLen, RTStrNLenEx.
- */
-RTDECL(int) RTUtf16NLenEx(PCRTUTF16 pwszString, size_t cwcMax, size_t *pcwc);
-/**
- * Find the zero terminator in a string with a limited length.
+ *
- * @returns Pointer to the zero terminator.
- * @returns NULL if the zero terminator was not found.
+ *
- * @param   pwszString  The string.
- * @param   cwcMax      The max string length.  RTSTR_MAX is fine.
- */
-RTDECL(PCRTUTF16) RTUtf16End(PCRTUTF16 pwszString, size_t cwcMax);
-/**
- * Strips blankspaces from both ends of the string.
+ *
- * @returns Pointer to first non-blank char in the string.
- * @param   pwsz    The string to strip.
- */
-RTDECL(PRTUTF16) RTUtf16Strip(PRTUTF16 pwsz);
-/**
- * Strips blankspaces from the start of the string.
+ *
- * @returns Pointer to first non-blank char in the string.
- * @param   pwsz    The string to strip.
- */
-RTDECL(PRTUTF16) RTUtf16StripL(PCRTUTF16 pwsz);
-/**
- * Strips blankspaces from the end of the string.
+ *
- * @returns pwsz.
- * @param   pwsz    The string to strip.
- */
-RTDECL(PRTUTF16) RTUtf16StripR(PRTUTF16 pwsz);
-/**
- * String copy with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pwszSrc             The source string.  NULL is not OK.
- */
-RTDECL(int) RTUtf16Copy(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
-/**
- * String copy with overflow handling, ASCII source.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pszSrc              The source string, pure ASCII.  NULL is not OK.
- */
-RTDECL(int) RTUtf16CopyAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
-/**
- * String copy with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pwszSrc             The source string.  NULL is not OK.
- * @param   cwcSrcMax           The maximum number of chars (not code points) to
- *                              copy from the source string, not counting the
- *                              terminator as usual.
- */
-RTDECL(int) RTUtf16CopyEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
-/**
- * String concatenation with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pwszSrc             The source string.  NULL is not OK.
- */
-RTDECL(int) RTUtf16Cat(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
-/**
- * String concatenation with overflow handling, ASCII source.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pszSrc              The source string, pure ASCII.  NULL is not OK.
- */
-RTDECL(int) RTUtf16CatAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
-/**
- * String concatenation with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pwszDst             The destination buffer.
- * @param   cwcDst              The size of the destination buffer in RTUTF16s.
- * @param   pwszSrc             The source string.  NULL is not OK.
- * @param   cwcSrcMax           The maximum number of UTF-16 chars (not code
- *                              points) to copy from the source string, not
- *                              counting the terminator as usual.
- */
-RTDECL(int) RTUtf16CatEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
-/**
- * Performs a case sensitive string compare between two UTF-16 strings.
+ *
- * @returns < 0 if the first string less than the second string.s
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   pwsz1       First UTF-16 string. Null is allowed.
- * @param   pwsz2       Second UTF-16 string. Null is allowed.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-RTDECL(int) RTUtf16Cmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
-/**
- * Performs a case sensitive string compare between an UTF-16 string and a pure
- * ASCII string.
+ *
- * @returns < 0 if the first string less than the second string.s
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   pwsz1       First UTF-16 string. Null is allowed.
- * @param   psz2        Second string, pure ASCII. Null is allowed.
- * @remark  This function will not make any attempt to validate the encoding.
- */
-RTDECL(int) RTUtf16CmpAscii(PCRTUTF16 pwsz1, const char *psz2);
-/**
- * Performs a case insensitive string compare between two UTF-16 strings.
+ *
- * This is a simplified compare, as only the simplified lower/upper case folding
- * specified by the unicode specs are used. It does not consider character pairs
- * as they are used in some languages, just simple upper & lower case compares.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   pwsz1       First UTF-16 string. Null is allowed.
- * @param   pwsz2       Second UTF-16 string. Null is allowed.
- */
-RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
-/**
- * Performs a case insensitive string compare between an UTF-16 string and an
- * pure ASCII string.
+ *
- * Since this compare only takes cares about the first 128 codepoints in
- * unicode, no tables are needed and there aren't any real complications.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   pwsz1       First UTF-16 string. Null is allowed.
- * @param   psz2        Second string, pure ASCII. Null is allowed.
- */
-RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1, const char *psz2);
-/**
- * Performs a case insensitive string compare between two UTF-16 strings
- * using the current locale of the process (if applicable).
+ *
- * This differs from RTUtf16ICmp() in that it will try, if a locale with the
- * required data is available, to do a correct case-insensitive compare. It
- * follows that it is more complex and thereby likely to be more expensive.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   pwsz1       First UTF-16 string. Null is allowed.
- * @param   pwsz2       Second UTF-16 string. Null is allowed.
- */
-RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
-/**
- * Folds a UTF-16 string to lowercase.
+ *
- * This is a very simple folding; is uses the simple lowercase
- * code point, it is not related to any locale just the most common
- * lowercase codepoint setup by the unicode specs, and it will not
- * create new surrogate pairs or remove existing ones.
+ *
- * @returns Pointer to the passed in string.
- * @param   pwsz        The string to fold.
- */
-RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
-/**
- * Folds a UTF-16 string to uppercase.
+ *
- * This is a very simple folding; is uses the simple uppercase
- * code point, it is not related to any locale just the most common
- * uppercase codepoint setup by the unicode specs, and it will not
- * create new surrogate pairs or remove existing ones.
+ *
- * @returns Pointer to the passed in string.
- * @param   pwsz        The string to fold.
- */
-RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
-/**
- * Validates the UTF-16 encoding of the string.
+ *
- * @returns iprt status code.
- * @param   pwsz        The string.
- */
-RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz);
-/**
- * Validates the UTF-16 encoding of the string.
+ *
- * @returns iprt status code.
- * @param   pwsz        The string.
- * @param   cwc         The max string length (/ size) in UTF-16 units. Use
- *                      RTSTR_MAX to process the entire string.
- * @param   fFlags      Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
- */
-RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz, size_t cwc, uint32_t fFlags);
-/**
- * Checks if the UTF-16 encoding is valid.
+ *
- * @returns true / false.
- * @param   pwsz        The string.
- */
-RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz);
-/**
- * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
- * list in-place by an ASCII replacement character.  Multi-byte characters will
- * be replaced byte by byte.
+ *
- * @returns The number of code points replaced, or a negative value if the
- *          string is not correctly encoded.  In this last case the string
- *          may be partially processed.
- * @param   pwsz           The string to sanitise.
- * @param   puszValidSet   A zero-terminated array of pairs of Unicode points.
- *                         Each pair is the start and end point of a range,
- *                         and the union of these ranges forms the white list.
- * @param   chReplacement  The ASCII replacement character.
- */
-RTDECL(ssize_t) RTUtf16PurgeComplementSet(PRTUTF16 pwsz, PCRTUNICP puszValidSet, char chReplacement);
-/**
- * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
- * tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      UTF-16 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- */
-#define RTUtf16ToUtf8(pwszString, ppszString)       RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
-/**
- * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
+ *
- * @returns iprt status code.
- * @param   pwszString      UTF-16 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTUtf16ToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
-/**
- * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (default tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      The UTF-16 string to convert.
- * @param   cwcString       The number of RTUTF16 items to translate from pwszString.
- *                          The translation will stop when reaching cwcString or the terminator ('\\0').
- *                          Use RTSTR_MAX to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to a pointer to
- *                          a buffer of the specified size, or pointer to a NULL pointer.
- *                          If *ppsz is NULL or cch is zero a buffer of at least cch chars
- *                          will be allocated to hold the translated string.
- *                          If a buffer was requested it must be freed using RTStrFree().
- * @param   cch             The buffer size in chars (the type). This includes the terminator.
- * @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.
- */
-#define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
-    RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
-/**
- * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (custom tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      The UTF-16 string to convert.
- * @param   cwcString       The number of RTUTF16 items to translate from pwszString.
- *                          The translation will stop when reaching cwcString or the terminator ('\\0').
- *                          Use RTSTR_MAX to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to a pointer to
- *                          a buffer of the specified size, or pointer to a NULL pointer.
- *                          If *ppsz is NULL or cch is zero a buffer of at least cch chars
- *                          will be allocated to hold the translated string.
- *                          If a buffer was requested it must be freed using RTStrFree().
- * @param   cch             The buffer size in chars (the type). This includes the terminator.
- * @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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
+ *
- * This function will validate the string, and incorrectly encoded UTF-16
- * strings will be rejected. The primary purpose of this function is to
- * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
- * other purposes RTUtf16ToUtf8Ex() should be used.
+ *
- * @returns Number of char (bytes).
- * @returns 0 if the string was incorrectly encoded.
- * @param   pwsz        The UTF-16 string.
- */
-RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
-/**
- * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
+ *
- * This function will validate the string, and incorrectly encoded UTF-16
- * strings will be rejected.
+ *
- * @returns iprt status code.
- * @param   pwsz        The string.
- * @param   cwc         The max string length. Use RTSTR_MAX to process the entire string.
- * @param   pcch        Where to store the string length (in bytes). Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
-/**
- * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
- * buffer (default tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      UTF-16 string to convert.
- * @param   ppszString      Receives pointer of allocated Latin1 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- */
-#define RTUtf16ToLatin1(pwszString, ppszString)     RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
-/**
- * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
- * buffer (custom tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      UTF-16 string to convert.
- * @param   ppszString      Receives pointer of allocated Latin1 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTUtf16ToLatin1Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
-/**
- * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
- * or a fittingly sized buffer allocated by the function (default tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      The UTF-16 string to convert.
- * @param   cwcString       The number of RTUTF16 items to translate from
- *                          pwszString. The translation will stop when reaching
- *                          cwcString or the terminator ('\\0'). Use RTSTR_MAX
- *                          to translate the entire string.
- * @param   ppsz            Pointer to the pointer to the Latin-1 string. The
- *                          buffer can optionally be preallocated by the caller.
+ *
- *                          If cch is zero, *ppsz is undefined.
+ *
- *                          If cch is non-zero and *ppsz is not NULL, then this
- *                          will be used as the output buffer.
- *                          VERR_BUFFER_OVERFLOW will be returned if this is
- *                          insufficient.
+ *
- *                          If cch is zero or *ppsz is NULL, then a buffer of
- *                          sufficient size is allocated. cch can be used to
- *                          specify a minimum size of this buffer. Use
- *                          RTUtf16Free() to free the result.
+ *
- * @param   cch             The buffer size in chars (the type). This includes
- *                          the terminator.
- * @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.
- */
-#define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
-    RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
-/**
- * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
- * or a fittingly sized buffer allocated by the function (custom tag).
+ *
- * @returns iprt status code.
- * @param   pwszString      The UTF-16 string to convert.
- * @param   cwcString       The number of RTUTF16 items to translate from
- *                          pwszString. The translation will stop when reaching
- *                          cwcString or the terminator ('\\0'). Use RTSTR_MAX
- *                          to translate the entire string.
- * @param   ppsz            Pointer to the pointer to the Latin-1 string. The
- *                          buffer can optionally be preallocated by the caller.
+ *
- *                          If cch is zero, *ppsz is undefined.
+ *
- *                          If cch is non-zero and *ppsz is not NULL, then this
- *                          will be used as the output buffer.
- *                          VERR_BUFFER_OVERFLOW will be returned if this is
- *                          insufficient.
+ *
- *                          If cch is zero or *ppsz is NULL, then a buffer of
- *                          sufficient size is allocated. cch can be used to
- *                          specify a minimum size of this buffer. Use
- *                          RTUtf16Free() to free the result.
+ *
- * @param   cch             The buffer size in chars (the type). This includes
- *                          the terminator.
- * @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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
+ *
- * This function will validate the string, and incorrectly encoded UTF-16
- * strings will be rejected. The primary purpose of this function is to
- * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
- * other purposes RTUtf16ToLatin1Ex() should be used.
+ *
- * @returns Number of char (bytes).
- * @returns 0 if the string was incorrectly encoded.
- * @param   pwsz        The UTF-16 string.
- */
-RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
-/**
- * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
+ *
- * This function will validate the string, and incorrectly encoded UTF-16
- * strings will be rejected.
+ *
- * @returns iprt status code.
- * @param   pwsz        The string.
- * @param   cwc         The max string length. Use RTSTR_MAX to process the
- *                      entire string.
- * @param   pcch        Where to store the string length (in bytes). Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   pwsz        The string.
+ *
- * @remark  This is an internal worker for RTUtf16GetCp().
- */
-RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code.
- * @param   ppwsz       Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  This is an internal worker for RTUtf16GetCpEx().
- */
-RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by pwsz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   pwsz        The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the UTF-16 range.
+ *
- * @remark  This is an internal worker for RTUtf16GetCpEx().
- */
-RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   pwsz        The string.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          everything which isn't a surrogate pair or an endian indicator.
- */
-DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
+{
-    const RTUTF16 wc = *pwsz;
-    if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
-        return wc;
-    return RTUtf16GetCpInternal(pwsz);
+}
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code.
- * @param   ppwsz       Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          everything which isn't a surrogate pair or and endian indicator.
- */
-DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
+{
-    const RTUTF16 wc = **ppwsz;
-    if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
+    {
-        (*ppwsz)++;
-        *pCp = wc;
-        return VINF_SUCCESS;
+    }
-    return RTUtf16GetCpExInternal(ppwsz, pCp);
+}
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by pwsz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   pwsz        The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the UTF-16 range.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          everything which isn't a surrogate pair or and endian indicator.
- */
-DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
+{
-    if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
+    {
-        *pwsz++ = (RTUTF16)CodePoint;
-        return pwsz;
+    }
-    return RTUtf16PutCpInternal(pwsz, CodePoint);
+}
-/**
- * Skips ahead, past the current code point.
+ *
- * @returns Pointer to the char after the current code point.
- * @param   pwsz    Pointer to the current code point.
- * @remark  This will not move the next valid code point, only past the current one.
- */
-DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
+{
-    RTUNICP Cp;
-    RTUtf16GetCpEx(&pwsz, &Cp);
-    return (PRTUTF16)pwsz;
+}
-/**
- * Skips backwards, to the previous code point.
+ *
- * @returns Pointer to the char after the current code point.
- * @param   pwszStart   Pointer to the start of the string.
- * @param   pwsz        Pointer to the current code point.
- */
-RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
-/**
- * Checks if the UTF-16 char is the high surrogate char (i.e.
- * the 1st char in the pair).
+ *
- * @returns true if it is.
- * @returns false if it isn't.
- * @param   wc      The character to investigate.
- */
-DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
+{
-    return wc >= 0xd800 && wc <= 0xdbff;
+}
-/**
- * Checks if the UTF-16 char is the low surrogate char (i.e.
- * the 2nd char in the pair).
+ *
- * @returns true if it is.
- * @returns false if it isn't.
- * @param   wc      The character to investigate.
- */
-DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
+{
-    return wc >= 0xdc00 && wc <= 0xdfff;
+}
-/**
- * Checks if the two UTF-16 chars form a valid surrogate pair.
+ *
- * @returns true if they do.
- * @returns false if they doesn't.
- * @param   wcHigh      The high (1st) character.
- * @param   wcLow       The low (2nd) character.
- */
-DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
+{
-    return RTUtf16IsHighSurrogate(wcHigh)
-        && RTUtf16IsLowSurrogate(wcLow);
+}
-/**
- * Formats a buffer stream as hex bytes.
+ *
- * The default is no separating spaces or line breaks or anything.
+ *
- * @returns IPRT status code.
- * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
- * @retval  VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
+ *
- * @param   pwszBuf     Output string buffer.
- * @param   cwcBuf      The size of the output buffer in RTUTF16 units.
- * @param   pv          Pointer to the bytes to stringify.
- * @param   cb          The number of bytes to stringify.
- * @param   fFlags      Combination of RTSTRPRINTHEXBYTES_F_XXX values.
- * @sa      RTStrPrintHexBytes.
- */
-RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf, size_t cwcBuf, void const *pv, size_t cb, uint32_t fFlags);
 /** @} */
+/** @defgroup rt_str_latin1     Latin-1 (ISO-8859-1) String Manipulation
+ * @{
+ */
+/**
+ * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
+ *
+ * @returns Number of RTUTF16 items.
+ * @param   psz             The Latin-1 string.
+ */
+RTDECL(size_t) RTLatin1CalcUtf16Len(const char *psz);
+/**
+ * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
+ *
+ * @returns iprt status code.
+ * @param   psz             The Latin-1 string.
+ * @param   cch             The max string length. Use RTSTR_MAX to process the
+ *                          entire string.
+ * @param   pcwc            Where to store the string length. Optional.
+ *                          This is undefined on failure.
+ */
+RTDECL(int) RTLatin1CalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
+/**
+ * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result
+ * buffer (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
+ *                          returned string must be freed using RTUtf16Free().
+ */
+#define RTLatin1ToUtf16(pszString, ppwszString)     RTLatin1ToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
+/**
+ * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result
+ * buffer (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
+ *                          returned string must be freed using RTUtf16Free().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTLatin1ToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
+/**
+ * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+ * result buffer if requested (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stops when it reaches cchString or
+ *                          the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing
+ *                          to pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at
+ *                          least cwc items will be allocated to hold the
+ *                          translated string. 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,
+ *                          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.
+ */
+#define RTLatin1ToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
+    RTLatin1ToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
+/**
+ * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+ * result buffer if requested.
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stops when it reaches cchString or
+ *                          the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing
+ *                          to pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at
+ *                          least cwc items will be allocated to hold the
+ *                          translated string. 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,
+ *                          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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTLatin1ToUtf16ExTag(const char *pszString, size_t cchString,
+                                 PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
+/** @} */
+#ifndef ___iprt_nocrt_string_h
+# if defined(RT_OS_WINDOWS)
+RTDECL(void *) mempcpy(void *pvDst, const void *pvSrc, size_t cb);
+# endif
+RT_C_DECLS_END
 #endif
-RT_C_DECLS_END
-/** @} */
-#endif

trunk/include/iprt/utf16.h

-              r57927
+              r57941
 /** @file
  * IPRT - String Manipulation.
+ * IPRT - String Manipulation, UTF-16 encoding.
  */
 …
  */
+#ifndef ___iprt_string_h
+#define ___iprt_string_h
+#include <iprt/cdefs.h>
+#include <iprt/types.h>
+#include <iprt/assert.h>
+#include <iprt/stdarg.h>
+#include <iprt/err.h> /* for VINF_SUCCESS */
+#if defined(RT_OS_LINUX) && defined(__KERNEL__)
+  RT_C_DECLS_BEGIN
+# define new newhack /* string.h: strreplace */
+# include <linux/string.h>
+# undef new
+  RT_C_DECLS_END
+#elif defined(IN_XF86_MODULE) && !defined(NO_ANSIC)
+  RT_C_DECLS_BEGIN
+# include "xf86_ansic.h"
+  RT_C_DECLS_END
+#elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
+  RT_C_DECLS_BEGIN
+  /** @todo
+   * XXX: Very ugly hack to get things build on recent FreeBSD builds. They have
+   * memchr now and we need to include param.h to get __FreeBSD_version and make
+   * memchr available based on the version below or we can't compile the kernel
+   * module on older versions anymore.
+   *
+   * But including param.h here opens Pandora's box because we clash with a few
+   * defines namely PVM and PAGE_SIZE. We can safely undefine PVM here but not
+   * PAGE_SIZE because this results in build errors sooner or later. Luckily this
+   * define is in a header included by param.h (machine/param.h). We define the
+   * guards here to prevent inclusion of it if PAGE_SIZE was defined already.
+   *
+   * @todo aeichner: Search for an elegant solution and cleanup this mess ASAP!
+   */
+# ifdef PAGE_SIZE
+#  define _AMD64_INCLUDE_PARAM_H_
+#  define _I386_INCLUDE_PARAM_H_
+#  define _MACHINE_PARAM_H_
+# endif
+# include <sys/param.h> /* __FreeBSD_version */
+# undef PVM
+# include <sys/libkern.h>
+  /*
+   * No memmove on versions < 7.2
+   * Defining a macro using bcopy here
+   */
+# define memmove(dst, src, size) bcopy(src, dst, size)
+  RT_C_DECLS_END
+#elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
+  /*
+   * Same case as with FreeBSD kernel:
+   * The string.h stuff clashes with sys/system.h
+   * ffs = find first set bit.
+   */
+# define ffs ffs_string_h
+# include <string.h>
+# undef ffs
+# undef strpbrk
+#else
+# include <string.h>
+#endif
+/*
+ * Supply prototypes for standard string functions provided by
+ * IPRT instead of the operating environment.
+ */
+#if defined(RT_OS_DARWIN) && defined(KERNEL)
+#ifndef ___iprt_utf16_h
+#define ___iprt_utf16_h
+#include <iprt/string.h>
 RT_C_DECLS_BEGIN
-void *memchr(const void *pv, int ch, size_t cb);
-char *strpbrk(const char *pszStr, const char *pszChars);
-RT_C_DECLS_END
-#endif
-#if defined(RT_OS_FREEBSD) && defined(_KERNEL)
-RT_C_DECLS_BEGIN
-#if __FreeBSD_version < 900000
-void *memchr(const void *pv, int ch, size_t cb);
-#endif
-char *strpbrk(const char *pszStr, const char *pszChars);
-RT_C_DECLS_END
-#endif
-#if !defined(RT_OS_LINUX) || !defined(_GNU_SOURCE)
-RT_C_DECLS_BEGIN
-void *memrchr(const char *pv, int ch, size_t cb);
-RT_C_DECLS_END
-#endif
-/** @def RT_USE_RTC_3629
- * When defined the UTF-8 range will stop at  0x10ffff.  If not defined, the
- * range stops at 0x7fffffff.
- * @remarks Must be defined both when building and using the IPRT.  */
-#ifdef DOXYGEN_RUNNING
-# define RT_USE_RTC_3629
-#endif
-/**
- * Byte zero the specified object.
+ *
- * This will use sizeof(Obj) to figure the size and will call memset, bzero
- * or some compiler intrinsic to perform the actual zeroing.
+ *
- * @param   Obj     The object to zero. Make sure to dereference pointers.
+ *
- * @remarks Because the macro may use memset it has been placed in string.h
- *          instead of cdefs.h to avoid build issues because someone forgot
- *          to include this header.
+ *
- * @ingroup grp_rt_cdefs
- */
-#define RT_ZERO(Obj)        RT_BZERO(&(Obj), sizeof(Obj))
-/**
- * Byte zero the specified memory area.
+ *
- * This will call memset, bzero or some compiler intrinsic to clear the
- * specified bytes of memory.
+ *
- * @param   pv          Pointer to the memory.
- * @param   cb          The number of bytes to clear. Please, don't pass 0.
+ *
- * @remarks Because the macro may use memset it has been placed in string.h
- *          instead of cdefs.h to avoid build issues because someone forgot
- *          to include this header.
+ *
- * @ingroup grp_rt_cdefs
- */
-#define RT_BZERO(pv, cb)    do { memset((pv), 0, cb); } while (0)
-/** @defgroup grp_rt_str    RTStr - String Manipulation
- * Mostly UTF-8 related helpers where the standard string functions won't do.
- * @ingroup grp_rt
- * @{
- */
-RT_C_DECLS_BEGIN
-/**
- * The maximum string length.
- */
-#define RTSTR_MAX       (~(size_t)0)
-/** @def RTSTR_TAG
- * The default allocation tag used by the RTStr allocation APIs.
+ *
- * When not defined before the inclusion of iprt/string.h, this will default to
- * the pointer to the current file name.  The string API will make of use of
- * this as pointer to a volatile but read-only string.
- */
-#if !defined(RTSTR_TAG) || defined(DOXYGEN_RUNNING)
-# define RTSTR_TAG      (__FILE__)
-#endif
-#ifdef IN_RING3
-/**
- * Allocates tmp buffer with default tag, translates pszString from UTF8 to
- * current codepage.
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of allocated native CP string.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszString       UTF-8 string to convert.
- */
-#define RTStrUtf8ToCurrentCP(ppszString, pszString)     RTStrUtf8ToCurrentCPTag((ppszString), (pszString), RTSTR_TAG)
-/**
- * Allocates tmp buffer with custom tag, translates pszString from UTF8 to
- * current codepage.
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of allocated native CP string.
- *                          The returned pointer must be freed using
- *                          RTStrFree()., const char *pszTag
- * @param   pszString       UTF-8 string to convert.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTR3DECL(int)  RTStrUtf8ToCurrentCPTag(char **ppszString, const char *pszString, const char *pszTag);
-/**
- * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of allocated UTF-8 string.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszString       Native string to convert.
- */
-#define RTStrCurrentCPToUtf8(ppszString, pszString)     RTStrCurrentCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
-/**
- * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of allocated UTF-8 string.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszString       Native string to convert.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTR3DECL(int)  RTStrCurrentCPToUtf8Tag(char **ppszString, const char *pszString, const char *pszTag);
-#endif /* IN_RING3 */
-/**
- * Free string allocated by any of the non-UCS-2 string functions.
+ *
- * @returns iprt status code.
- * @param   pszString      Pointer to buffer with string to free.
- *                         NULL is accepted.
- */
-RTDECL(void)  RTStrFree(char *pszString);
-/**
- * Allocates a new copy of the given UTF-8 string (default tag).
+ *
- * @returns Pointer to the allocated UTF-8 string.
- * @param   pszString       UTF-8 string to duplicate.
- */
-#define RTStrDup(pszString)             RTStrDupTag((pszString), RTSTR_TAG)
-/**
- * Allocates a new copy of the given UTF-8 string (custom tag).
+ *
- * @returns Pointer to the allocated UTF-8 string.
- * @param   pszString       UTF-8 string to duplicate.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(char *) RTStrDupTag(const char *pszString, const char *pszTag);
-/**
- * Allocates a new copy of the given UTF-8 string (default tag).
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of the allocated UTF-8 string.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszString       UTF-8 string to duplicate.
- */
-#define RTStrDupEx(ppszString, pszString)   RTStrDupExTag((ppszString), (pszString), RTSTR_TAG)
-/**
- * Allocates a new copy of the given UTF-8 string (custom tag).
+ *
- * @returns iprt status code.
- * @param   ppszString      Receives pointer of the allocated UTF-8 string.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszString       UTF-8 string to duplicate.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTStrDupExTag(char **ppszString, const char *pszString, const char *pszTag);
-/**
- * Allocates a new copy of the given UTF-8 substring (default tag).
+ *
- * @returns Pointer to the allocated UTF-8 substring.
- * @param   pszString       UTF-8 string to duplicate.
- * @param   cchMax          The max number of chars to duplicate, not counting
- *                          the terminator.
- */
-#define RTStrDupN(pszString, cchMax)        RTStrDupNTag((pszString), (cchMax), RTSTR_TAG)
-/**
- * Allocates a new copy of the given UTF-8 substring (custom tag).
+ *
- * @returns Pointer to the allocated UTF-8 substring.
- * @param   pszString       UTF-8 string to duplicate.
- * @param   cchMax          The max number of chars to duplicate, not counting
- *                          the terminator.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(char *) RTStrDupNTag(const char *pszString, size_t cchMax, const char *pszTag);
-/**
- * Appends a string onto an existing IPRT allocated string (default tag).
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   pszAppend           The string to append.  NULL and empty strings
- *                              are quietly ignored.
- */
-#define RTStrAAppend(ppsz, pszAppend)   RTStrAAppendTag((ppsz), (pszAppend), RTSTR_TAG)
-/**
- * Appends a string onto an existing IPRT allocated string (custom tag).
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   pszAppend           The string to append.  NULL and empty strings
- *                              are quietly ignored.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrAAppendTag(char **ppsz, const char *pszAppend, const char *pszTag);
-/**
- * Appends N bytes from a strings onto an existing IPRT allocated string
- * (default tag).
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   pszAppend           The string to append.  Can be NULL if cchAppend
- *                              is NULL.
- * @param   cchAppend           The number of chars (not code points) to append
- *                              from pszAppend.   Must not be more than
- *                              @a pszAppend contains, except for the special
- *                              value RTSTR_MAX that can be used to indicate all
- *                              of @a pszAppend without having to strlen it.
- */
-#define RTStrAAppendN(ppsz, pszAppend, cchAppend)   RTStrAAppendNTag((ppsz), (pszAppend), (cchAppend), RTSTR_TAG)
-/**
- * Appends N bytes from a strings onto an existing IPRT allocated string (custom
- * tag).
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   pszAppend           The string to append.  Can be NULL if cchAppend
- *                              is NULL.
- * @param   cchAppend           The number of chars (not code points) to append
- *                              from pszAppend.   Must not be more than
- *                              @a pszAppend contains, except for the special
- *                              value RTSTR_MAX that can be used to indicate all
- *                              of @a pszAppend without having to strlen it.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrAAppendNTag(char **ppsz, const char *pszAppend, size_t cchAppend, const char *pszTag);
-/**
- * Appends one or more strings onto an existing IPRT allocated string.
+ *
- * This is a very flexible and efficient alternative to using RTStrAPrintf to
- * combine several strings together.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   cPairs              The number of string / length pairs in the
- *                              @a va.
- * @param   va                  List of string (const char *) and length
- *                              (size_t) pairs.  The strings will be appended to
- *                              the string in the first argument.
- */
-#define RTStrAAppendExNV(ppsz, cPairs, va)  RTStrAAppendExNVTag((ppsz), (cPairs), (va), RTSTR_TAG)
-/**
- * Appends one or more strings onto an existing IPRT allocated string.
+ *
- * This is a very flexible and efficient alternative to using RTStrAPrintf to
- * combine several strings together.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   cPairs              The number of string / length pairs in the
- *                              @a va.
- * @param   va                  List of string (const char *) and length
- *                              (size_t) pairs.  The strings will be appended to
- *                              the string in the first argument.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrAAppendExNVTag(char **ppsz, size_t cPairs, va_list va, const char *pszTag);
-/**
- * Appends one or more strings onto an existing IPRT allocated string
- * (untagged).
+ *
- * This is a very flexible and efficient alternative to using RTStrAPrintf to
- * combine several strings together.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   cPairs              The number of string / length pairs in the
- *                              ellipsis.
- * @param   ...                 List of string (const char *) and length
- *                              (size_t) pairs.  The strings will be appended to
- *                              the string in the first argument.
- */
-DECLINLINE(int) RTStrAAppendExN(char **ppsz, size_t cPairs, ...)
+{
-    int     rc;
-    va_list va;
-    va_start(va, cPairs);
-    rc = RTStrAAppendExNVTag(ppsz, cPairs, va, RTSTR_TAG);
-    va_end(va);
-    return rc;
+}
-/**
- * Appends one or more strings onto an existing IPRT allocated string (custom
- * tag).
+ *
- * This is a very flexible and efficient alternative to using RTStrAPrintf to
- * combine several strings together.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer must either be NULL or point to a string
- *                              returned by an IPRT string API.  (In/Out)
- * @param   pszTag              Allocation tag used for statistics and such.
- * @param   cPairs              The number of string / length pairs in the
- *                              ellipsis.
- * @param   ...                 List of string (const char *) and length
- *                              (size_t) pairs.  The strings will be appended to
- *                              the string in the first argument.
- */
-DECLINLINE(int) RTStrAAppendExNTag(char **ppsz, const char *pszTag, size_t cPairs, ...)
+{
-    int     rc;
-    va_list va;
-    va_start(va, cPairs);
-    rc = RTStrAAppendExNVTag(ppsz, cPairs, va, pszTag);
-    va_end(va);
-    return rc;
+}
-/**
- * Truncates an IPRT allocated string (default tag).
+ *
- * @retval  VINF_SUCCESS.
- * @retval  VERR_OUT_OF_RANGE if cchNew is too long.  Nothing is done.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer can be NULL if @a cchNew is 0, no change
- *                              is made then.  If we actually reallocate the
- *                              string, the string pointer might be changed by
- *                              this call.  (In/Out)
- * @param   cchNew              The new string length (excluding the
- *                              terminator).  The string must be at least this
- *                              long or we'll return VERR_OUT_OF_RANGE and
- *                              assert on you.
- */
-#define RTStrATruncate(ppsz, cchNew)    RTStrATruncateTag((ppsz), (cchNew), RTSTR_TAG)
-/**
- * Truncates an IPRT allocated string.
+ *
- * @retval  VINF_SUCCESS.
- * @retval  VERR_OUT_OF_RANGE if cchNew is too long.  Nothing is done.
+ *
- * @param   ppsz                Pointer to the string pointer.  The string
- *                              pointer can be NULL if @a cchNew is 0, no change
- *                              is made then.  If we actually reallocate the
- *                              string, the string pointer might be changed by
- *                              this call.  (In/Out)
- * @param   cchNew              The new string length (excluding the
- *                              terminator).  The string must be at least this
- *                              long or we'll return VERR_OUT_OF_RANGE and
- *                              assert on you.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrATruncateTag(char **ppsz, size_t cchNew, const char *pszTag);
-/**
- * Allocates memory for string storage (default tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @returns Pointer to the allocated string.  The first byte is always set
- *          to the string terminator char, the contents of the remainder of the
- *          memory is undefined.  The string must be freed by calling RTStrFree.
+ *
- *          NULL is returned if the allocation failed.  Please translate this to
- *          VERR_NO_STR_MEMORY and not VERR_NO_MEMORY.  Also consider
- *          RTStrAllocEx if an IPRT status code is required.
+ *
- * @param   cb                  How many bytes to allocate.  If this is zero, we
- *                              will allocate a terminator byte anyway.
- */
-#define RTStrAlloc(cb)                  RTStrAllocTag((cb), RTSTR_TAG)
-/**
- * Allocates memory for string storage (custom tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @returns Pointer to the allocated string.  The first byte is always set
- *          to the string terminator char, the contents of the remainder of the
- *          memory is undefined.  The string must be freed by calling RTStrFree.
+ *
- *          NULL is returned if the allocation failed.  Please translate this to
- *          VERR_NO_STR_MEMORY and not VERR_NO_MEMORY.  Also consider
- *          RTStrAllocEx if an IPRT status code is required.
+ *
- * @param   cb                  How many bytes to allocate.  If this is zero, we
- *                              will allocate a terminator byte anyway.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(char *) RTStrAllocTag(size_t cb, const char *pszTag);
-/**
- * Allocates memory for string storage, with status code (default tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY
+ *
- * @param   ppsz                Where to return the allocated string.  This will
- *                              be set to NULL on failure.  On success, the
- *                              returned memory will always start with a
- *                              terminator char so that it is considered a valid
- *                              C string, the contents of rest of the memory is
- *                              undefined.
- * @param   cb                  How many bytes to allocate.  If this is zero, we
- *                              will allocate a terminator byte anyway.
- */
-#define RTStrAllocEx(ppsz, cb)      RTStrAllocExTag((ppsz), (cb), RTSTR_TAG)
-/**
- * Allocates memory for string storage, with status code (custom tag).
+ *
- * You should normally not use this function, except if there is some very
- * custom string handling you need doing that isn't covered by any of the other
- * APIs.
+ *
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_STR_MEMORY
+ *
- * @param   ppsz                Where to return the allocated string.  This will
- *                              be set to NULL on failure.  On success, the
- *                              returned memory will always start with a
- *                              terminator char so that it is considered a valid
- *                              C string, the contents of rest of the memory is
- *                              undefined.
- * @param   cb                  How many bytes to allocate.  If this is zero, we
- *                              will allocate a terminator byte anyway.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrAllocExTag(char **ppsz, size_t cb, const char *pszTag);
-/**
- * Reallocates the specified string (default tag).
+ *
- * You should normally not have use this function, except perhaps to truncate a
- * really long string you've got from some IPRT string API, but then you should
- * use RTStrATruncate.
+ *
- * @returns VINF_SUCCESS.
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string variable containing the
- *                              input and output string.
+ *
- *                              When not freeing the string, the result will
- *                              always have the last byte set to the terminator
- *                              character so that when used for string
- *                              truncation the result will be a valid C string
- *                              (your job to keep it a valid UTF-8 string).
+ *
- *                              When the input string is NULL and we're supposed
- *                              to reallocate, the returned string will also
- *                              have the first byte set to the terminator char
- *                              so it will be a valid C string.
+ *
- * @param   cbNew               When @a cbNew is zero, we'll behave like
- *                              RTStrFree and @a *ppsz will be set to NULL.
+ *
- *                              When not zero, this will be the new size of the
- *                              memory backing the string, i.e. it includes the
- *                              terminator char.
- */
-#define RTStrRealloc(ppsz, cbNew)       RTStrReallocTag((ppsz), (cbNew), RTSTR_TAG)
-/**
- * Reallocates the specified string (custom tag).
+ *
- * You should normally not have use this function, except perhaps to truncate a
- * really long string you've got from some IPRT string API, but then you should
- * use RTStrATruncate.
+ *
- * @returns VINF_SUCCESS.
- * @retval  VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
- *          remains unchanged.
+ *
- * @param   ppsz                Pointer to the string variable containing the
- *                              input and output string.
+ *
- *                              When not freeing the string, the result will
- *                              always have the last byte set to the terminator
- *                              character so that when used for string
- *                              truncation the result will be a valid C string
- *                              (your job to keep it a valid UTF-8 string).
+ *
- *                              When the input string is NULL and we're supposed
- *                              to reallocate, the returned string will also
- *                              have the first byte set to the terminator char
- *                              so it will be a valid C string.
+ *
- * @param   cbNew               When @a cbNew is zero, we'll behave like
- *                              RTStrFree and @a *ppsz will be set to NULL.
+ *
- *                              When not zero, this will be the new size of the
- *                              memory backing the string, i.e. it includes the
- *                              terminator char.
- * @param   pszTag              Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrReallocTag(char **ppsz, size_t cbNew, const char *pszTag);
-/**
- * Validates the UTF-8 encoding of the string.
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- */
-RTDECL(int) RTStrValidateEncoding(const char *psz);
-/** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
- */
-/** Check that the string is zero terminated within the given size.
- * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
-#define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED     RT_BIT_32(0)
-/** Check that the string is exactly the given length.
- * If it terminates early, VERR_BUFFER_UNDERFLOW will be returned.  When used
- * together with RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED, the given length must
- * include the terminator or VERR_BUFFER_OVERFLOW will be returned. */
-#define RTSTR_VALIDATE_ENCODING_EXACT_LENGTH        RT_BIT_32(1)
-/** @} */
-/**
- * Validates the UTF-8 encoding of the string.
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length (/ size).  Use RTSTR_MAX to
- *                      process the entire string.
- * @param   fFlags      Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
- */
-RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
-/**
- * Checks if the UTF-8 encoding is valid.
+ *
- * @returns true / false.
- * @param   psz         The string.
- */
-RTDECL(bool) RTStrIsValidEncoding(const char *psz);
-/**
- * Purge all bad UTF-8 encoding in the string, replacing it with '?'.
+ *
- * @returns The number of bad characters (0 if nothing was done).
- * @param   psz         The string to purge.
- */
-RTDECL(size_t) RTStrPurgeEncoding(char *psz);
-/**
- * Sanitise a (valid) UTF-8 string by replacing all characters outside a white
- * list in-place by an ASCII replacement character.  Multi-byte characters will
- * be replaced byte by byte.
+ *
- * @returns The number of code points replaced, or a negative value if the
- *          string is not correctly encoded.  In this last case the string
- *          may be partially processed.
- * @param   psz            The string to sanitise.
- * @param   puszValidSet   A zero-terminated array of pairs of Unicode points.
- *                         Each pair is the start and end point of a range,
- *                         and the union of these ranges forms the white list.
- * @param   chReplacement  The ASCII replacement character.
- */
-RTDECL(ssize_t) RTStrPurgeComplementSet(char *psz, PCRTUNICP puszValidSet, char chReplacement);
-/**
- * Gets the number of code points the string is made up of, excluding
- * the terminator.
+ *
+ *
- * @returns Number of code points (RTUNICP).
- * @returns 0 if the string was incorrectly encoded.
- * @param   psz         The string.
- */
-RTDECL(size_t) RTStrUniLen(const char *psz);
-/**
- * Gets the number of code points the string is made up of, excluding
- * the terminator.
+ *
- * This function will validate the string, and incorrectly encoded UTF-8
- * strings will be rejected.
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
- * @param   pcuc        Where to store the code point count.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
-/**
- * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   ppUniString     Receives pointer to the allocated unicode string.
- *                          The returned string must be freed using RTUniFree().
- */
-RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
-/**
- * Translates pszString from UTF-8 to an array of code points, allocating the result
- * array if requested.
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
- *                          when it reaches cchString or the string terminator ('\\0').
- *                          Use RTSTR_MAX to translate the entire string.
- * @param   ppaCps          If cCps is non-zero, this must either be pointing to pointer to
- *                          a buffer of the specified size, or pointer to a NULL pointer.
- *                          If *ppusz is NULL or cCps is zero a buffer of at least cCps items
- *                          will be allocated to hold the translated string.
- *                          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,
- *                          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);
-/**
- * Calculates the length of the string in RTUTF16 items.
+ *
- * This function will validate the string, and incorrectly encoded UTF-8
- * strings will be rejected. The primary purpose of this function is to
- * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
- * other purposes RTStrCalcUtf16LenEx() should be used.
+ *
- * @returns Number of RTUTF16 items.
- * @returns 0 if the string was incorrectly encoded.
- * @param   psz         The string.
- */
-RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
-/**
- * Calculates the length of the string in RTUTF16 items.
+ *
- * This function will validate the string, and incorrectly encoded UTF-8
- * strings will be rejected.
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
- * @param   pcwc        Where to store the string length. Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
-/**
- * Translate a UTF-8 string into a UTF-16 allocating the result buffer (default
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   ppwszString     Receives pointer to the allocated UTF-16 string.
- *                          The returned string must be freed using RTUtf16Free().
- */
-#define RTStrToUtf16(pszString, ppwszString)    RTStrToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
-/**
- * Translate a UTF-8 string into a UTF-16 allocating the result buffer (custom
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   ppwszString     Receives pointer to the allocated UTF-16 string.
- *                          The returned string must be freed using RTUtf16Free().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
-/**
- * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
- *                          when it reaches cchString or the string terminator ('\\0').
- *                          Use RTSTR_MAX to translate the entire string.
- * @param   ppwsz           If cwc is non-zero, this must either be pointing to pointer to
- *                          a buffer of the specified size, or pointer to a NULL pointer.
- *                          If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
- *                          will be allocated to hold the translated string.
- *                          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,
- *                          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.
- */
-#define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
-    RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
-/**
- * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
- * requested (custom tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   cchString       The maximum size in chars (the type) to convert. The conversion stop
- *                          when it reaches cchString or the string terminator ('\\0').
- *                          Use RTSTR_MAX to translate the entire string.
- * @param   ppwsz           If cwc is non-zero, this must either be pointing to pointer to
- *                          a buffer of the specified size, or pointer to a NULL pointer.
- *                          If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
- *                          will be allocated to hold the translated string.
- *                          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,
- *                          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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTStrToUtf16ExTag(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
-/**
- * Calculates the length of the string in Latin-1 characters.
+ *
- * This function will validate the string, and incorrectly encoded UTF-8
- * strings as well as string with codepoints outside the latin-1 range will be
- * rejected.  The primary purpose of this function is to help allocate buffers
- * for RTStrToLatin1Ex of the correct size.  For most other purposes
- * RTStrCalcLatin1LenEx() should be used.
+ *
- * @returns Number of Latin-1 characters.
- * @returns 0 if the string was incorrectly encoded.
- * @param   psz         The string.
- */
-RTDECL(size_t) RTStrCalcLatin1Len(const char *psz);
-/**
- * Calculates the length of the string in Latin-1 characters.
+ *
- * This function will validate the string, and incorrectly encoded UTF-8
- * strings as well as string with codepoints outside the latin-1 range will be
- * rejected.
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length. Use RTSTR_MAX to process the
- *                      entire string.
- * @param   pcch        Where to store the string length. Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTStrCalcLatin1LenEx(const char *psz, size_t cch, size_t *pcch);
-/**
- * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   ppszString      Receives pointer to the allocated Latin-1 string.
- *                          The returned string must be freed using RTStrFree().
- */
-#define RTStrToLatin1(pszString, ppszString)    RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
-/**
- * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   ppszString      Receives pointer to the allocated Latin-1 string.
- *                          The returned string must be freed using RTStrFree().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrToLatin1Tag(const char *pszString, char **ppszString, const char *pszTag);
-/**
- * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   cchString       The maximum size in chars (the type) to convert.
- *                          The conversion stop when it reaches cchString or
- *                          the string terminator ('\\0'). Use RTSTR_MAX to
- *                          translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch items will be
- *                          allocated to hold the translated string. If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in bytes. This includes the
- *                          terminator.
- * @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.
- */
-#define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
-    RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
-/**
- * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
- * requested (custom tag).
+ *
- * @returns iprt status code.
- * @param   pszString       UTF-8 string to convert.
- * @param   cchString       The maximum size in chars (the type) to convert.
- *                          The conversion stop when it reaches cchString or
- *                          the string terminator ('\\0'). Use RTSTR_MAX to
- *                          translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch items will be
- *                          allocated to hold the translated string. If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in bytes.  This includes the
- *                          terminator.
- * @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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTStrToLatin1ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Translate a Latin1 string into a UTF-8 allocating the result buffer (default
- * tag).
+ *
- * @returns iprt status code.
- * @param   pszString       Latin1 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- */
-#define RTLatin1ToUtf8(pszString, ppszString)       RTLatin1ToUtf8Tag((pszString), (ppszString), RTSTR_TAG)
-/**
- * Translate a Latin-1 string into a UTF-8 allocating the result buffer.
+ *
- * @returns iprt status code.
- * @param   pszString       Latin-1 string to convert.
- * @param   ppszString      Receives pointer of allocated UTF-8 string on
- *                          success, and is always set to NULL on failure.
- *                          The returned pointer must be freed using RTStrFree().
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTLatin1ToUtf8Tag(const char *pszString, char **ppszString, const char *pszTag);
-/**
- * Translates Latin-1 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (default tag).
+ *
- * @returns iprt status code.
- * @param   pszString       The Latin-1 string to convert.
- * @param   cchString       The number of Latin-1 characters to translate from
- *                          pszString. The translation will stop when reaching
- *                          cchString or the terminator ('\\0').  Use RTSTR_MAX
- *                          to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          a pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch chars will be
- *                          allocated to hold the translated string. If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in chars (the type). This includes the terminator.
- * @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.
- */
-#define RTLatin1ToUtf8Ex(pszString, cchString, ppsz, cch, pcch) \
-    RTLatin1ToUtf8ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
-/**
- * Translates Latin1 to UTF-8 using buffer provided by the caller or a fittingly
- * sized buffer allocated by the function (custom tag).
+ *
- * @returns iprt status code.
- * @param   pszString       The Latin1 string to convert.
- * @param   cchString       The number of Latin1 characters to translate from
- *                          pwszString.  The translation will stop when
- *                          reaching cchString or the terminator ('\\0').  Use
- *                          RTSTR_MAX to translate the entire string.
- * @param   ppsz            If cch is non-zero, this must either be pointing to
- *                          a pointer to a buffer of the specified size, or
- *                          pointer to a NULL pointer.  If *ppsz is NULL or cch
- *                          is zero a buffer of at least cch chars will be
- *                          allocated to hold the translated string.  If a
- *                          buffer was requested it must be freed using
- *                          RTStrFree().
- * @param   cch             The buffer size in chars (the type).  This includes
- *                          the terminator.
- * @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.
- * @param   pszTag          Allocation tag used for statistics and such.
- */
-RTDECL(int)  RTLatin1ToUtf8ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
-/**
- * Calculates the length of the Latin-1 string in UTF-8 chars (bytes).
+ *
- * The primary purpose of this function is to help allocate buffers for
- * RTLatin1ToUtf8() of the correct size. For most other purposes
- * RTLatin1ToUtf8Ex() should be used.
+ *
- * @returns Number of chars (bytes).
- * @returns 0 if the string was incorrectly encoded.
- * @param   psz        The Latin-1 string.
- */
-RTDECL(size_t) RTLatin1CalcUtf8Len(const char *psz);
-/**
- * Calculates the length of the Latin-1 string in UTF-8 chars (bytes).
+ *
- * @returns iprt status code.
- * @param   psz         The string.
- * @param   cch         The max string length. Use RTSTR_MAX to process the entire string.
- * @param   pcch        Where to store the string length (in bytes).  Optional.
- *                      This is undefined on failure.
- */
-RTDECL(int) RTLatin1CalcUtf8LenEx(const char *psz, size_t cch, size_t *pcch);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   psz         The string.
- */
-RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code
- * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
- * @param   ppsz        The string cursor.
- *                      This is advanced one character forward on failure.
- * @param   pCp         Where to store the unicode code point.
- *                      Stores RTUNICP_INVALID if the encoding is invalid.
- */
-RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
-/**
- * Get the unicode code point at the given string position for a string of a
- * given length.
+ *
- * @returns iprt status code
- * @retval  VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
- * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
- * @param   ppsz        The string.
- * @param   pcch        Pointer to the length of the string.  This will be
- *                      decremented by the size of the code point.
- * @param   pCp         Where to store the unicode code point.
- *                      Stores RTUNICP_INVALID if the encoding is invalid.
- */
-RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by psz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   psz         The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the UTF-8 range.
+ *
- * @remark  This is a worker function for RTStrPutCp().
+ *
- */
-RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   psz         The string.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrGetCpInternal().
- */
-DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
+{
-    const unsigned char uch = *(const unsigned char *)psz;
-    if (!(uch & RT_BIT(7)))
-        return uch;
-    return RTStrGetCpInternal(psz);
+}
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code.
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- *                      This is advanced one character forward on failure.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrGetCpExInternal().
- */
-DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
+{
-    const unsigned char uch = **(const unsigned char **)ppsz;
-    if (!(uch & RT_BIT(7)))
+    {
-        (*ppsz)++;
-        *pCp = uch;
-        return VINF_SUCCESS;
+    }
-    return RTStrGetCpExInternal(ppsz, pCp);
+}
-/**
- * Get the unicode code point at the given string position for a string of a
- * given maximum length.
+ *
- * @returns iprt status code.
- * @retval  VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
- * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- * @param   pcch        Pointer to the maximum string length.  This will be
- *                      decremented by the size of the code point found.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrGetCpNExInternal().
- */
-DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
+{
-    if (RT_LIKELY(*pcch != 0))
+    {
-        const unsigned char uch = **(const unsigned char **)ppsz;
-        if (!(uch & RT_BIT(7)))
+        {
-            (*ppsz)++;
-            (*pcch)--;
-            *pCp = uch;
-            return VINF_SUCCESS;
+        }
+    }
-    return RTStrGetCpNExInternal(ppsz, pcch, pCp);
+}
-/**
- * Get the UTF-8 size in characters of a given Unicode code point.
+ *
- * The code point is expected to be a valid Unicode one, but not necessarily in
- * the range supported by UTF-8.
+ *
- * @returns The number of chars (bytes) required to encode the code point, or
- *          zero if there is no UTF-8 encoding.
- * @param   CodePoint       The unicode code point.
- */
-DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint)
+{
-    if (CodePoint < 0x00000080)
-        return 1;
-    if (CodePoint < 0x00000800)
-        return 2;
-    if (CodePoint < 0x00010000)
-        return 3;
-#ifdef RT_USE_RTC_3629
-    if (CodePoint < 0x00011000)
-        return 4;
-#else
-    if (CodePoint < 0x00200000)
-        return 4;
-    if (CodePoint < 0x04000000)
-        return 5;
-    if (CodePoint < 0x7fffffff)
-        return 6;
-#endif
-    return 0;
+}
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by psz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   psz         The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the UTF-8 range.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrPutCpInternal().
- */
-DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
+{
-    if (CodePoint < 0x80)
+    {
-        *psz++ = (unsigned char)CodePoint;
-        return psz;
+    }
-    return RTStrPutCpInternal(psz, CodePoint);
+}
-/**
- * Skips ahead, past the current code point.
+ *
- * @returns Pointer to the char after the current code point.
- * @param   psz     Pointer to the current code point.
- * @remark  This will not move the next valid code point, only past the current one.
- */
-DECLINLINE(char *) RTStrNextCp(const char *psz)
+{
-    RTUNICP Cp;
-    RTStrGetCpEx(&psz, &Cp);
-    return (char *)psz;
+}
-/**
- * Skips back to the previous code point.
+ *
- * @returns Pointer to the char before the current code point.
- * @returns pszStart on failure.
- * @param   pszStart    Pointer to the start of the string.
- * @param   psz         Pointer to the current code point.
- */
-RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns unicode code point.
- * @returns RTUNICP_INVALID if the encoding is invalid.
- * @param   psz         The string.
- */
-DECLINLINE(RTUNICP) RTLatin1GetCp(const char *psz)
+{
-    return *(const unsigned char *)psz;
+}
-/**
- * Get the unicode code point at the given string position.
+ *
- * @returns iprt status code.
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- *                      This is advanced one character forward on failure.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
+ *
- * @remark  We optimize this operation by using an inline function for
- *          the most frequent and simplest sequence, the rest is
- *          handled by RTStrGetCpExInternal().
- */
-DECLINLINE(int) RTLatin1GetCpEx(const char **ppsz, PRTUNICP pCp)
+{
-    const unsigned char uch = **(const unsigned char **)ppsz;
-    (*ppsz)++;
-    *pCp = uch;
-    return VINF_SUCCESS;
+}
-/**
- * Get the unicode code point at the given string position for a string of a
- * given maximum length.
+ *
- * @returns iprt status code.
- * @retval  VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
+ *
- * @param   ppsz        Pointer to the string pointer. This will be updated to
- *                      point to the char following the current code point.
- * @param   pcch        Pointer to the maximum string length.  This will be
- *                      decremented by the size of the code point found.
- * @param   pCp         Where to store the code point.
- *                      RTUNICP_INVALID is stored here on failure.
- */
-DECLINLINE(int) RTLatin1GetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
+{
-    if (RT_LIKELY(*pcch != 0))
+    {
-        const unsigned char uch = **(const unsigned char **)ppsz;
-        (*ppsz)++;
-        (*pcch)--;
-        *pCp = uch;
-        return VINF_SUCCESS;
+    }
-    *pCp = RTUNICP_INVALID;
-    return VERR_END_OF_STRING;
+}
-/**
- * Get the Latin-1 size in characters of a given Unicode code point.
+ *
- * The code point is expected to be a valid Unicode one, but not necessarily in
- * the range supported by Latin-1.
+ *
- * @returns the size in characters, or zero if there is no Latin-1 encoding
- */
-DECLINLINE(size_t) RTLatin1CpSize(RTUNICP CodePoint)
+{
-    if (CodePoint < 0x100)
-        return 1;
-    return 0;
+}
-/**
- * Put the unicode code point at the given string position
- * and return the pointer to the char following it.
+ *
- * This function will not consider anything at or following the
- * buffer area pointed to by psz. It is therefore not suitable for
- * inserting code points into a string, only appending/overwriting.
+ *
- * @returns pointer to the char following the written code point.
- * @param   psz         The string.
- * @param   CodePoint   The code point to write.
- *                      This should not be RTUNICP_INVALID or any other
- *                      character out of the Latin-1 range.
- */
-DECLINLINE(char *) RTLatin1PutCp(char *psz, RTUNICP CodePoint)
+{
-    AssertReturn(CodePoint < 0x100, NULL);
-    *psz++ = (unsigned char)CodePoint;
-    return psz;
+}
-/**
- * Skips ahead, past the current code point.
+ *
- * @returns Pointer to the char after the current code point.
- * @param   psz     Pointer to the current code point.
- * @remark  This will not move the next valid code point, only past the current one.
- */
-DECLINLINE(char *) RTLatin1NextCp(const char *psz)
+{
-    psz++;
-    return (char *)psz;
+}
-/**
- * Skips back to the previous code point.
+ *
- * @returns Pointer to the char before the current code point.
- * @returns pszStart on failure.
- * @param   pszStart    Pointer to the start of the string.
- * @param   psz         Pointer to the current code point.
- */
-DECLINLINE(char *) RTLatin1PrevCp(const char *pszStart, const char *psz)
+{
-    if ((uintptr_t)psz > (uintptr_t)pszStart)
+    {
-        psz--;
-        return (char *)psz;
+    }
-    return (char *)pszStart;
+}
-/** @page pg_rt_str_format  The IPRT Format Strings
+ *
- * IPRT implements most of the commonly used format types and flags with the
- * exception of floating point which is completely missing.  In addition IPRT
- * provides a number of IPRT specific format types for the IPRT typedefs and
- * other useful things.  Note that several of these extensions are similar to
- * \%p and doesn't care much if you try add formating flags/width/precision.
+ *
+ *
- * Group 0a, The commonly used format types:
- *      - \%s   - Takes a pointer to a zero terminated string (UTF-8) and
- *                prints it with the optionally adjustment (width, -) and
- *                length restriction (precision).
- *      - \%ls  - Same as \%s except that the input is UTF-16 (output UTF-8).
- *      - \%Ls  - Same as \%s except that the input is UCS-32 (output UTF-8).
- *      - \%S   - Same as \%s, used to convert to current codeset but this is
- *                now done by the streams code.  Deprecated, use \%s.
- *      - \%lS  - Ditto. Deprecated, use \%ls.
- *      - \%LS  - Ditto. Deprecated, use \%Ls.
- *      - \%c   - Takes a char and prints it.
- *      - \%d   - Takes a signed integer and prints it as decimal. Thousand
- *                separator (\'), zero padding (0), adjustment (-+), width,
- *                precision
- *      - \%i   - Same as \%d.
- *      - \%u   - Takes an unsigned integer and prints it as decimal. Thousand
- *                separator (\'), zero padding (0), adjustment (-+), width,
- *                precision
- *      - \%x   - Takes an unsigned integer and prints it as lowercased
- *                hexadecimal.  The special hash (\#) flag causes a '0x'
- *                prefixed to be printed. Zero padding (0), adjustment (-+),
- *                width, precision.
- *      - \%X   - Same as \%x except that it is uppercased.
- *      - \%o   - Takes an unsigned (?) integer and prints it as octal. Zero
- *                padding (0), adjustment (-+), width, precision.
- *      - \%p   - Takes a pointer (void technically) and prints it. Zero
- *                padding (0), adjustment (-+), width, precision.
+ *
- * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
- * argument type specifiers:
- *      - \%ll  - long long (uint64_t).
- *      - \%L   - long long (uint64_t).
- *      - \%l   - long (uint32_t, uint64_t)
- *      - \%h   - short (int16_t).
- *      - \%hh  - char (int8_t).
- *      - \%H   - char (int8_t).
- *      - \%z   - size_t.
- *      - \%j   - intmax_t (int64_t).
- *      - \%t   - ptrdiff_t.
- * The type in parentheses is typical sizes, however when printing those types
- * you are better off using the special group 2 format types below (\%RX32 and
- * such).
+ *
+ *
- * Group 0b, IPRT format tricks:
- *      - %M    - Replaces the format string, takes a string pointer.
- *      - %N    - Nested formatting, takes a pointer to a format string
- *                followed by the pointer to a va_list variable.  The va_list
- *                variable will not be modified and the caller must do va_end()
- *                on it.  Make sure the va_list variable is NOT in a parameter
- *                list or some gcc versions/targets may get it all wrong.
+ *
+ *
- * Group 1, the basic runtime typedefs (excluding those which obviously are
- * pointer):
- *      - \%RTbool          - Takes a bool value and prints 'true', 'false', or '!%d!'.
- *      - \%RTfile          - Takes a #RTFILE value.
- *      - \%RTfmode         - Takes a #RTFMODE value.
- *      - \%RTfoff          - Takes a #RTFOFF value.
- *      - \%RTfp16          - Takes a #RTFAR16 value.
- *      - \%RTfp32          - Takes a #RTFAR32 value.
- *      - \%RTfp64          - Takes a #RTFAR64 value.
- *      - \%RTgid           - Takes a #RTGID value.
- *      - \%RTino           - Takes a #RTINODE value.
- *      - \%RTint           - Takes a #RTINT value.
- *      - \%RTiop           - Takes a #RTIOPORT value.
- *      - \%RTldrm          - Takes a #RTLDRMOD value.
- *      - \%RTmac           - Takes a #PCRTMAC pointer.
- *      - \%RTnaddr         - Takes a #PCRTNETADDR value.
- *      - \%RTnaipv4        - Takes a #RTNETADDRIPV4 value.
- *      - \%RTnaipv6        - Takes a #PCRTNETADDRIPV6 value.
- *      - \%RTnthrd         - Takes a #RTNATIVETHREAD value.
- *      - \%RTnthrd         - Takes a #RTNATIVETHREAD value.
- *      - \%RTproc          - Takes a #RTPROCESS value.
- *      - \%RTptr           - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
- *      - \%RTreg           - Takes a #RTCCUINTREG value.
- *      - \%RTsel           - Takes a #RTSEL value.
- *      - \%RTsem           - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
- *      - \%RTsock          - Takes a #RTSOCKET value.
- *      - \%RTthrd          - Takes a #RTTHREAD value.
- *      - \%RTuid           - Takes a #RTUID value.
- *      - \%RTuint          - Takes a #RTUINT value.
- *      - \%RTunicp         - Takes a #RTUNICP value.
- *      - \%RTutf16         - Takes a #RTUTF16 value.
- *      - \%RTuuid          - Takes a #PCRTUUID and will print the UUID as a string.
- *      - \%RTxuint         - Takes a #RTUINT or #RTINT value, formatting it as hex.
- *      - \%RGi             - Takes a #RTGCINT value.
- *      - \%RGp             - Takes a #RTGCPHYS value.
- *      - \%RGr             - Takes a #RTGCUINTREG value.
- *      - \%RGu             - Takes a #RTGCUINT value.
- *      - \%RGv             - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
- *      - \%RGx             - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
- *      - \%RHi             - Takes a #RTHCINT value.
- *      - \%RHp             - Takes a #RTHCPHYS value.
- *      - \%RHr             - Takes a #RTHCUINTREG value.
- *      - \%RHu             - Takes a #RTHCUINT value.
- *      - \%RHv             - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
- *      - \%RHx             - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
- *      - \%RRv             - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
- *      - \%RCi             - Takes a #RTINT value.
- *      - \%RCp             - Takes a #RTCCPHYS value.
- *      - \%RCr             - Takes a #RTCCUINTREG value.
- *      - \%RCu             - Takes a #RTUINT value.
- *      - \%RCv             - Takes a #uintptr_t, #intptr_t, void * value.
- *      - \%RCx             - Takes a #RTUINT or #RTINT value, formatting it as hex.
+ *
+ *
- * Group 2, the generic integer types which are prefered over relying on what
- * bit-count a 'long', 'short',  or 'long long' has on a platform. This are
- * highly prefered for the [u]intXX_t kind of types:
- *      - \%RI[8|16|32|64]  - Signed integer value of the specifed bit count.
- *      - \%RU[8|16|32|64]  - Unsigned integer value of the specifed bit count.
- *      - \%RX[8|16|32|64]  - Hexadecimal integer value of the specifed bit count.
+ *
+ *
- * Group 3, hex dumpers and other complex stuff which requires more than simple
- * formatting:
- *      - \%Rhxd            - Takes a pointer to the memory which is to be dumped in typical
- *                            hex format. Use the precision to specify the length, and the width to
- *                            set the number of bytes per line. Default width and precision is 16.
- *      - \%Rhxs            - Takes a pointer to the memory to be displayed as a hex string,
- *                            i.e. a series of space separated bytes formatted as two digit hex value.
- *                            Use the precision to specify the length. Default length is 16 bytes.
- *                            The width, if specified, is ignored.
- *      - \%Rrc             - Takes an integer iprt status code as argument. Will insert the
- *                            status code define corresponding to the iprt status code.
- *      - \%Rrs             - Takes an integer iprt status code as argument. Will insert the
- *                            short description of the specified status code.
- *      - \%Rrf             - Takes an integer iprt status code as argument. Will insert the
- *                            full description of the specified status code.
- *      - \%Rra             - Takes an integer iprt status code as argument. Will insert the
- *                            status code define + full description.
- *      - \%Rwc             - Takes a long Windows error code as argument. Will insert the status
- *                            code define corresponding to the Windows error code.
- *      - \%Rwf             - Takes a long Windows error code as argument. Will insert the
- *                            full description of the specified status code.
- *      - \%Rwa             - Takes a long Windows error code as argument. Will insert the
- *                            error code define + full description.
+ *
- *      - \%Rhrc            - Takes a COM/XPCOM status code as argument. Will insert the status
- *                            code define corresponding to the Windows error code.
- *      - \%Rhrf            - Takes a COM/XPCOM status code as argument. Will insert the
- *                            full description of the specified status code.
- *      - \%Rhra            - Takes a COM/XPCOM error code as argument. Will insert the
- *                            error code define + full description.
+ *
- *      - \%Rfn             - Pretty printing of a function or method. It drops the
- *                            return code and parameter list.
- *      - \%Rbn             - Prints the base name.  For dropping the path in
- *                            order to save space when printing a path name.
+ *
- * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
+ *
+ *
- * Group 4, structure dumpers:
- *      - \%RDtimespec      - Takes a PCRTTIMESPEC.
+ *
+ *
- * Group 5, XML / HTML escapers:
- *      - \%RMas            - Takes a string pointer (const char *) and outputs
- *                            it as an attribute value with the proper escaping.
- *                            This typically ends up in double quotes.
+ *
- *      - \%RMes            - Takes a string pointer (const char *) and outputs
- *                            it as an element with the necessary escaping.
+ *
- * Group 6, CPU Architecture Register dumpers:
- *      - \%RAx86[reg]      - Takes a 64-bit register value if the register is
- *                            64-bit or smaller.  Check the code wrt which
- *                            registers are implemented.
+ *
- */
-#ifndef DECLARED_FNRTSTROUTPUT          /* duplicated in iprt/log.h */
-# define DECLARED_FNRTSTROUTPUT
-/**
- * Output callback.
+ *
- * @returns number of bytes written.
- * @param   pvArg       User argument.
- * @param   pachChars   Pointer to an array of utf-8 characters.
- * @param   cbChars     Number of bytes in the character array pointed to by pachChars.
- */
-typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
-/** Pointer to callback function. */
-typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
-#endif
-/** Format flag.
- * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
- * that not all flags makes sense to both of the functions.
- * @{ */
-#define RTSTR_F_CAPITAL         0x0001
-#define RTSTR_F_LEFT            0x0002
-#define RTSTR_F_ZEROPAD         0x0004
-#define RTSTR_F_SPECIAL         0x0008
-#define RTSTR_F_VALSIGNED       0x0010
-#define RTSTR_F_PLUS            0x0020
-#define RTSTR_F_BLANK           0x0040
-#define RTSTR_F_WIDTH           0x0080
-#define RTSTR_F_PRECISION       0x0100
-#define RTSTR_F_THOUSAND_SEP    0x0200
-#define RTSTR_F_BIT_MASK        0xf800
-#define RTSTR_F_8BIT            0x0800
-#define RTSTR_F_16BIT           0x1000
-#define RTSTR_F_32BIT           0x2000
-#define RTSTR_F_64BIT           0x4000
-#define RTSTR_F_128BIT          0x8000
-/** @} */
-/** @def RTSTR_GET_BIT_FLAG
- * Gets the bit flag for the specified type.
- */
-#define RTSTR_GET_BIT_FLAG(type) \
-    ( sizeof(type) * 8 == 32  ? RTSTR_F_32BIT \
-    : sizeof(type) * 8 == 64  ? RTSTR_F_64BIT \
-    : sizeof(type) * 8 == 16  ? RTSTR_F_16BIT \
-    : sizeof(type) * 8 == 8   ? RTSTR_F_8BIT \
-    : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
-    : 0)
-/**
- * Callback to format non-standard format specifiers.
+ *
- * @returns The number of bytes formatted.
- * @param   pvArg           Formatter argument.
- * @param   pfnOutput       Pointer to output function.
- * @param   pvArgOutput     Argument for the output function.
- * @param   ppszFormat      Pointer to the format string pointer. Advance this till the char
- *                          after the format specifier.
- * @param   pArgs           Pointer to the argument list. Use this to fetch the arguments.
- * @param   cchWidth        Format Width. -1 if not specified.
- * @param   cchPrecision    Format Precision. -1 if not specified.
- * @param   fFlags          Flags (RTSTR_NTFS_*).
- * @param   chArgSize       The argument size specifier, 'l' or 'L'.
- */
-typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
-                                         const char **ppszFormat, va_list *pArgs, int cchWidth,
-                                         int cchPrecision, unsigned fFlags, char chArgSize);
-/** Pointer to a FNSTRFORMAT() function. */
-typedef FNSTRFORMAT *PFNSTRFORMAT;
-/**
- * Partial implementation of a printf like formatter.
- * It doesn't do everything correct, and there is no floating point support.
- * However, it supports custom formats by the means of a format callback.
+ *
- * @returns number of bytes formatted.
- * @param   pfnOutput   Output worker.
- *                      Called in two ways. Normally with a string and its length.
- *                      For termination, it's called with NULL for string, 0 for length.
- * @param   pvArgOutput Argument to the output worker.
- * @param   pfnFormat   Custom format worker.
- * @param   pvArgFormat Argument to the format worker.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   InArgs      Argument list.
- */
-RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
-                            const char *pszFormat, va_list InArgs) RT_IPRT_FORMAT_ATTR(5, 0);
-/**
- * Partial implementation of a printf like formatter.
- * It doesn't do everything correct, and there is no floating point support.
- * However, it supports custom formats by the means of a format callback.
+ *
- * @returns number of bytes formatted.
- * @param   pfnOutput   Output worker.
- *                      Called in two ways. Normally with a string and its length.
- *                      For termination, it's called with NULL for string, 0 for length.
- * @param   pvArgOutput Argument to the output worker.
- * @param   pfnFormat   Custom format worker.
- * @param   pvArgFormat Argument to the format worker.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         Argument list.
- */
-RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
-                           const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
-/**
- * Formats an integer number according to the parameters.
+ *
- * @returns Length of the formatted number.
- * @param   psz             Pointer to output string buffer of sufficient size.
- * @param   u64Value        Value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision,
-                              unsigned int fFlags);
-/**
- * Formats an unsigned 8-bit number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   u8Value         The value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatU8(char *pszBuf, size_t cbBuf, uint8_t u8Value, unsigned int uiBase,
-                              signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an unsigned 16-bit number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   u16Value        The value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatU16(char *pszBuf, size_t cbBuf, uint16_t u16Value, unsigned int uiBase,
-                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an unsigned 32-bit number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   u32Value        The value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatU32(char *pszBuf, size_t cbBuf, uint32_t u32Value, unsigned int uiBase,
-                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an unsigned 64-bit number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   u64Value        The value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatU64(char *pszBuf, size_t cbBuf, uint64_t u64Value, unsigned int uiBase,
-                               signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an unsigned 128-bit number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   pu128Value      The value to format.
- * @param   uiBase          Number representation base.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatU128(char *pszBuf, size_t cbBuf, PCRTUINT128U pu128Value, unsigned int uiBase,
-                                signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an 80-bit extended floating point number.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   pr80Value       The value to format.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatR80(char *pszBuf, size_t cbBuf, PCRTFLOAT80U pr80Value, signed int cchWidth,
-                               signed int cchPrecision, uint32_t fFlags);
-/**
- * Formats an 80-bit extended floating point number, version 2.
+ *
- * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
- * @param   pszBuf          The output buffer.
- * @param   cbBuf           The size of the output buffer.
- * @param   pr80Value       The value to format.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags, RTSTR_F_XXX.
- */
-RTDECL(ssize_t) RTStrFormatR80u2(char *pszBuf, size_t cbBuf, PCRTFLOAT80U2 pr80Value, signed int cchWidth,
-                                 signed int cchPrecision, uint32_t fFlags);
-/**
- * Callback for formatting a type.
+ *
- * This is registered using the RTStrFormatTypeRegister function and will
- * be called during string formatting to handle the specified %R[type].
- * The argument for this format type is assumed to be a pointer and it's
- * passed in the @a pvValue argument.
+ *
- * @returns Length of the formatted output.
- * @param   pfnOutput       Output worker.
- * @param   pvArgOutput     Argument to the output worker.
- * @param   pszType         The type name.
- * @param   pvValue         The argument value.
- * @param   cchWidth        Width.
- * @param   cchPrecision    Precision.
- * @param   fFlags          Flags (NTFS_*).
- * @param   pvUser          The user argument.
- */
-typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
-                                               const char *pszType, void const *pvValue,
-                                               int cchWidth, int cchPrecision, unsigned fFlags,
-                                               void *pvUser);
-/** Pointer to a FNRTSTRFORMATTYPE. */
-typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
-/**
- * Register a format handler for a type.
+ *
- * The format handler is used to handle '%R[type]' format types, where the argument
- * in the vector is a pointer value (a bit restrictive, but keeps it simple).
+ *
- * The caller must ensure that no other thread will be making use of any of
- * the dynamic formatting type facilities simultaneously with this call.
+ *
- * @returns IPRT status code.
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_ALREADY_EXISTS if the type has already been registered.
- * @retval  VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
+ *
- * @param   pszType         The type name.
- * @param   pfnHandler      The handler address. See FNRTSTRFORMATTYPE for details.
- * @param   pvUser          The user argument to pass to the handler. See RTStrFormatTypeSetUser
- *                          for how to update this later.
- */
-RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
-/**
- * Deregisters a format type.
+ *
- * The caller must ensure that no other thread will be making use of any of
- * the dynamic formatting type facilities simultaneously with this call.
+ *
- * @returns IPRT status code.
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_FILE_NOT_FOUND if not found.
+ *
- * @param   pszType     The type to deregister.
- */
-RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
-/**
- * Sets the user argument for a type.
+ *
- * This can be used if a user argument needs relocating in GC.
+ *
- * @returns IPRT status code.
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_FILE_NOT_FOUND if not found.
+ *
- * @param   pszType     The type to update.
- * @param   pvUser      The new user argument value.
- */
-RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
-/**
- * String printf.
+ *
- * @returns The length of the returned string (in pszBuffer) excluding the
- *          terminator.
- * @param   pszBuffer   Output buffer.
- * @param   cchBuffer   Size of the output buffer.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- */
-RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
-/**
- * String printf.
+ *
- * @returns The length of the returned string (in pszBuffer) excluding the
- *          terminator.
- * @param   pszBuffer   Output buffer.
- * @param   cchBuffer   Size of the output buffer.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
-/**
- * String printf with custom formatting.
+ *
- * @returns The length of the returned string (in pszBuffer) excluding the
- *          terminator.
- * @param   pfnFormat   Pointer to handler function for the custom formats.
- * @param   pvArg       Argument to the pfnFormat function.
- * @param   pszBuffer   Output buffer.
- * @param   cchBuffer   Size of the output buffer.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- */
-RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
-                              const char *pszFormat, va_list args)  RT_IPRT_FORMAT_ATTR(5, 0);
-/**
- * String printf with custom formatting.
+ *
- * @returns The length of the returned string (in pszBuffer) excluding the
- *          terminator.
- * @param   pfnFormat   Pointer to handler function for the custom formats.
- * @param   pvArg       Argument to the pfnFormat function.
- * @param   pszBuffer   Output buffer.
- * @param   cchBuffer   Size of the output buffer.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
-                             const char *pszFormat, ...)  RT_IPRT_FORMAT_ATTR(5, 6);
-/**
- * Allocating string printf (default tag).
+ *
- * @returns The length of the string in the returned *ppszBuffer excluding the
- *          terminator.
- * @returns -1 on failure.
- * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
- *                      The buffer should be freed using RTStrFree().
- *                      On failure *ppszBuffer will be set to NULL.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- */
-#define RTStrAPrintfV(ppszBuffer, pszFormat, args)      RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
-/**
- * Allocating string printf (custom tag).
+ *
- * @returns The length of the string in the returned *ppszBuffer excluding the
- *          terminator.
- * @returns -1 on failure.
- * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
- *                      The buffer should be freed using RTStrFree().
- *                      On failure *ppszBuffer will be set to NULL.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- * @param   pszTag      Allocation tag used for statistics and such.
- */
-RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer, const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(2, 0);
-/**
- * Allocating string printf.
+ *
- * @returns The length of the string in the returned *ppszBuffer excluding the
- *          terminator.
- * @returns -1 on failure.
- * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
- *                      The buffer should be freed using RTStrFree().
- *                      On failure *ppszBuffer will be set to NULL.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...)
+{
-    int     cbRet;
-    va_list va;
-    va_start(va, pszFormat);
-    cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, RTSTR_TAG);
-    va_end(va);
-    return cbRet;
+}
-/**
- * Allocating string printf (custom tag).
+ *
- * @returns The length of the string in the returned *ppszBuffer excluding the
- *          terminator.
- * @returns -1 on failure.
- * @param   ppszBuffer  Where to store the pointer to the allocated output buffer.
- *                      The buffer should be freed using RTStrFree().
- *                      On failure *ppszBuffer will be set to NULL.
- * @param   pszTag      Allocation tag used for statistics and such.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer, const char *pszTag, const char *pszFormat, ...)
+{
-    int     cbRet;
-    va_list va;
-    va_start(va, pszFormat);
-    cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, pszTag);
-    va_end(va);
-    return cbRet;
+}
-/**
- * Allocating string printf, version 2.
+ *
- * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
- *          memory.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- */
-#define RTStrAPrintf2V(pszFormat, args)     RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
-/**
- * Allocating string printf, version 2.
+ *
- * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
- *          memory.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   args        The format argument.
- * @param   pszTag      Allocation tag used for statistics and such.
- */
-RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(1, 0);
-/**
- * Allocating string printf, version 2 (default tag).
+ *
- * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
- *          memory.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat, ...)
+{
-    char   *pszRet;
-    va_list va;
-    va_start(va, pszFormat);
-    pszRet = RTStrAPrintf2VTag(pszFormat, va, RTSTR_TAG);
-    va_end(va);
-    return pszRet;
+}
-/**
- * Allocating string printf, version 2 (custom tag).
+ *
- * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
- *          memory.
- * @param   pszTag      Allocation tag used for statistics and such.
- * @param   pszFormat   Pointer to the format string, @see pg_rt_str_format.
- * @param   ...         The format argument.
- */
-DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag, const char *pszFormat, ...)
+{
-    char   *pszRet;
-    va_list va;
-    va_start(va, pszFormat);
-    pszRet = RTStrAPrintf2VTag(pszFormat, va, pszTag);
-    va_end(va);
-    return pszRet;
+}
-/**
- * Strips blankspaces from both ends of the string.
+ *
- * @returns Pointer to first non-blank char in the string.
- * @param   psz     The string to strip.
- */
-RTDECL(char *) RTStrStrip(char *psz);
-/**
- * Strips blankspaces from the start of the string.
+ *
- * @returns Pointer to first non-blank char in the string.
- * @param   psz     The string to strip.
- */
-RTDECL(char *) RTStrStripL(const char *psz);
-/**
- * Strips blankspaces from the end of the string.
+ *
- * @returns psz.
- * @param   psz     The string to strip.
- */
-RTDECL(char *) RTStrStripR(char *psz);
-/**
- * String copy with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pszDst              The destination buffer.
- * @param   cbDst               The size of the destination buffer (in bytes).
- * @param   pszSrc              The source string.  NULL is not OK.
- */
-RTDECL(int) RTStrCopy(char *pszDst, size_t cbDst, const char *pszSrc);
-/**
- * String copy with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pszDst              The destination buffer.
- * @param   cbDst               The size of the destination buffer (in bytes).
- * @param   pszSrc              The source string.  NULL is not OK.
- * @param   cchSrcMax           The maximum number of chars (not code points) to
- *                              copy from the source string, not counting the
- *                              terminator as usual.
- */
-RTDECL(int) RTStrCopyEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
-/**
- * String copy with overflow handling and buffer advancing.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   ppszDst             Pointer to the destination buffer pointer.
- *                              This will be advanced to the end of the copied
- *                              bytes (points at the terminator).  This is also
- *                              updated on overflow.
- * @param   pcbDst              Pointer to the destination buffer size
- *                              variable.  This will be updated in accord with
- *                              the buffer pointer.
- * @param   pszSrc              The source string.  NULL is not OK.
- */
-RTDECL(int) RTStrCopyP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
-/**
- * String copy with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   ppszDst             Pointer to the destination buffer pointer.
- *                              This will be advanced to the end of the copied
- *                              bytes (points at the terminator).  This is also
- *                              updated on overflow.
- * @param   pcbDst              Pointer to the destination buffer size
- *                              variable.  This will be updated in accord with
- *                              the buffer pointer.
- * @param   pszSrc              The source string.  NULL is not OK.
- * @param   cchSrcMax           The maximum number of chars (not code points) to
- *                              copy from the source string, not counting the
- *                              terminator as usual.
- */
-RTDECL(int) RTStrCopyPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
-/**
- * String concatenation with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pszDst              The destination buffer.
- * @param   cbDst               The size of the destination buffer (in bytes).
- * @param   pszSrc              The source string.  NULL is not OK.
- */
-RTDECL(int) RTStrCat(char *pszDst, size_t cbDst, const char *pszSrc);
-/**
- * String concatenation with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   pszDst              The destination buffer.
- * @param   cbDst               The size of the destination buffer (in bytes).
- * @param   pszSrc              The source string.  NULL is not OK.
- * @param   cchSrcMax           The maximum number of chars (not code points) to
- *                              copy from the source string, not counting the
- *                              terminator as usual.
- */
-RTDECL(int) RTStrCatEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
-/**
- * String concatenation with overflow handling.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   ppszDst             Pointer to the destination buffer pointer.
- *                              This will be advanced to the end of the copied
- *                              bytes (points at the terminator).  This is also
- *                              updated on overflow.
- * @param   pcbDst              Pointer to the destination buffer size
- *                              variable.  This will be updated in accord with
- *                              the buffer pointer.
- * @param   pszSrc              The source string.  NULL is not OK.
- */
-RTDECL(int) RTStrCatP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
-/**
- * String concatenation with overflow handling and buffer advancing.
+ *
- * @retval  VINF_SUCCESS on success.
- * @retval  VERR_BUFFER_OVERFLOW if the destination buffer is too small.  The
- *          buffer will contain as much of the string as it can hold, fully
- *          terminated.
+ *
- * @param   ppszDst             Pointer to the destination buffer pointer.
- *                              This will be advanced to the end of the copied
- *                              bytes (points at the terminator).  This is also
- *                              updated on overflow.
- * @param   pcbDst              Pointer to the destination buffer size
- *                              variable.  This will be updated in accord with
- *                              the buffer pointer.
- * @param   pszSrc              The source string.  NULL is not OK.
- * @param   cchSrcMax           The maximum number of chars (not code points) to
- *                              copy from the source string, not counting the
- *                              terminator as usual.
- */
-RTDECL(int) RTStrCatPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
-/**
- * Performs a case sensitive string compare between two UTF-8 strings.
+ *
- * Encoding errors are ignored by the current implementation. So, the only
- * difference between this and the CRT strcmp function is the handling of
- * NULL arguments.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   psz1        First UTF-8 string. Null is allowed.
- * @param   psz2        Second UTF-8 string. Null is allowed.
- */
-RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
-/**
- * Performs a case sensitive string compare between two UTF-8 strings, given
- * a maximum string length.
+ *
- * Encoding errors are ignored by the current implementation. So, the only
- * difference between this and the CRT strncmp function is the handling of
- * NULL arguments.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   psz1        First UTF-8 string. Null is allowed.
- * @param   psz2        Second UTF-8 string. Null is allowed.
- * @param   cchMax      The maximum string length
- */
-RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
-/**
- * Performs a case insensitive string compare between two UTF-8 strings.
+ *
- * This is a simplified compare, as only the simplified lower/upper case folding
- * specified by the unicode specs are used. It does not consider character pairs
- * as they are used in some languages, just simple upper & lower case compares.
+ *
- * The result is the difference between the mismatching codepoints after they
- * both have been lower cased.
+ *
- * If the string encoding is invalid the function will assert (strict builds)
- * and use RTStrCmp for the remainder of the string.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   psz1        First UTF-8 string. Null is allowed.
- * @param   psz2        Second UTF-8 string. Null is allowed.
- */
-RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
-/**
- * Performs a case insensitive string compare between two UTF-8 strings, given a
- * maximum string length.
+ *
- * This is a simplified compare, as only the simplified lower/upper case folding
- * specified by the unicode specs are used. It does not consider character pairs
- * as they are used in some languages, just simple upper & lower case compares.
+ *
- * The result is the difference between the mismatching codepoints after they
- * both have been lower cased.
+ *
- * If the string encoding is invalid the function will assert (strict builds)
- * and use RTStrCmp for the remainder of the string.
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
- * @param   psz1        First UTF-8 string. Null is allowed.
- * @param   psz2        Second UTF-8 string. Null is allowed.
- * @param   cchMax      Maximum string length
- */
-RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
-/**
- * Locates a case sensitive substring.
+ *
- * If any of the two strings are NULL, then NULL is returned. If the needle is
- * an empty string, then the haystack is returned (i.e. matches anything).
+ *
- * @returns Pointer to the first occurrence of the substring if found, NULL if
- *          not.
+ *
- * @param   pszHaystack The string to search.
- * @param   pszNeedle   The substring to search for.
+ *
- * @remarks The difference between this and strstr is the handling of NULL
- *          pointers.
- */
-RTDECL(char *) RTStrStr(const char *pszHaystack, const char *pszNeedle);
-/**
- * Locates a case insensitive substring.
+ *
- * If any of the two strings are NULL, then NULL is returned. If the needle is
- * an empty string, then the haystack is returned (i.e. matches anything).
+ *
- * @returns Pointer to the first occurrence of the substring if found, NULL if
- *          not.
+ *
- * @param   pszHaystack The string to search.
- * @param   pszNeedle   The substring to search for.
+ *
- */
-RTDECL(char *) RTStrIStr(const char *pszHaystack, const char *pszNeedle);
-/**
- * Converts the string to lower case.
+ *
- * @returns Pointer to the converted string.
- * @param   psz     The string to convert.
- */
-RTDECL(char *) RTStrToLower(char *psz);
-/**
- * Converts the string to upper case.
+ *
- * @returns Pointer to the converted string.
- * @param   psz     The string to convert.
- */
-RTDECL(char *) RTStrToUpper(char *psz);
-/**
- * Checks if the string is case foldable, i.e. whether it would change if
- * subject to RTStrToLower or RTStrToUpper.
+ *
- * @returns true / false
- * @param   psz     The string in question.
- */
-RTDECL(bool) RTStrIsCaseFoldable(const char *psz);
-/**
- * Checks if the string is upper cased (no lower case chars in it).
+ *
- * @returns true / false
- * @param   psz     The string in question.
- */
-RTDECL(bool) RTStrIsUpperCased(const char *psz);
-/**
- * Checks if the string is lower cased (no upper case chars in it).
+ *
- * @returns true / false
- * @param   psz     The string in question.
- */
-RTDECL(bool) RTStrIsLowerCased(const char *psz);
-/**
- * Find the length of a zero-terminated byte string, given
- * a max string length.
+ *
- * See also RTStrNLenEx.
+ *
- * @returns The string length or cbMax. The returned length does not include
- *          the zero terminator if it was found.
+ *
- * @param   pszString   The string.
- * @param   cchMax      The max string length.
- */
-RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
-/**
- * Find the length of a zero-terminated byte string, given
- * a max string length.
+ *
- * See also RTStrNLen.
+ *
- * @returns IPRT status code.
- * @retval  VINF_SUCCESS if the string has a length less than cchMax.
- * @retval  VERR_BUFFER_OVERFLOW if the end of the string wasn't found
- *          before cchMax was reached.
+ *
- * @param   pszString   The string.
- * @param   cchMax      The max string length.
- * @param   pcch        Where to store the string length excluding the
- *                      terminator. This is set to cchMax if the terminator
- *                      isn't found.
- */
-RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
-RT_C_DECLS_END
-/** The maximum size argument of a memchr call. */
-#define RTSTR_MEMCHR_MAX            ((~(size_t)0 >> 1) - 15)
-/**
- * Find the zero terminator in a string with a limited length.
+ *
- * @returns Pointer to the zero terminator.
- * @returns NULL if the zero terminator was not found.
+ *
- * @param   pszString   The string.
- * @param   cchMax      The max string length.  RTSTR_MAX is fine.
- */
-#if defined(__cplusplus) && !defined(DOXYGEN_RUNNING)
-DECLINLINE(char const *) RTStrEnd(char const *pszString, size_t cchMax)
+{
-    /* Avoid potential issues with memchr seen in glibc.
-     * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
-    while (cchMax > RTSTR_MEMCHR_MAX)
+    {
-        char const *pszRet = (char const *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
-        if (RT_LIKELY(pszRet))
-            return pszRet;
-        pszString += RTSTR_MEMCHR_MAX;
-        cchMax    -= RTSTR_MEMCHR_MAX;
+    }
-    return (char const *)memchr(pszString, '\0', cchMax);
+}
-DECLINLINE(char *) RTStrEnd(char *pszString, size_t cchMax)
-#else
-DECLINLINE(char *) RTStrEnd(const char *pszString, size_t cchMax)
-#endif
+{
-    /* Avoid potential issues with memchr seen in glibc.
-     * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
-    while (cchMax > RTSTR_MEMCHR_MAX)
+    {
-        char *pszRet = (char *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
-        if (RT_LIKELY(pszRet))
-            return pszRet;
-        pszString += RTSTR_MEMCHR_MAX;
-        cchMax    -= RTSTR_MEMCHR_MAX;
+    }
-    return (char *)memchr(pszString, '\0', cchMax);
+}
-RT_C_DECLS_BEGIN
-/**
- * Finds the offset at which a simple character first occurs in a string.
+ *
- * @returns The offset of the first occurence or the terminator offset.
- * @param   pszHaystack The string to search.
- * @param   chNeedle    The character to search for.
- */
-DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack, char chNeedle)
+{
-    const char *psz = pszHaystack;
-    char ch;
-    while (   (ch = *psz) != chNeedle
-           && ch != '\0')
-        psz++;
-    return psz - pszHaystack;
+}
-/**
- * Matches a simple string pattern.
+ *
- * @returns true if the string matches the pattern, otherwise false.
+ *
- * @param  pszPattern   The pattern. Special chars are '*' and '?', where the
- *                      asterisk matches zero or more characters and question
- *                      mark matches exactly one character.
- * @param  pszString    The string to match against the pattern.
- */
-RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
-/**
- * Matches a simple string pattern, neither which needs to be zero terminated.
+ *
- * This is identical to RTStrSimplePatternMatch except that you can optionally
- * specify the length of both the pattern and the string.  The function will
- * stop when it hits a string terminator or either of the lengths.
+ *
- * @returns true if the string matches the pattern, otherwise false.
+ *
- * @param  pszPattern   The pattern. Special chars are '*' and '?', where the
- *                      asterisk matches zero or more characters and question
- *                      mark matches exactly one character.
- * @param  cchPattern   The pattern length. Pass RTSTR_MAX if you don't know the
- *                      length and wish to stop at the string terminator.
- * @param  pszString    The string to match against the pattern.
- * @param  cchString    The string length. Pass RTSTR_MAX if you don't know the
- *                      length and wish to match up to the string terminator.
- */
-RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
-                                      const char *pszString, size_t cchString);
-/**
- * Matches multiple patterns against a string.
+ *
- * The patterns are separated by the pipe character (|).
+ *
- * @returns true if the string matches the pattern, otherwise false.
+ *
- * @param   pszPatterns The patterns.
- * @param   cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
- *                      stop at the terminator.
- * @param   pszString   The string to match against the pattern.
- * @param   cchString   The string length. Pass RTSTR_MAX stop stop at the
- *                      terminator.
- * @param   poffPattern Offset into the patterns string of the patttern that
- *                      matched. If no match, this will be set to RTSTR_MAX.
- *                      This is optional, NULL is fine.
- */
-RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
-                                          const char *pszString, size_t cchString,
-                                          size_t *poffPattern);
-/**
- * Compares two version strings RTStrICmp fashion.
+ *
- * The version string is split up into sections at punctuation, spaces,
- * underscores, dashes and plus signs.  The sections are then split up into
- * numeric and string sub-sections.  Finally, the sub-sections are compared
- * in a numeric or case insesntivie fashion depending on what they are.
+ *
- * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
- * "1".  These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
+ *
- * @returns < 0 if the first string less than the second string.
- * @returns 0 if the first string identical to the second string.
- * @returns > 0 if the first string greater than the second string.
+ *
- * @param   pszVer1     First version string to compare.
- * @param   pszVer2     Second version string to compare first version with.
- */
-RTDECL(int) RTStrVersionCompare(const char *pszVer1, const char *pszVer2);
-/** @defgroup rt_str_conv   String To/From Number Conversions
- * @{ */
-/**
- * Converts a string representation of a number to a 64-bit unsigned number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu64        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
-/**
- * Converts a string representation of a number to a 64-bit unsigned number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_TRAILING_CHARS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu64        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
-/**
- * Converts a string representation of a number to a 64-bit unsigned number.
- * The base is guessed.
+ *
- * @returns 64-bit unsigned number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
-/**
- * Converts a string representation of a number to a 32-bit unsigned number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu32        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
-/**
- * Converts a string representation of a number to a 32-bit unsigned number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_TRAILING_CHARS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu32        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
-/**
- * Converts a string representation of a number to a 64-bit unsigned number.
- * The base is guessed.
+ *
- * @returns 32-bit unsigned number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
-/**
- * Converts a string representation of a number to a 16-bit unsigned number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu16        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
-/**
- * Converts a string representation of a number to a 16-bit unsigned number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_TRAILING_CHARS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu16        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
-/**
- * Converts a string representation of a number to a 16-bit unsigned number.
- * The base is guessed.
+ *
- * @returns 16-bit unsigned number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
-/**
- * Converts a string representation of a number to a 8-bit unsigned number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu8         Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
-/**
- * Converts a string representation of a number to a 8-bit unsigned number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_NEGATIVE_UNSIGNED
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_TRAILING_CHARS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pu8         Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
-/**
- * Converts a string representation of a number to a 8-bit unsigned number.
- * The base is guessed.
+ *
- * @returns 8-bit unsigned number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
-/**
- * Converts a string representation of a number to a 64-bit signed number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi64        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
-/**
- * Converts a string representation of a number to a 64-bit signed number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VINF_SUCCESS
- * @retval  VERR_TRAILING_CHARS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi64        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
-/**
- * Converts a string representation of a number to a 64-bit signed number.
- * The base is guessed.
+ *
- * @returns 64-bit signed number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(int64_t) RTStrToInt64(const char *pszValue);
-/**
- * Converts a string representation of a number to a 32-bit signed number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi32        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
-/**
- * Converts a string representation of a number to a 32-bit signed number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VINF_SUCCESS
- * @retval  VERR_TRAILING_CHARS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi32        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
-/**
- * Converts a string representation of a number to a 32-bit signed number.
- * The base is guessed.
+ *
- * @returns 32-bit signed number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(int32_t) RTStrToInt32(const char *pszValue);
-/**
- * Converts a string representation of a number to a 16-bit signed number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi16        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
-/**
- * Converts a string representation of a number to a 16-bit signed number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VINF_SUCCESS
- * @retval  VERR_TRAILING_CHARS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   uBase       The base of the representation used.
- *                      If 0 the function will look for known prefixes before defaulting to 10.
- * @param   pi16        Where to store the converted number. (optional)
- */
-RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
-/**
- * Converts a string representation of a number to a 16-bit signed number.
- * The base is guessed.
+ *
- * @returns 16-bit signed number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(int16_t) RTStrToInt16(const char *pszValue);
-/**
- * Converts a string representation of a number to a 8-bit signed number.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
- * @retval  VINF_SUCCESS
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @param   ppszNext    Where to store the pointer to the first char following the number. (Optional)
- * @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)
- */
-RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
-/**
- * Converts a string representation of a number to a 8-bit signed number,
- * making sure the full string is converted.
+ *
- * @returns iprt status code.
- *          Warnings are used to indicate conversion problems.
- * @retval  VWRN_NUMBER_TOO_BIG
- * @retval  VINF_SUCCESS
- * @retval  VERR_TRAILING_CHARS
- * @retval  VERR_TRAILING_SPACES
- * @retval  VERR_NO_DIGITS
+ *
- * @param   pszValue    Pointer to the string value.
- * @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)
- */
-RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
-/**
- * Converts a string representation of a number to a 8-bit signed number.
- * The base is guessed.
+ *
- * @returns 8-bit signed number on success.
- * @returns 0 on failure.
- * @param   pszValue    Pointer to the string value.
- */
-RTDECL(int8_t) RTStrToInt8(const char *pszValue);
-/**
- * Formats a buffer stream as hex bytes.
+ *
- * The default is no separating spaces or line breaks or anything.
+ *
- * @returns IPRT status code.
- * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
- * @retval  VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
+ *
- * @param   pszBuf      Output string buffer.
- * @param   cchBuf      The size of the output buffer.
- * @param   pv          Pointer to the bytes to stringify.
- * @param   cb          The number of bytes to stringify.
- * @param   fFlags      Combination of RTSTRPRINTHEXBYTES_F_XXX values.
- * @sa      RTUtf16PrintHexBytes.
- */
-RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cchBuf, void const *pv, size_t cb, uint32_t fFlags);
-/** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
- * @{ */
-/** Upper case hex digits, the default is lower case. */
-#define RTSTRPRINTHEXBYTES_F_UPPER      RT_BIT(0)
-/** @} */
-/**
- * Converts a string of hex bytes back into binary data.
+ *
- * @returns IPRT status code.
- * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
- * @retval  VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
- * @retval  VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
- *          the output buffer.
- * @retval  VERR_UNEVEN_INPUT if the input contains a half byte.
- * @retval  VERR_NO_DIGITS
- * @retval  VWRN_TRAILING_CHARS
- * @retval  VWRN_TRAILING_SPACES
+ *
- * @param   pszHex      The string containing the hex bytes.
- * @param   pv          Output buffer.
- * @param   cb          The size of the output buffer.
- * @param   fFlags      Must be zero, reserved for future use.
- */
-RTDECL(int) RTStrConvertHexBytes(char const *pszHex, void *pv, size_t cb, uint32_t fFlags);
-/** @} */
-/** @defgroup rt_str_space  Unique String Space
- * @{
- */
-/** Pointer to a string name space container node core. */
-typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
-/** Pointer to a pointer to a string name space container node core. */
-typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
-/**
- * String name space container node core.
- */
-typedef struct RTSTRSPACECORE
+{
-    /** Hash key. Don't touch. */
-    uint32_t        Key;
-    /** Pointer to the left leaf node. Don't touch. */
-    PRTSTRSPACECORE pLeft;
-    /** Pointer to the left right node. Don't touch. */
-    PRTSTRSPACECORE pRight;
-    /** Pointer to the list of string with the same key. Don't touch. */
-    PRTSTRSPACECORE pList;
-    /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
-    unsigned char   uchHeight;
-    /** The string length. Read only! */
-    size_t          cchString;
-    /** Pointer to the string. Read only! */
-    const char     *pszString;
-} RTSTRSPACECORE;
-/** String space. (Initialize with NULL.) */
-typedef PRTSTRSPACECORE     RTSTRSPACE;
-/** Pointer to a string space. */
-typedef PPRTSTRSPACECORE    PRTSTRSPACE;
-/**
- * Inserts a string into a unique string space.
+ *
- * @returns true on success.
- * @returns false if the string collided with an existing string.
- * @param   pStrSpace       The space to insert it into.
- * @param   pStr            The string node.
- */
-RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
-/**
- * Removes a string from a unique string space.
+ *
- * @returns Pointer to the removed string node.
- * @returns NULL if the string was not found in the string space.
- * @param   pStrSpace       The space to remove it from.
- * @param   pszString       The string to remove.
- */
-RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
-/**
- * Gets a string from a unique string space.
+ *
- * @returns Pointer to the string node.
- * @returns NULL if the string was not found in the string space.
- * @param   pStrSpace       The space to get it from.
- * @param   pszString       The string to get.
- */
-RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
-/**
- * Gets a string from a unique string space.
+ *
- * @returns Pointer to the string node.
- * @returns NULL if the string was not found in the string space.
- * @param   pStrSpace       The space to get it from.
- * @param   pszString       The string to get.
- * @param   cchMax          The max string length to evaluate.  Passing
- *                          RTSTR_MAX is ok and makes it behave just like
- *                          RTStrSpaceGet.
- */
-RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax);
-/**
- * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
+ *
- * @returns 0 on continue.
- * @returns Non-zero to aborts the operation.
- * @param   pStr        The string node
- * @param   pvUser      The user specified argument.
- */
-typedef DECLCALLBACK(int)   FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
-/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
-typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
-/**
- * Destroys the string space.
+ *
- * The caller supplies a callback which will be called for each of the string
- * nodes in for freeing their memory and other resources.
+ *
- * @returns 0 or what ever non-zero return value pfnCallback returned
- *          when aborting the destruction.
- * @param   pStrSpace       The space to destroy.
- * @param   pfnCallback     The callback.
- * @param   pvUser          The user argument.
- */
-RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
-/**
- * Enumerates the string space.
- * The caller supplies a callback which will be called for each of
- * the string nodes.
+ *
- * @returns 0 or what ever non-zero return value pfnCallback returned
- *          when aborting the destruction.
- * @param   pStrSpace       The space to enumerate.
- * @param   pfnCallback     The callback.
- * @param   pvUser          The user argument.
- */
-RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
-/** @} */
-/** @defgroup rt_str_hash       Sting hashing
- * @{ */
-/**
- * Hashes the given string using algorithm \#1.
+ *
- * @returns String hash.
- * @param   pszString       The string to hash.
- */
-RTDECL(uint32_t)    RTStrHash1(const char *pszString);
-/**
- * Hashes the given string using algorithm \#1.
+ *
- * @returns String hash.
- * @param   pszString       The string to hash.
- * @param   cchString       The max length to hash. Hashing will stop if the
- *                          terminator character is encountered first. Passing
- *                          RTSTR_MAX is fine.
- */
-RTDECL(uint32_t)    RTStrHash1N(const char *pszString, size_t cchString);
-/**
- * Hashes the given strings as if they were concatenated using algorithm \#1.
+ *
- * @returns String hash.
- * @param   cPairs          The number of string / length pairs in the
- *                          ellipsis.
- * @param   ...             List of string (const char *) and length
- *                          (size_t) pairs.  Passing RTSTR_MAX as the size is
- *                          fine.
- */
-RTDECL(uint32_t)    RTStrHash1ExN(size_t cPairs, ...);
-/**
- * Hashes the given strings as if they were concatenated using algorithm \#1.
+ *
- * @returns String hash.
- * @param   cPairs          The number of string / length pairs in the @a va.
- * @param   va              List of string (const char *) and length
- *                          (size_t) pairs.  Passing RTSTR_MAX as the size is
- *                          fine.
- */
-RTDECL(uint32_t)    RTStrHash1ExNV(size_t cPairs, va_list va);
-/** @}  */
 /** @defgroup rt_str_utf16      UTF-16 String Manipulation
+ * @ingroup grp_rt_str
  * @{
  */
 …
+/** @defgroup rt_str_latin1     Latin-1 (ISO-8859-1) String Manipulation
+ * @{
+ */
+/**
+ * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
+ *
+ * @returns Number of RTUTF16 items.
+ * @param   psz             The Latin-1 string.
+ */
+RTDECL(size_t) RTLatin1CalcUtf16Len(const char *psz);
+/**
+ * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
+ *
+ * @returns iprt status code.
+ * @param   psz             The Latin-1 string.
+ * @param   cch             The max string length. Use RTSTR_MAX to process the
+ *                          entire string.
+ * @param   pcwc            Where to store the string length. Optional.
+ *                          This is undefined on failure.
+ */
+RTDECL(int) RTLatin1CalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
+/**
+ * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result
+ * buffer (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
+ *                          returned string must be freed using RTUtf16Free().
+ */
+#define RTLatin1ToUtf16(pszString, ppwszString)     RTLatin1ToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
+/**
+ * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result
+ * buffer (custom tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   ppwszString     Receives pointer to the allocated UTF-16 string. The
+ *                          returned string must be freed using RTUtf16Free().
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTLatin1ToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
+/**
+ * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+ * result buffer if requested (default tag).
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stops when it reaches cchString or
+ *                          the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing
+ *                          to pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at
+ *                          least cwc items will be allocated to hold the
+ *                          translated string. 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,
+ *                          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.
+ */
+#define RTLatin1ToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
+    RTLatin1ToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
+/**
+ * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
+ * result buffer if requested.
+ *
+ * @returns iprt status code.
+ * @param   pszString       The Latin-1 string to convert.
+ * @param   cchString       The maximum size in chars (the type) to convert.
+ *                          The conversion stops when it reaches cchString or
+ *                          the string terminator ('\\0').
+ *                          Use RTSTR_MAX to translate the entire string.
+ * @param   ppwsz           If cwc is non-zero, this must either be pointing
+ *                          to pointer to a buffer of the specified size, or
+ *                          pointer to a NULL pointer.
+ *                          If *ppwsz is NULL or cwc is zero a buffer of at
+ *                          least cwc items will be allocated to hold the
+ *                          translated string. 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,
+ *                          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.
+ * @param   pszTag          Allocation tag used for statistics and such.
+ */
+RTDECL(int) RTLatin1ToUtf16ExTag(const char *pszString, size_t cchString,
+                                 PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
+RT_C_DECLS_END
 /** @} */
-#ifndef ___iprt_nocrt_string_h
-# if defined(RT_OS_WINDOWS)
-RTDECL(void *) mempcpy(void *pvDst, const void *pvSrc, size_t cb);
-# endif
 #endif
-RT_C_DECLS_END
-/** @} */
-#endif

Note: See TracChangeset for help on using the changeset viewer.

Changeset 57941 in vbox

Legend:

trunk/include/iprt/latin1.h

trunk/include/iprt/string.h

trunk/include/iprt/utf16.h

Download in other formats: