string.h revision 79f3fc22f1940ba088cf03fd922096395f320051
/** @file
* IPRT - String Manipulation.
*/
/*
* Copyright (C) 2006-2010 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_string_h
#define ___iprt_string_h
#if defined(RT_OS_LINUX) && defined(__KERNEL__)
# include "xf86_ansic.h"
/** @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
* 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
/*
* No memmove on versions < 7.2
* Defining a macro using bcopy here
*/
/*
* Same case as with FreeBSD kernel:
* ffs = find first set bit.
*/
# define ffs ffs_string_h
# include <string.h>
#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)
#endif
#if defined(RT_OS_FREEBSD) && defined(_KERNEL)
#if __FreeBSD_version < 900000
#endif
#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
*/
/**
* 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
*/
/** @defgroup grp_rt_str RTStr - String Manipulation
* Mostly UTF-8 related helpers where the standard string functions won't do.
* @ingroup grp_rt
* @{
*/
/**
* The maximum string length.
*/
/** @def RTMEM_TAG
* The default allocation tag used by the RTStr allocation APIs.
*
* 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.
*/
#ifndef RTSTR_TAG
#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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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
* @param pszAppend The string to append. NULL and empty strings
* are quietly ignored.
*/
/**
* 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
* @param pszAppend The string to append. NULL and empty strings
* are quietly ignored.
* @param pszTag Allocation tag used for statistics and such.
*/
/**
* 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
* @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
* @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
* @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.
*/
/**
* 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
* @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.
*/
/**
* 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
* @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.
*/
{
int rc;
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
* @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.
*/
{
int rc;
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
* @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.
*/
/**
* 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
* @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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Validates the UTF-8 encoding of the string.
*
* @returns iprt status code.
* @param psz The string.
*/
/** @name Flags for RTStrValidateEncodingEx
*/
/** 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)
/** @} */
/**
* Validates the UTF-8 encoding of the string.
*
* @returns iprt status code.
* @param psz The string.
* @param cch The max string length. Use RTSTR_MAX to process the entire string.
* @param fFlags Reserved for future. Pass 0.
*/
/**
* Checks if the UTF-8 encoding is valid.
*
* @returns true / false.
* @param psz The string.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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().
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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().
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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().
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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().
*
*/
/**
* 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().
*/
{
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().
*/
{
{
(*ppsz)++;
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_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().
*/
{
{
{
(*ppsz)++;
(*pcch)--;
return VINF_SUCCESS;
}
}
}
/**
* 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.
*/
{
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().
*/
{
if (CodePoint < 0x80)
{
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.
*/
{
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.
*/
/**
* 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.
*/
{
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().
*/
{
(*ppsz)++;
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.
*/
{
{
(*ppsz)++;
(*pcch)--;
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
*/
{
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.
*/
{
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.
*/
{
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.
*/
{
psz--;
return (char *)psz;
}
/** @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
*
*
* 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 - R3: Same as \%s except it is printed in the current codeset
* instead of UTF-8 (source is still UTF-8).
* Other contexts: Same as \%s.
* - \%lS - Same as \%S except that the input is UTF-16 (output current
* codeset).
* - \%LS - Same as \%S except that the input is UCS-32 (output current
* codeset).
* - \%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
*
*
* 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.
*
* code define corresponding to the Windows error code.
* full description of the specified status code.
* 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.
*/
/** 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) \
: 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'.
*/
/** 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);
/**
* 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, ...);
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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,
/**
* 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,
/**
* 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,
/**
* 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.
*/
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.
*/
/**
* 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.
*/
/**
* 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);
/**
* 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.
*/
/**
* 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);
/**
* 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, ...);
/**
* 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);
/**
* 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.
*/
{
int cbRet;
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.
*/
{
int cbRet;
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.
*/
/**
* 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.
*/
/**
* 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.
*/
{
char *pszRet;
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.
*/
{
char *pszRet;
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.
*/
/**
* Strips blankspaces from the start of the string.
*
* @returns Pointer to first non-blank char in the string.
* @param psz The string to strip.
*/
/**
* Strips blankspaces from the end of the string.
*
* @returns psz.
* @param psz The string to strip.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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
*/
/**
* Performs a case insensitive string compare between two UTF-8 strings.
*
* 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.
*/
/**
* Performs a case insensitive string compare between two UTF-8 strings, given a
* maximum string length.
*
* 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
*/
/**
* 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.
*/
/**
* 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.
*
*/
/**
* Converts the string to lower case.
*
* @returns Pointer to the converted string.
* @param psz The string to convert.
*/
/**
* Converts the string to upper case.
*
* @returns Pointer to the converted string.
* @param psz The string to convert.
*/
/**
* 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.
*/
/**
* 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.
*/
/** The maximum size argument of a memchr call. */
/**
* 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)
{
/* Avoid potential issues with memchr seen in glibc.
while (cchMax > RTSTR_MEMCHR_MAX)
{
return pszRet;
}
}
#else
#endif
{
/* Avoid potential issues with memchr seen in glibc.
while (cchMax > RTSTR_MEMCHR_MAX)
{
return pszRet;
}
}
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
* @ingroup grp_rt_str
* @{ */
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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)
*/
/**
* 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)
*/
/**
* 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.
*/
/**
* 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 Must be zero, reserved for future use.
*/
RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cchBuf, void const *pv, size_t cb, uint32_t fFlags);
/**
* 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.
*/
/** @} */
/** @defgroup rt_str_space Unique String Space
* @ingroup grp_rt_str
* @{
*/
/** 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. */
/** Pointer to the left leaf node. Don't touch. */
/** Pointer to the left right node. Don't touch. */
/** Pointer to the list of string with the same key. Don't touch. */
/** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
unsigned char uchHeight;
/** The string length. Read only! */
/** Pointer to the string. Read only! */
const char *pszString;
/** 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.
*/
/**
* 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 insert it into.
* @param pszString The string to remove.
*/
/**
* 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 insert it into.
* @param pszString The string to get.
*/
/**
* 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 insert it into.
* @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.
*/
/** 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 insert it into.
* @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 insert it into.
* @param pfnCallback The callback.
* @param pvUser The user argument.
*/
RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
/** @} */
/** @defgroup rt_str_utf16 UTF-16 String Manipulation
* @ingroup grp_rt_str
* @{
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* Performs a case insensitive string compare between two UTF-16 strings.
*
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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().
*/
/**
* 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().
*/
/**
* 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().
*/
/**
* 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.
*/
{
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.
*/
{
{
(*ppwsz)++;
return VINF_SUCCESS;
}
}
/**
* 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.
*/
{
{
return pwsz;
}
}
/**
* 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.
*/
{
}
/**
* 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.
*/
/**
* 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.
*/
{
}
/**
* 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.
*/
{
}
/**
* 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.
*/
{
return RTUtf16IsHighSurrogate(wcHigh)
}
/** @} */
/** @defgroup rt_str_latin1 Latin-1 (ISO-8859-1) String Manipulation
* @ingroup grp_rt_str
* @{
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/** @} */
/** @} */
#endif