string.h revision f39bba5daba2465f228571265a47ed4b16b683e3
* The maximum string length. * The default allocation tag used by the RTStr allocation APIs. * When not defined before the inclusion of iprt/string.h, this will default to * the pointer to the current file name. The string API will make of use of * this as pointer to a volatile but read-only string. * Allocates tmp buffer with default tag, translates pszString from UTF8 to * @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. * Allocates tmp buffer with custom tag, translates pszString from UTF8 to * @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. * 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. * 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. * 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. * 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 * 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 * @param pszTag Allocation tag used for statistics and such. * Appends a string onto an existing IPRT allocated string (default tag). * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param pszAppend The string to append. NULL and empty strings * Appends a string onto an existing IPRT allocated string (custom tag). * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param pszAppend The string to append. NULL and empty strings * @param pszTag Allocation tag used for statistics and such. * Appends N bytes from a strings onto an existing IPRT allocated string * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param pszAppend The string to append. Can be NULL if cchAppend * @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. * Appends N bytes from a strings onto an existing IPRT allocated string (custom * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param pszAppend The string to append. Can be NULL if cchAppend * @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. * 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 VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param cPairs The number of string / length pairs in the * @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 VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param cPairs The number of string / length pairs in the * @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 * This is a very flexible and efficient alternative to using RTStrAPrintf to * combine several strings together. * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param cPairs The number of string / length pairs in the * @param ... 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 (custom * This is a very flexible and efficient alternative to using RTStrAPrintf to * combine several strings together. * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @param ppsz Pointer to the string pointer. The string * pointer must either be NULL or point to a string * returned by an IPRT string API. (In/Out) * @param pszTag Allocation tag used for statistics and such. * @param cPairs The number of string / length pairs in the * @param ... List of string (const char *) and length * (size_t) pairs. The strings will be appended to * the string in the first argument. * Truncates an IPRT allocated string (default tag). * @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 * Truncates an IPRT allocated string. * @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 * @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 * @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 * @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 * @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 * @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 * @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 * @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 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @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 * 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 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz * @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 * @param pszTag Allocation tag used for statistics and such. * Validates the UTF-8 encoding of the string. * @returns iprt status code. /** @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. */ * Validates the UTF-8 encoding of the string. * @returns iprt status code. * @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. * 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. * Sanitise a (valid) UTF-8 string by replacing all characters outside a white * list in-place by an ASCII replacement character. Multi-byte characters will * be replaced byte by byte. * @returns The number of code points replaced, or a negative value if the * string is not correctly encoded. In this last case the string * may be partially processed. * @param psz The string to sanitise. * @param puszValidSet A zero-terminated array of the Unicode code points * @param chReplacement The ASCII replacement character. * Gets the number of code points the string is made up of, excluding * @returns Number of code points (RTUNICP). * @returns 0 if the string was incorrectly encoded. * Gets the number of code points the string is made up of, excluding * This function will validate the string, and incorrectly encoded UTF-8 * strings will be rejected. * @returns iprt status code. * @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 * @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. * 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. * 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 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 * @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 * @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. * 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. * 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 * @returns iprt status code. * @param cch The max string length. Use RTSTR_MAX to process the * @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 * @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 * @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 * @param cch The buffer size in bytes. This includes the * @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 * @param cch The buffer size in bytes. This includes the * @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. * Translate a Latin1 string into a UTF-8 allocating the result buffer (default * @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(). * 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 * @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 * @param cch The buffer size in chars (the type). This includes * @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. * 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 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. * 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 * @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 * @returns pointer to the char following the written code point. * @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. * @remark We optimize this operation by using an inline function for * the most frequent and simplest sequence, the rest is * handled by RTStrGetCpInternal(). const unsigned char uch = *(
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(). const unsigned char uch = **(
const unsigned char **)
ppsz;
* Get the unicode code point at the given string position for a string of a * @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(). const unsigned char uch = **(
const unsigned char **)
ppsz;
* 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. * 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 * @returns pointer to the char following the written code point. * @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(). * 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. * 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. 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(). const unsigned char uch = **(
const unsigned char **)
ppsz;
* Get the unicode code point at the given string position for a string of a * @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. const unsigned char uch = **(
const unsigned char **)
ppsz;
* 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 * 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 * @returns pointer to the char following the written code point. * @param CodePoint The code point to write. * This should not be RTUNICP_INVALID or any other * character out of the Latin-1 range. * 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. * 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. /** @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 - Same as \%s, used to convert to current codeset but this is * now done by the streams code. Deprecated, use \%s. * - \%lS - Ditto. Deprecated, use \%ls. * - \%LS - Ditto. Deprecated, use \%Ls. * - \%c - Takes a char and prints it. * - \%d - Takes a signed integer and prints it as decimal. Thousand * separator (\'), zero padding (0), adjustment (-+), width, * - \%u - Takes an unsigned integer and prints it as decimal. Thousand * separator (\'), zero padding (0), adjustment (-+), width, * - \%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 (-+), * - \%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). * - \%j - intmax_t (int64_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 * 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 * - \%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 * - \%Rhxd - Takes a pointer to the memory which is to be dumped in typical * hex format. Use the precision to specify the length, and the width to * set the number of bytes per line. Default width and precision is 16. * - \%Rhxs - Takes a pointer to the memory to be displayed as a hex string, * i.e. a series of space separated bytes formatted as two digit hex value. * Use the precision to specify the length. Default length is 16 bytes. * The width, if specified, is ignored. * - \%Rrc - Takes an integer iprt status code as argument. Will insert the * status code define corresponding to the iprt status code. * - \%Rrs - Takes an integer iprt status code as argument. Will insert the * short description of the specified status code. * - \%Rrf - Takes an integer iprt status code as argument. Will insert the * full description of the specified status code. * - \%Rra - Takes an integer iprt status code as argument. Will insert the * status code define + full description. * - \%Rwc - Takes a long Windows error code as argument. Will insert the status * code define corresponding to the Windows error code. * - \%Rwf - Takes a long Windows error code as argument. Will insert the * full description of the specified status code. * - \%Rwa - Takes a long Windows error code as argument. Will insert the * error code define + full description. * - \%Rhrc - Takes a COM/XPCOM status code as argument. Will insert the status * code define corresponding to the Windows error code. * - \%Rhrf - Takes a COM/XPCOM status code as argument. Will insert the * full description of the specified status code. * - \%Rhra - Takes a COM/XPCOM error code as argument. Will insert the * error code define + full description. * - \%Rfn - Pretty printing of a function or method. It drops the * return code and parameter list. * - \%Rbn - Prints the base name. For dropping the path in * order to save space when printing a path name. * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX. * Group 4, structure dumpers: * - \%RDtimespec - Takes a PCRTTIMESPEC. * Group 5, XML / HTML escapers: * - \%RMas - Takes a string pointer (const char *) and outputs * it as an attribute value with the proper escaping. * This typically ends up in double quotes. * - \%RMes - Takes a string pointer (const char *) and outputs * it as an element with the necessary escaping. * Group 6, CPU Architecture Register dumpers: * - \%RAx86[reg] - Takes a 64-bit register value if the register is * 64-bit or smaller. Check the code wrt which * registers are implemented. * @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. */ * These are used by RTStrFormat extensions and RTStrFormatNumber, mind * that not all flags makes sense to both of the functions. /** @def RTSTR_GET_BIT_FLAG * Gets the bit flag for the specified type. * 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. */ * 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. * 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. * 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 cchPrecision Precision. * @param fFlags Flags, RTSTR_F_XXX. * 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 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 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 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 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 cchPrecision Precision. * @param fFlags Flags, RTSTR_F_XXX. * 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 cchPrecision Precision. * @param fFlags Flags, RTSTR_F_XXX. * 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 cchPrecision Precision. * @param fFlags Flags, RTSTR_F_XXX. * 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 cchPrecision Precision. * @param fFlags Flags (NTFS_*). * @param pvUser The user argument. /** Pointer to a FNRTSTRFORMATTYPE. */ * 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. * 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. * @returns The length of the returned string (in pszBuffer) excluding the * @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. * @returns The length of the returned string (in pszBuffer) excluding the * @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 * @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. * String printf with custom formatting. * @returns The length of the returned string (in pszBuffer) excluding the * @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. * Allocating string printf (default tag). * @returns The length of the string in the returned *ppszBuffer excluding the * @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. * Allocating string printf (custom tag). * @returns The length of the string in the returned *ppszBuffer excluding the * @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. * Allocating string printf. * @returns The length of the string in the returned *ppszBuffer excluding the * @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. * Allocating string printf (custom tag). * @returns The length of the string in the returned *ppszBuffer excluding the * @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. * Allocating string printf, version 2. * @returns Formatted string. Use RTStrFree() to free it. NULL when out of * @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 * @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 * @param pszFormat Pointer to the format string, @see pg_rt_str_format. * @param ... The format argument. * Allocating string printf, version 2 (custom tag). * @returns Formatted string. Use RTStrFree() to free it. NULL when out of * @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. * 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. * @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 * @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 * @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 * 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 * @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 * @param pcbDst Pointer to the destination buffer size * variable. This will be updated in accord with * @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 * @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 * @param pcbDst Pointer to the destination buffer size * variable. This will be updated in accord with * @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 * 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 * @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 * @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 * 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 * @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 * @param pcbDst Pointer to the destination buffer size * variable. This will be updated in accord with * @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 * @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 * @param pcbDst Pointer to the destination buffer size * variable. This will be updated in accord with * @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 * 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 * @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 * @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. * This is a simplified compare, as only the simplified lower/upper case folding * specified by the unicode specs are used. It does not consider character pairs * as they are used in some languages, just simple upper & lower case compares. * The result is the difference between the mismatching codepoints after they * both have been lower cased. * If the string encoding is invalid the function will assert (strict builds) * and use RTStrCmp for the remainder of the string. * @returns < 0 if the first string less than the second string. * @returns 0 if the first string identical to the second string. * @returns > 0 if the first string greater than the second string. * @param psz1 First UTF-8 string. Null is allowed. * @param psz2 Second UTF-8 string. Null is allowed. * Performs a case insensitive string compare between two UTF-8 strings, given a * This is a simplified compare, as only the simplified lower/upper case folding * specified by the unicode specs are used. It does not consider character pairs * as they are used in some languages, just simple upper & lower case compares. * The result is the difference between the mismatching codepoints after they * both have been lower cased. * If the string encoding is invalid the function will assert (strict builds) * and use RTStrCmp for the remainder of the string. * @returns < 0 if the first string less than the second string. * @returns 0 if the first string identical to the second string. * @returns > 0 if the first string greater than the second string. * @param psz1 First UTF-8 string. Null is allowed. * @param psz2 Second UTF-8 string. Null is allowed. * @param cchMax Maximum string length * 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 * @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 * 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 * @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 * @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 * @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 /** 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. /* Avoid potential issues with memchr seen in glibc. /* Avoid potential issues with memchr seen in glibc. * 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 * @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. /** @defgroup rt_str_conv String To/From Number Conversions * Converts a string representation of a number to a 64-bit unsigned number. * @returns iprt status code. * Warnings are used to indicate conversion problems. * @retval VWRN_NUMBER_TOO_BIG * @retval VWRN_NEGATIVE_UNSIGNED * @retval VWRN_TRAILING_CHARS * @retval VWRN_TRAILING_SPACES * @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 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. * @returns 64-bit unsigned number on success. * @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 * @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 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. * @returns 32-bit unsigned number on success. * @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 * @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 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. * @returns 16-bit unsigned number on success. * @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 * @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 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. * @returns 8-bit unsigned number on success. * @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 * @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 VERR_TRAILING_CHARS * @retval VERR_TRAILING_SPACES * @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. * @returns 64-bit signed number on success. * @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 * @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 VERR_TRAILING_CHARS * @retval VERR_TRAILING_SPACES * @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. * @returns 32-bit signed number on success. * @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 * @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 VERR_TRAILING_CHARS * @retval VERR_TRAILING_SPACES * @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. * @returns 16-bit signed number on success. * @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 * @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 VERR_TRAILING_CHARS * @retval VERR_TRAILING_SPACES * @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. * @returns 8-bit signed number on success. * @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. * 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 * @retval VERR_UNEVEN_INPUT if the input contains a half byte. * @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 /** Pointer to a string name space container node core. */ /** Pointer to a pointer to a string name space container node core. */ * String name space container node core. /** 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 */ /** The string length. Read only! */ /** Pointer to the string. Read only! */ /** String space. (Initialize with NULL.) */ /** Pointer to a string space. */ * 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 * 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(). */ * 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. * Enumerates the string space. * The caller supplies a callback which will be called for each of * @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. /** @defgroup rt_str_hash Sting hashing * Hashes the given string using algorithm \#1. * @param pszString The string to hash. * Hashes the given string using algorithm \#1. * @param pszString The string to hash. * @param cchString The max length to hash. Hashing will stop if the * terminator character is encountered first. Passing * Hashes the given strings as if they were concatenated using algorithm \#1. * @param cPairs The number of string / length pairs in the * @param ... List of string (const char *) and length * (size_t) pairs. Passing RTSTR_MAX as the size is * Hashes the given strings as if they were concatenated using algorithm \#1. * @param cPairs The number of string / length pairs in the @a va. * @param va List of string (const char *) and length * (size_t) pairs. Passing RTSTR_MAX as the size is /** @defgroup rt_str_utf16 UTF-16 String Manipulation * 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. * 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. * This is a simplified compare, as only the simplified lower/upper case folding * specified by the unicode specs are used. It does not consider character pairs * as they are used in some languages, just simple upper & lower case compares. * @returns < 0 if the first string less than the second string. * @returns 0 if the first string identical to the second string. * @returns > 0 if the first string greater than the second string. * @param pwsz1 First UTF-16 string. Null is allowed. * @param pwsz2 Second UTF-16 string. Null is allowed. * 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. * Sanitise a (valid) UTF-16 string by replacing all characters outside a white * list in-place by an ASCII replacement character. Multi-byte characters will * be replaced byte by byte. * @returns The number of code points replaced, or a negative value if the * string is not correctly encoded. In this last case the string * may be partially processed. * @param pwsz The string to sanitise. * @param puszValidSet A zero-terminated array of the Unicode code points * @param chReplacement The ASCII replacement character. * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default * @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(). * 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. * 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 * @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(). * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result * @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 * 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 * @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 * 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 * @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. * 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 * @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 * @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. if (
wc <
0xd800 || (
wc >
0xdfff &&
wc <
0xfffe))
* 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. if (
wc <
0xd800 || (
wc >
0xdfff &&
wc <
0xfffe))
* 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 * @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. * 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. return wc >=
0xd800 &&
wc <=
0xdbff;
* Checks if the UTF-16 char is the low surrogate char (i.e. * the 2nd char in the pair). * @returns true if it is. * @returns false if it isn't. * @param wc The character to investigate. return wc >=
0xdc00 &&
wc <=
0xdfff;
* Checks if the two UTF-16 chars form a valid surrogate pair. * @returns true if they do. * @returns false if they doesn't. * @param wcHigh The high (1st) character. * @param wcLow The low (2nd) character. /** @defgroup rt_str_latin1 Latin-1 (ISO-8859-1) String Manipulation * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items. * @returns Number of RTUTF16 items. * @param psz The Latin-1 string. * 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 * @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 * @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(). * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result * @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 * @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 * @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.