2 * IPRT - String Manipulation.
6 * Copyright (C) 2006-2016 Oracle Corporation
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
26 #ifndef ___iprt_string_h
27 #define ___iprt_string_h
29 #include <iprt/cdefs.h>
30 #include <iprt/types.h>
31 #include <iprt/assert.h>
32 #include <iprt/stdarg.h>
33 #include <iprt/err.h> /* for VINF_SUCCESS */
34 #if defined(RT_OS_LINUX) && defined(__KERNEL__)
35 /* no C++ hacks ('new' etc) here anymore! */
36 # include <linux/string.h>
38 #elif defined(IN_XF86_MODULE) && !defined(NO_ANSIC)
40 # include "xf86_ansic.h"
43 #elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
45 # include <sys/libkern.h>
48 #elif defined(RT_OS_NETBSD) && defined(_KERNEL)
50 # include <lib/libkern/libkern.h>
53 #elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
55 * Same case as with FreeBSD kernel:
56 * The string.h stuff clashes with sys/system.h
57 * ffs = find first set bit.
59 # define ffs ffs_string_h
68 /* For the time being: */
69 #include <iprt/utf16.h>
70 #include <iprt/latin1.h>
73 * Supply prototypes for standard string functions provided by
74 * IPRT instead of the operating environment.
76 #if defined(RT_OS_DARWIN) && defined(KERNEL)
78 void *memchr(const void *pv
, int ch
, size_t cb
);
79 char *strpbrk(const char *pszStr
, const char *pszChars
);
83 #if defined(RT_OS_FREEBSD) && defined(_KERNEL)
85 char *strpbrk(const char *pszStr
, const char *pszChars
);
89 #if defined(RT_OS_NETBSD) && defined(_KERNEL)
91 char *strpbrk(const char *pszStr
, const char *pszChars
);
95 #if (!defined(RT_OS_LINUX) || !defined(_GNU_SOURCE)) && !defined(RT_OS_FREEBSD) && !defined(RT_OS_NETBSD)
97 void *memrchr(const char *pv
, int ch
, size_t cb
);
102 /** @def RT_USE_RTC_3629
103 * When defined the UTF-8 range will stop at 0x10ffff. If not defined, the
104 * range stops at 0x7fffffff.
105 * @remarks Must be defined both when building and using the IPRT. */
106 #ifdef DOXYGEN_RUNNING
107 # define RT_USE_RTC_3629
112 * Byte zero the specified object.
114 * This will use sizeof(Obj) to figure the size and will call memset, bzero
115 * or some compiler intrinsic to perform the actual zeroing.
117 * @param Obj The object to zero. Make sure to dereference pointers.
119 * @remarks Because the macro may use memset it has been placed in string.h
120 * instead of cdefs.h to avoid build issues because someone forgot
121 * to include this header.
123 * @ingroup grp_rt_cdefs
125 #define RT_ZERO(Obj) RT_BZERO(&(Obj), sizeof(Obj))
128 * Byte zero the specified memory area.
130 * This will call memset, bzero or some compiler intrinsic to clear the
131 * specified bytes of memory.
133 * @param pv Pointer to the memory.
134 * @param cb The number of bytes to clear. Please, don't pass 0.
136 * @remarks Because the macro may use memset it has been placed in string.h
137 * instead of cdefs.h to avoid build issues because someone forgot
138 * to include this header.
140 * @ingroup grp_rt_cdefs
142 #define RT_BZERO(pv, cb) do { memset((pv), 0, cb); } while (0)
146 /** @defgroup grp_rt_str RTStr - String Manipulation
147 * Mostly UTF-8 related helpers where the standard string functions won't do.
156 * The maximum string length.
158 #define RTSTR_MAX (~(size_t)0)
162 * The default allocation tag used by the RTStr allocation APIs.
164 * When not defined before the inclusion of iprt/string.h, this will default to
165 * the pointer to the current file name. The string API will make of use of
166 * this as pointer to a volatile but read-only string.
168 #if !defined(RTSTR_TAG) || defined(DOXYGEN_RUNNING)
169 # define RTSTR_TAG (__FILE__)
176 * Allocates tmp buffer with default tag, translates pszString from UTF8 to
179 * @returns iprt status code.
180 * @param ppszString Receives pointer of allocated native CP string.
181 * The returned pointer must be freed using RTStrFree().
182 * @param pszString UTF-8 string to convert.
184 #define RTStrUtf8ToCurrentCP(ppszString, pszString) RTStrUtf8ToCurrentCPTag((ppszString), (pszString), RTSTR_TAG)
187 * Allocates tmp buffer with custom tag, translates pszString from UTF8 to
190 * @returns iprt status code.
191 * @param ppszString Receives pointer of allocated native CP string.
192 * The returned pointer must be freed using
193 * RTStrFree()., const char *pszTag
194 * @param pszString UTF-8 string to convert.
195 * @param pszTag Allocation tag used for statistics and such.
197 RTR3DECL(int) RTStrUtf8ToCurrentCPTag(char **ppszString
, const char *pszString
, const char *pszTag
);
200 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
202 * @returns iprt status code.
203 * @param ppszString Receives pointer of allocated UTF-8 string.
204 * The returned pointer must be freed using RTStrFree().
205 * @param pszString Native string to convert.
207 #define RTStrCurrentCPToUtf8(ppszString, pszString) RTStrCurrentCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
210 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
212 * @returns iprt status code.
213 * @param ppszString Receives pointer of allocated UTF-8 string.
214 * The returned pointer must be freed using RTStrFree().
215 * @param pszString Native string to convert.
216 * @param pszTag Allocation tag used for statistics and such.
218 RTR3DECL(int) RTStrCurrentCPToUtf8Tag(char **ppszString
, const char *pszString
, const char *pszTag
);
220 #endif /* IN_RING3 */
223 * Free string allocated by any of the non-UCS-2 string functions.
225 * @returns iprt status code.
226 * @param pszString Pointer to buffer with string to free.
229 RTDECL(void) RTStrFree(char *pszString
);
232 * Allocates a new copy of the given UTF-8 string (default tag).
234 * @returns Pointer to the allocated UTF-8 string.
235 * @param pszString UTF-8 string to duplicate.
237 #define RTStrDup(pszString) RTStrDupTag((pszString), RTSTR_TAG)
240 * Allocates a new copy of the given UTF-8 string (custom tag).
242 * @returns Pointer to the allocated UTF-8 string.
243 * @param pszString UTF-8 string to duplicate.
244 * @param pszTag Allocation tag used for statistics and such.
246 RTDECL(char *) RTStrDupTag(const char *pszString
, const char *pszTag
);
249 * Allocates a new copy of the given UTF-8 string (default tag).
251 * @returns iprt status code.
252 * @param ppszString Receives pointer of the allocated UTF-8 string.
253 * The returned pointer must be freed using RTStrFree().
254 * @param pszString UTF-8 string to duplicate.
256 #define RTStrDupEx(ppszString, pszString) RTStrDupExTag((ppszString), (pszString), RTSTR_TAG)
259 * Allocates a new copy of the given UTF-8 string (custom tag).
261 * @returns iprt status code.
262 * @param ppszString Receives pointer of the allocated UTF-8 string.
263 * The returned pointer must be freed using RTStrFree().
264 * @param pszString UTF-8 string to duplicate.
265 * @param pszTag Allocation tag used for statistics and such.
267 RTDECL(int) RTStrDupExTag(char **ppszString
, const char *pszString
, const char *pszTag
);
270 * Allocates a new copy of the given UTF-8 substring (default tag).
272 * @returns Pointer to the allocated UTF-8 substring.
273 * @param pszString UTF-8 string to duplicate.
274 * @param cchMax The max number of chars to duplicate, not counting
277 #define RTStrDupN(pszString, cchMax) RTStrDupNTag((pszString), (cchMax), RTSTR_TAG)
280 * Allocates a new copy of the given UTF-8 substring (custom tag).
282 * @returns Pointer to the allocated UTF-8 substring.
283 * @param pszString UTF-8 string to duplicate.
284 * @param cchMax The max number of chars to duplicate, not counting
286 * @param pszTag Allocation tag used for statistics and such.
288 RTDECL(char *) RTStrDupNTag(const char *pszString
, size_t cchMax
, const char *pszTag
);
291 * Appends a string onto an existing IPRT allocated string (default tag).
293 * @retval VINF_SUCCESS
294 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
297 * @param ppsz Pointer to the string pointer. The string
298 * pointer must either be NULL or point to a string
299 * returned by an IPRT string API. (In/Out)
300 * @param pszAppend The string to append. NULL and empty strings
301 * are quietly ignored.
303 #define RTStrAAppend(ppsz, pszAppend) RTStrAAppendTag((ppsz), (pszAppend), RTSTR_TAG)
306 * Appends a string onto an existing IPRT allocated string (custom tag).
308 * @retval VINF_SUCCESS
309 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
312 * @param ppsz Pointer to the string pointer. The string
313 * pointer must either be NULL or point to a string
314 * returned by an IPRT string API. (In/Out)
315 * @param pszAppend The string to append. NULL and empty strings
316 * are quietly ignored.
317 * @param pszTag Allocation tag used for statistics and such.
319 RTDECL(int) RTStrAAppendTag(char **ppsz
, const char *pszAppend
, const char *pszTag
);
322 * Appends N bytes from a strings onto an existing IPRT allocated string
325 * @retval VINF_SUCCESS
326 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
329 * @param ppsz Pointer to the string pointer. The string
330 * pointer must either be NULL or point to a string
331 * returned by an IPRT string API. (In/Out)
332 * @param pszAppend The string to append. Can be NULL if cchAppend
334 * @param cchAppend The number of chars (not code points) to append
335 * from pszAppend. Must not be more than
336 * @a pszAppend contains, except for the special
337 * value RTSTR_MAX that can be used to indicate all
338 * of @a pszAppend without having to strlen it.
340 #define RTStrAAppendN(ppsz, pszAppend, cchAppend) RTStrAAppendNTag((ppsz), (pszAppend), (cchAppend), RTSTR_TAG)
343 * Appends N bytes from a strings onto an existing IPRT allocated string (custom
346 * @retval VINF_SUCCESS
347 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
350 * @param ppsz Pointer to the string pointer. The string
351 * pointer must either be NULL or point to a string
352 * returned by an IPRT string API. (In/Out)
353 * @param pszAppend The string to append. Can be NULL if cchAppend
355 * @param cchAppend The number of chars (not code points) to append
356 * from pszAppend. Must not be more than
357 * @a pszAppend contains, except for the special
358 * value RTSTR_MAX that can be used to indicate all
359 * of @a pszAppend without having to strlen it.
360 * @param pszTag Allocation tag used for statistics and such.
362 RTDECL(int) RTStrAAppendNTag(char **ppsz
, const char *pszAppend
, size_t cchAppend
, const char *pszTag
);
365 * Appends one or more strings onto an existing IPRT allocated string.
367 * This is a very flexible and efficient alternative to using RTStrAPrintf to
368 * combine several strings together.
370 * @retval VINF_SUCCESS
371 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
374 * @param ppsz Pointer to the string pointer. The string
375 * pointer must either be NULL or point to a string
376 * returned by an IPRT string API. (In/Out)
377 * @param cPairs The number of string / length pairs in the
379 * @param va List of string (const char *) and length
380 * (size_t) pairs. The strings will be appended to
381 * the string in the first argument.
383 #define RTStrAAppendExNV(ppsz, cPairs, va) RTStrAAppendExNVTag((ppsz), (cPairs), (va), RTSTR_TAG)
386 * Appends one or more strings onto an existing IPRT allocated string.
388 * This is a very flexible and efficient alternative to using RTStrAPrintf to
389 * combine several strings together.
391 * @retval VINF_SUCCESS
392 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
395 * @param ppsz Pointer to the string pointer. The string
396 * pointer must either be NULL or point to a string
397 * returned by an IPRT string API. (In/Out)
398 * @param cPairs The number of string / length pairs in the
400 * @param va List of string (const char *) and length
401 * (size_t) pairs. The strings will be appended to
402 * the string in the first argument.
403 * @param pszTag Allocation tag used for statistics and such.
405 RTDECL(int) RTStrAAppendExNVTag(char **ppsz
, size_t cPairs
, va_list va
, const char *pszTag
);
408 * Appends one or more strings onto an existing IPRT allocated string
411 * This is a very flexible and efficient alternative to using RTStrAPrintf to
412 * combine several strings together.
414 * @retval VINF_SUCCESS
415 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
418 * @param ppsz Pointer to the string pointer. The string
419 * pointer must either be NULL or point to a string
420 * returned by an IPRT string API. (In/Out)
421 * @param cPairs The number of string / length pairs in the
423 * @param ... List of string (const char *) and length
424 * (size_t) pairs. The strings will be appended to
425 * the string in the first argument.
427 DECLINLINE(int) RTStrAAppendExN(char **ppsz
, size_t cPairs
, ...)
431 va_start(va
, cPairs
);
432 rc
= RTStrAAppendExNVTag(ppsz
, cPairs
, va
, RTSTR_TAG
);
438 * Appends one or more strings onto an existing IPRT allocated string (custom
441 * This is a very flexible and efficient alternative to using RTStrAPrintf to
442 * combine several strings together.
444 * @retval VINF_SUCCESS
445 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
448 * @param ppsz Pointer to the string pointer. The string
449 * pointer must either be NULL or point to a string
450 * returned by an IPRT string API. (In/Out)
451 * @param pszTag Allocation tag used for statistics and such.
452 * @param cPairs The number of string / length pairs in the
454 * @param ... List of string (const char *) and length
455 * (size_t) pairs. The strings will be appended to
456 * the string in the first argument.
458 DECLINLINE(int) RTStrAAppendExNTag(char **ppsz
, const char *pszTag
, size_t cPairs
, ...)
462 va_start(va
, cPairs
);
463 rc
= RTStrAAppendExNVTag(ppsz
, cPairs
, va
, pszTag
);
469 * Truncates an IPRT allocated string (default tag).
471 * @retval VINF_SUCCESS.
472 * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
474 * @param ppsz Pointer to the string pointer. The string
475 * pointer can be NULL if @a cchNew is 0, no change
476 * is made then. If we actually reallocate the
477 * string, the string pointer might be changed by
478 * this call. (In/Out)
479 * @param cchNew The new string length (excluding the
480 * terminator). The string must be at least this
481 * long or we'll return VERR_OUT_OF_RANGE and
484 #define RTStrATruncate(ppsz, cchNew) RTStrATruncateTag((ppsz), (cchNew), RTSTR_TAG)
487 * Truncates an IPRT allocated string.
489 * @retval VINF_SUCCESS.
490 * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
492 * @param ppsz Pointer to the string pointer. The string
493 * pointer can be NULL if @a cchNew is 0, no change
494 * is made then. If we actually reallocate the
495 * string, the string pointer might be changed by
496 * this call. (In/Out)
497 * @param cchNew The new string length (excluding the
498 * terminator). The string must be at least this
499 * long or we'll return VERR_OUT_OF_RANGE and
501 * @param pszTag Allocation tag used for statistics and such.
503 RTDECL(int) RTStrATruncateTag(char **ppsz
, size_t cchNew
, const char *pszTag
);
506 * Allocates memory for string storage (default tag).
508 * You should normally not use this function, except if there is some very
509 * custom string handling you need doing that isn't covered by any of the other
512 * @returns Pointer to the allocated string. The first byte is always set
513 * to the string terminator char, the contents of the remainder of the
514 * memory is undefined. The string must be freed by calling RTStrFree.
516 * NULL is returned if the allocation failed. Please translate this to
517 * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
518 * RTStrAllocEx if an IPRT status code is required.
520 * @param cb How many bytes to allocate. If this is zero, we
521 * will allocate a terminator byte anyway.
523 #define RTStrAlloc(cb) RTStrAllocTag((cb), RTSTR_TAG)
526 * Allocates memory for string storage (custom tag).
528 * You should normally not use this function, except if there is some very
529 * custom string handling you need doing that isn't covered by any of the other
532 * @returns Pointer to the allocated string. The first byte is always set
533 * to the string terminator char, the contents of the remainder of the
534 * memory is undefined. The string must be freed by calling RTStrFree.
536 * NULL is returned if the allocation failed. Please translate this to
537 * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
538 * RTStrAllocEx if an IPRT status code is required.
540 * @param cb How many bytes to allocate. If this is zero, we
541 * will allocate a terminator byte anyway.
542 * @param pszTag Allocation tag used for statistics and such.
544 RTDECL(char *) RTStrAllocTag(size_t cb
, const char *pszTag
);
547 * Allocates memory for string storage, with status code (default tag).
549 * You should normally not use this function, except if there is some very
550 * custom string handling you need doing that isn't covered by any of the other
553 * @retval VINF_SUCCESS
554 * @retval VERR_NO_STR_MEMORY
556 * @param ppsz Where to return the allocated string. This will
557 * be set to NULL on failure. On success, the
558 * returned memory will always start with a
559 * terminator char so that it is considered a valid
560 * C string, the contents of rest of the memory is
562 * @param cb How many bytes to allocate. If this is zero, we
563 * will allocate a terminator byte anyway.
565 #define RTStrAllocEx(ppsz, cb) RTStrAllocExTag((ppsz), (cb), RTSTR_TAG)
568 * Allocates memory for string storage, with status code (custom tag).
570 * You should normally not use this function, except if there is some very
571 * custom string handling you need doing that isn't covered by any of the other
574 * @retval VINF_SUCCESS
575 * @retval VERR_NO_STR_MEMORY
577 * @param ppsz Where to return the allocated string. This will
578 * be set to NULL on failure. On success, the
579 * returned memory will always start with a
580 * terminator char so that it is considered a valid
581 * C string, the contents of rest of the memory is
583 * @param cb How many bytes to allocate. If this is zero, we
584 * will allocate a terminator byte anyway.
585 * @param pszTag Allocation tag used for statistics and such.
587 RTDECL(int) RTStrAllocExTag(char **ppsz
, size_t cb
, const char *pszTag
);
590 * Reallocates the specified string (default tag).
592 * You should normally not have use this function, except perhaps to truncate a
593 * really long string you've got from some IPRT string API, but then you should
594 * use RTStrATruncate.
596 * @returns VINF_SUCCESS.
597 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
600 * @param ppsz Pointer to the string variable containing the
601 * input and output string.
603 * When not freeing the string, the result will
604 * always have the last byte set to the terminator
605 * character so that when used for string
606 * truncation the result will be a valid C string
607 * (your job to keep it a valid UTF-8 string).
609 * When the input string is NULL and we're supposed
610 * to reallocate, the returned string will also
611 * have the first byte set to the terminator char
612 * so it will be a valid C string.
614 * @param cbNew When @a cbNew is zero, we'll behave like
615 * RTStrFree and @a *ppsz will be set to NULL.
617 * When not zero, this will be the new size of the
618 * memory backing the string, i.e. it includes the
621 #define RTStrRealloc(ppsz, cbNew) RTStrReallocTag((ppsz), (cbNew), RTSTR_TAG)
624 * Reallocates the specified string (custom tag).
626 * You should normally not have use this function, except perhaps to truncate a
627 * really long string you've got from some IPRT string API, but then you should
628 * use RTStrATruncate.
630 * @returns VINF_SUCCESS.
631 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
634 * @param ppsz Pointer to the string variable containing the
635 * input and output string.
637 * When not freeing the string, the result will
638 * always have the last byte set to the terminator
639 * character so that when used for string
640 * truncation the result will be a valid C string
641 * (your job to keep it a valid UTF-8 string).
643 * When the input string is NULL and we're supposed
644 * to reallocate, the returned string will also
645 * have the first byte set to the terminator char
646 * so it will be a valid C string.
648 * @param cbNew When @a cbNew is zero, we'll behave like
649 * RTStrFree and @a *ppsz will be set to NULL.
651 * When not zero, this will be the new size of the
652 * memory backing the string, i.e. it includes the
654 * @param pszTag Allocation tag used for statistics and such.
656 RTDECL(int) RTStrReallocTag(char **ppsz
, size_t cbNew
, const char *pszTag
);
659 * Validates the UTF-8 encoding of the string.
661 * @returns iprt status code.
662 * @param psz The string.
664 RTDECL(int) RTStrValidateEncoding(const char *psz
);
666 /** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
669 /** Check that the string is zero terminated within the given size.
670 * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
671 #define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED RT_BIT_32(0)
672 /** Check that the string is exactly the given length.
673 * If it terminates early, VERR_BUFFER_UNDERFLOW will be returned. When used
674 * together with RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED, the given length must
675 * include the terminator or VERR_BUFFER_OVERFLOW will be returned. */
676 #define RTSTR_VALIDATE_ENCODING_EXACT_LENGTH RT_BIT_32(1)
680 * Validates the UTF-8 encoding of the string.
682 * @returns iprt status code.
683 * @param psz The string.
684 * @param cch The max string length (/ size). Use RTSTR_MAX to
685 * process the entire string.
686 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
688 RTDECL(int) RTStrValidateEncodingEx(const char *psz
, size_t cch
, uint32_t fFlags
);
691 * Checks if the UTF-8 encoding is valid.
693 * @returns true / false.
694 * @param psz The string.
696 RTDECL(bool) RTStrIsValidEncoding(const char *psz
);
699 * Purge all bad UTF-8 encoding in the string, replacing it with '?'.
701 * @returns The number of bad characters (0 if nothing was done).
702 * @param psz The string to purge.
704 RTDECL(size_t) RTStrPurgeEncoding(char *psz
);
707 * Sanitizes a (valid) UTF-8 string by replacing all characters outside a white
708 * list in-place by an ASCII replacement character.
710 * Multi-byte characters will be replaced byte by byte.
712 * @returns The number of code points replaced. In the case of an incorrectly
713 * encoded string -1 will be returned, and the string is not completely
714 * processed. In the case of puszValidPairs having an odd number of
715 * code points, -1 will be also return but without any modification to
717 * @param psz The string to sanitise.
718 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
719 * Each pair is the start and end point of a range,
720 * and the union of these ranges forms the white list.
721 * @param chReplacement The ASCII replacement character.
723 RTDECL(ssize_t
) RTStrPurgeComplementSet(char *psz
, PCRTUNICP puszValidPairs
, char chReplacement
);
726 * Gets the number of code points the string is made up of, excluding
730 * @returns Number of code points (RTUNICP).
731 * @returns 0 if the string was incorrectly encoded.
732 * @param psz The string.
734 RTDECL(size_t) RTStrUniLen(const char *psz
);
737 * Gets the number of code points the string is made up of, excluding
740 * This function will validate the string, and incorrectly encoded UTF-8
741 * strings will be rejected.
743 * @returns iprt status code.
744 * @param psz The string.
745 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
746 * @param pcuc Where to store the code point count.
747 * This is undefined on failure.
749 RTDECL(int) RTStrUniLenEx(const char *psz
, size_t cch
, size_t *pcuc
);
752 * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
754 * @returns iprt status code.
755 * @param pszString UTF-8 string to convert.
756 * @param ppUniString Receives pointer to the allocated unicode string.
757 * The returned string must be freed using RTUniFree().
759 RTDECL(int) RTStrToUni(const char *pszString
, PRTUNICP
*ppUniString
);
762 * Translates pszString from UTF-8 to an array of code points, allocating the result
763 * array if requested.
765 * @returns iprt status code.
766 * @param pszString UTF-8 string to convert.
767 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
768 * when it reaches cchString or the string terminator ('\\0').
769 * Use RTSTR_MAX to translate the entire string.
770 * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
771 * a buffer of the specified size, or pointer to a NULL pointer.
772 * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
773 * will be allocated to hold the translated string.
774 * If a buffer was requested it must be freed using RTUtf16Free().
775 * @param cCps The number of code points in the unicode string. This includes the terminator.
776 * @param pcCps Where to store the length of the translated string,
777 * excluding the terminator. (Optional)
779 * This may be set under some error conditions,
780 * however, only for VERR_BUFFER_OVERFLOW and
781 * VERR_NO_STR_MEMORY will it contain a valid string
782 * length that can be used to resize the buffer.
784 RTDECL(int) RTStrToUniEx(const char *pszString
, size_t cchString
, PRTUNICP
*ppaCps
, size_t cCps
, size_t *pcCps
);
787 * Calculates the length of the string in RTUTF16 items.
789 * This function will validate the string, and incorrectly encoded UTF-8
790 * strings will be rejected. The primary purpose of this function is to
791 * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
792 * other purposes RTStrCalcUtf16LenEx() should be used.
794 * @returns Number of RTUTF16 items.
795 * @returns 0 if the string was incorrectly encoded.
796 * @param psz The string.
798 RTDECL(size_t) RTStrCalcUtf16Len(const char *psz
);
801 * Calculates the length of the string in RTUTF16 items.
803 * This function will validate the string, and incorrectly encoded UTF-8
804 * strings will be rejected.
806 * @returns iprt status code.
807 * @param psz The string.
808 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
809 * @param pcwc Where to store the string length. Optional.
810 * This is undefined on failure.
812 RTDECL(int) RTStrCalcUtf16LenEx(const char *psz
, size_t cch
, size_t *pcwc
);
815 * Translate a UTF-8 string into a UTF-16 allocating the result buffer (default
818 * @returns iprt status code.
819 * @param pszString UTF-8 string to convert.
820 * @param ppwszString Receives pointer to the allocated UTF-16 string.
821 * The returned string must be freed using RTUtf16Free().
823 #define RTStrToUtf16(pszString, ppwszString) RTStrToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
826 * Translate a UTF-8 string into a UTF-16 allocating the result buffer (custom
829 * @returns iprt status code.
830 * @param pszString UTF-8 string to convert.
831 * @param ppwszString Receives pointer to the allocated UTF-16 string.
832 * The returned string must be freed using RTUtf16Free().
833 * @param pszTag Allocation tag used for statistics and such.
835 RTDECL(int) RTStrToUtf16Tag(const char *pszString
, PRTUTF16
*ppwszString
, const char *pszTag
);
838 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
840 * @returns iprt status code.
841 * @param pszString UTF-8 string to convert.
842 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
843 * when it reaches cchString or the string terminator ('\\0').
844 * Use RTSTR_MAX to translate the entire string.
845 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
846 * a buffer of the specified size, or pointer to a NULL pointer.
847 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
848 * will be allocated to hold the translated string.
849 * If a buffer was requested it must be freed using RTUtf16Free().
850 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
851 * @param pcwc Where to store the length of the translated string,
852 * excluding the terminator. (Optional)
854 * This may be set under some error conditions,
855 * however, only for VERR_BUFFER_OVERFLOW and
856 * VERR_NO_STR_MEMORY will it contain a valid string
857 * length that can be used to resize the buffer.
859 #define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
860 RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
863 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
864 * requested (custom tag).
866 * @returns iprt status code.
867 * @param pszString UTF-8 string to convert.
868 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
869 * when it reaches cchString or the string terminator ('\\0').
870 * Use RTSTR_MAX to translate the entire string.
871 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
872 * a buffer of the specified size, or pointer to a NULL pointer.
873 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
874 * will be allocated to hold the translated string.
875 * If a buffer was requested it must be freed using RTUtf16Free().
876 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
877 * @param pcwc Where to store the length of the translated string,
878 * excluding the terminator. (Optional)
880 * This may be set under some error conditions,
881 * however, only for VERR_BUFFER_OVERFLOW and
882 * VERR_NO_STR_MEMORY will it contain a valid string
883 * length that can be used to resize the buffer.
884 * @param pszTag Allocation tag used for statistics and such.
886 RTDECL(int) RTStrToUtf16ExTag(const char *pszString
, size_t cchString
, PRTUTF16
*ppwsz
, size_t cwc
, size_t *pcwc
, const char *pszTag
);
890 * Calculates the length of the string in Latin-1 characters.
892 * This function will validate the string, and incorrectly encoded UTF-8
893 * strings as well as string with codepoints outside the latin-1 range will be
894 * rejected. The primary purpose of this function is to help allocate buffers
895 * for RTStrToLatin1Ex of the correct size. For most other purposes
896 * RTStrCalcLatin1LenEx() should be used.
898 * @returns Number of Latin-1 characters.
899 * @returns 0 if the string was incorrectly encoded.
900 * @param psz The string.
902 RTDECL(size_t) RTStrCalcLatin1Len(const char *psz
);
905 * Calculates the length of the string in Latin-1 characters.
907 * This function will validate the string, and incorrectly encoded UTF-8
908 * strings as well as string with codepoints outside the latin-1 range will be
911 * @returns iprt status code.
912 * @param psz The string.
913 * @param cch The max string length. Use RTSTR_MAX to process the
915 * @param pcch Where to store the string length. Optional.
916 * This is undefined on failure.
918 RTDECL(int) RTStrCalcLatin1LenEx(const char *psz
, size_t cch
, size_t *pcch
);
921 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
924 * @returns iprt status code.
925 * @param pszString UTF-8 string to convert.
926 * @param ppszString Receives pointer to the allocated Latin-1 string.
927 * The returned string must be freed using RTStrFree().
929 #define RTStrToLatin1(pszString, ppszString) RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
932 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
935 * @returns iprt status code.
936 * @param pszString UTF-8 string to convert.
937 * @param ppszString Receives pointer to the allocated Latin-1 string.
938 * The returned string must be freed using RTStrFree().
939 * @param pszTag Allocation tag used for statistics and such.
941 RTDECL(int) RTStrToLatin1Tag(const char *pszString
, char **ppszString
, const char *pszTag
);
944 * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
946 * @returns iprt status code.
947 * @param pszString UTF-8 string to convert.
948 * @param cchString The maximum size in chars (the type) to convert.
949 * The conversion stop when it reaches cchString or
950 * the string terminator ('\\0'). Use RTSTR_MAX to
951 * translate the entire string.
952 * @param ppsz If cch is non-zero, this must either be pointing to
953 * pointer to a buffer of the specified size, or
954 * pointer to a NULL pointer. If *ppsz is NULL or cch
955 * is zero a buffer of at least cch items will be
956 * allocated to hold the translated string. If a
957 * buffer was requested it must be freed using
959 * @param cch The buffer size in bytes. This includes the
961 * @param pcch Where to store the length of the translated string,
962 * excluding the terminator. (Optional)
964 * This may be set under some error conditions,
965 * however, only for VERR_BUFFER_OVERFLOW and
966 * VERR_NO_STR_MEMORY will it contain a valid string
967 * length that can be used to resize the buffer.
969 #define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
970 RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
973 * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
974 * requested (custom tag).
976 * @returns iprt status code.
977 * @param pszString UTF-8 string to convert.
978 * @param cchString The maximum size in chars (the type) to convert.
979 * The conversion stop when it reaches cchString or
980 * the string terminator ('\\0'). Use RTSTR_MAX to
981 * translate the entire string.
982 * @param ppsz If cch is non-zero, this must either be pointing to
983 * pointer to a buffer of the specified size, or
984 * pointer to a NULL pointer. If *ppsz is NULL or cch
985 * is zero a buffer of at least cch items will be
986 * allocated to hold the translated string. If a
987 * buffer was requested it must be freed using
989 * @param cch The buffer size in bytes. This includes the
991 * @param pcch Where to store the length of the translated string,
992 * excluding the terminator. (Optional)
994 * This may be set under some error conditions,
995 * however, only for VERR_BUFFER_OVERFLOW and
996 * VERR_NO_STR_MEMORY will it contain a valid string
997 * length that can be used to resize the buffer.
998 * @param pszTag Allocation tag used for statistics and such.
1000 RTDECL(int) RTStrToLatin1ExTag(const char *pszString
, size_t cchString
, char **ppsz
, size_t cch
, size_t *pcch
, const char *pszTag
);
1003 * Get the unicode code point at the given string position.
1005 * @returns unicode code point.
1006 * @returns RTUNICP_INVALID if the encoding is invalid.
1007 * @param psz The string.
1009 RTDECL(RTUNICP
) RTStrGetCpInternal(const char *psz
);
1012 * Get the unicode code point at the given string position.
1014 * @returns iprt status code
1015 * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1016 * @param ppsz The string cursor.
1017 * This is advanced one character forward on failure.
1018 * @param pCp Where to store the unicode code point.
1019 * Stores RTUNICP_INVALID if the encoding is invalid.
1021 RTDECL(int) RTStrGetCpExInternal(const char **ppsz
, PRTUNICP pCp
);
1024 * Get the unicode code point at the given string position for a string of a
1027 * @returns iprt status code
1028 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1029 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1031 * @param ppsz The string.
1032 * @param pcch Pointer to the length of the string. This will be
1033 * decremented by the size of the code point.
1034 * @param pCp Where to store the unicode code point.
1035 * Stores RTUNICP_INVALID if the encoding is invalid.
1037 RTDECL(int) RTStrGetCpNExInternal(const char **ppsz
, size_t *pcch
, PRTUNICP pCp
);
1040 * Put the unicode code point at the given string position
1041 * and return the pointer to the char following it.
1043 * This function will not consider anything at or following the
1044 * buffer area pointed to by psz. It is therefore not suitable for
1045 * inserting code points into a string, only appending/overwriting.
1047 * @returns pointer to the char following the written code point.
1048 * @param psz The string.
1049 * @param CodePoint The code point to write.
1050 * This should not be RTUNICP_INVALID or any other
1051 * character out of the UTF-8 range.
1053 * @remark This is a worker function for RTStrPutCp().
1056 RTDECL(char *) RTStrPutCpInternal(char *psz
, RTUNICP CodePoint
);
1059 * Get the unicode code point at the given string position.
1061 * @returns unicode code point.
1062 * @returns RTUNICP_INVALID if the encoding is invalid.
1063 * @param psz The string.
1065 * @remark We optimize this operation by using an inline function for
1066 * the most frequent and simplest sequence, the rest is
1067 * handled by RTStrGetCpInternal().
1069 DECLINLINE(RTUNICP
) RTStrGetCp(const char *psz
)
1071 const unsigned char uch
= *(const unsigned char *)psz
;
1072 if (!(uch
& RT_BIT(7)))
1074 return RTStrGetCpInternal(psz
);
1078 * Get the unicode code point at the given string position.
1080 * @returns iprt status code.
1081 * @param ppsz Pointer to the string pointer. This will be updated to
1082 * point to the char following the current code point.
1083 * This is advanced one character forward on failure.
1084 * @param pCp Where to store the code point.
1085 * RTUNICP_INVALID is stored here on failure.
1087 * @remark We optimize this operation by using an inline function for
1088 * the most frequent and simplest sequence, the rest is
1089 * handled by RTStrGetCpExInternal().
1091 DECLINLINE(int) RTStrGetCpEx(const char **ppsz
, PRTUNICP pCp
)
1093 const unsigned char uch
= **(const unsigned char **)ppsz
;
1094 if (!(uch
& RT_BIT(7)))
1098 return VINF_SUCCESS
;
1100 return RTStrGetCpExInternal(ppsz
, pCp
);
1104 * Get the unicode code point at the given string position for a string of a
1105 * given maximum length.
1107 * @returns iprt status code.
1108 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1109 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1111 * @param ppsz Pointer to the string pointer. This will be updated to
1112 * point to the char following the current code point.
1113 * @param pcch Pointer to the maximum string length. This will be
1114 * decremented by the size of the code point found.
1115 * @param pCp Where to store the code point.
1116 * RTUNICP_INVALID is stored here on failure.
1118 * @remark We optimize this operation by using an inline function for
1119 * the most frequent and simplest sequence, the rest is
1120 * handled by RTStrGetCpNExInternal().
1122 DECLINLINE(int) RTStrGetCpNEx(const char **ppsz
, size_t *pcch
, PRTUNICP pCp
)
1124 if (RT_LIKELY(*pcch
!= 0))
1126 const unsigned char uch
= **(const unsigned char **)ppsz
;
1127 if (!(uch
& RT_BIT(7)))
1132 return VINF_SUCCESS
;
1135 return RTStrGetCpNExInternal(ppsz
, pcch
, pCp
);
1139 * Get the UTF-8 size in characters of a given Unicode code point.
1141 * The code point is expected to be a valid Unicode one, but not necessarily in
1142 * the range supported by UTF-8.
1144 * @returns The number of chars (bytes) required to encode the code point, or
1145 * zero if there is no UTF-8 encoding.
1146 * @param CodePoint The unicode code point.
1148 DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint
)
1150 if (CodePoint
< 0x00000080)
1152 if (CodePoint
< 0x00000800)
1154 if (CodePoint
< 0x00010000)
1156 #ifdef RT_USE_RTC_3629
1157 if (CodePoint
< 0x00011000)
1160 if (CodePoint
< 0x00200000)
1162 if (CodePoint
< 0x04000000)
1164 if (CodePoint
< 0x7fffffff)
1171 * Put the unicode code point at the given string position
1172 * and return the pointer to the char following it.
1174 * This function will not consider anything at or following the
1175 * buffer area pointed to by psz. It is therefore not suitable for
1176 * inserting code points into a string, only appending/overwriting.
1178 * @returns pointer to the char following the written code point.
1179 * @param psz The string.
1180 * @param CodePoint The code point to write.
1181 * This should not be RTUNICP_INVALID or any other
1182 * character out of the UTF-8 range.
1184 * @remark We optimize this operation by using an inline function for
1185 * the most frequent and simplest sequence, the rest is
1186 * handled by RTStrPutCpInternal().
1188 DECLINLINE(char *) RTStrPutCp(char *psz
, RTUNICP CodePoint
)
1190 if (CodePoint
< 0x80)
1192 *psz
++ = (unsigned char)CodePoint
;
1195 return RTStrPutCpInternal(psz
, CodePoint
);
1199 * Skips ahead, past the current code point.
1201 * @returns Pointer to the char after the current code point.
1202 * @param psz Pointer to the current code point.
1203 * @remark This will not move the next valid code point, only past the current one.
1205 DECLINLINE(char *) RTStrNextCp(const char *psz
)
1208 RTStrGetCpEx(&psz
, &Cp
);
1213 * Skips back to the previous code point.
1215 * @returns Pointer to the char before the current code point.
1216 * @returns pszStart on failure.
1217 * @param pszStart Pointer to the start of the string.
1218 * @param psz Pointer to the current code point.
1220 RTDECL(char *) RTStrPrevCp(const char *pszStart
, const char *psz
);
1223 /** @page pg_rt_str_format The IPRT Format Strings
1225 * IPRT implements most of the commonly used format types and flags with the
1226 * exception of floating point which is completely missing. In addition IPRT
1227 * provides a number of IPRT specific format types for the IPRT typedefs and
1228 * other useful things. Note that several of these extensions are similar to
1229 * \%p and doesn't care much if you try add formating flags/width/precision.
1232 * Group 0a, The commonly used format types:
1233 * - \%s - Takes a pointer to a zero terminated string (UTF-8) and
1234 * prints it with the optionally adjustment (width, -) and
1235 * length restriction (precision).
1236 * - \%ls - Same as \%s except that the input is UTF-16 (output UTF-8).
1237 * - \%Ls - Same as \%s except that the input is UCS-32 (output UTF-8).
1238 * - \%S - Same as \%s, used to convert to current codeset but this is
1239 * now done by the streams code. Deprecated, use \%s.
1240 * - \%lS - Ditto. Deprecated, use \%ls.
1241 * - \%LS - Ditto. Deprecated, use \%Ls.
1242 * - \%c - Takes a char and prints it.
1243 * - \%d - Takes a signed integer and prints it as decimal. Thousand
1244 * separator (\'), zero padding (0), adjustment (-+), width,
1246 * - \%i - Same as \%d.
1247 * - \%u - Takes an unsigned integer and prints it as decimal. Thousand
1248 * separator (\'), zero padding (0), adjustment (-+), width,
1250 * - \%x - Takes an unsigned integer and prints it as lowercased
1251 * hexadecimal. The special hash (\#) flag causes a '0x'
1252 * prefixed to be printed. Zero padding (0), adjustment (-+),
1254 * - \%X - Same as \%x except that it is uppercased.
1255 * - \%o - Takes an unsigned (?) integer and prints it as octal. Zero
1256 * padding (0), adjustment (-+), width, precision.
1257 * - \%p - Takes a pointer (void technically) and prints it. Zero
1258 * padding (0), adjustment (-+), width, precision.
1260 * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
1261 * argument type specifiers:
1262 * - \%ll - long long (uint64_t).
1263 * - \%L - long long (uint64_t).
1264 * - \%l - long (uint32_t, uint64_t)
1265 * - \%h - short (int16_t).
1266 * - \%hh - char (int8_t).
1267 * - \%H - char (int8_t).
1269 * - \%j - intmax_t (int64_t).
1270 * - \%t - ptrdiff_t.
1271 * The type in parentheses is typical sizes, however when printing those types
1272 * you are better off using the special group 2 format types below (\%RX32 and
1276 * Group 0b, IPRT format tricks:
1277 * - %M - Replaces the format string, takes a string pointer.
1278 * - %N - Nested formatting, takes a pointer to a format string
1279 * followed by the pointer to a va_list variable. The va_list
1280 * variable will not be modified and the caller must do va_end()
1281 * on it. Make sure the va_list variable is NOT in a parameter
1282 * list or some gcc versions/targets may get it all wrong.
1285 * Group 1, the basic runtime typedefs (excluding those which obviously are
1287 * - \%RTbool - Takes a bool value and prints 'true', 'false', or '!%d!'.
1288 * - \%RTfile - Takes a #RTFILE value.
1289 * - \%RTfmode - Takes a #RTFMODE value.
1290 * - \%RTfoff - Takes a #RTFOFF value.
1291 * - \%RTfp16 - Takes a #RTFAR16 value.
1292 * - \%RTfp32 - Takes a #RTFAR32 value.
1293 * - \%RTfp64 - Takes a #RTFAR64 value.
1294 * - \%RTgid - Takes a #RTGID value.
1295 * - \%RTino - Takes a #RTINODE value.
1296 * - \%RTint - Takes a #RTINT value.
1297 * - \%RTiop - Takes a #RTIOPORT value.
1298 * - \%RTldrm - Takes a #RTLDRMOD value.
1299 * - \%RTmac - Takes a #PCRTMAC pointer.
1300 * - \%RTnaddr - Takes a #PCRTNETADDR value.
1301 * - \%RTnaipv4 - Takes a #RTNETADDRIPV4 value.
1302 * - \%RTnaipv6 - Takes a #PCRTNETADDRIPV6 value.
1303 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1304 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1305 * - \%RTproc - Takes a #RTPROCESS value.
1306 * - \%RTptr - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
1307 * - \%RTreg - Takes a #RTCCUINTREG value.
1308 * - \%RTsel - Takes a #RTSEL value.
1309 * - \%RTsem - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
1310 * - \%RTsock - Takes a #RTSOCKET value.
1311 * - \%RTthrd - Takes a #RTTHREAD value.
1312 * - \%RTuid - Takes a #RTUID value.
1313 * - \%RTuint - Takes a #RTUINT value.
1314 * - \%RTunicp - Takes a #RTUNICP value.
1315 * - \%RTutf16 - Takes a #RTUTF16 value.
1316 * - \%RTuuid - Takes a #PCRTUUID and will print the UUID as a string.
1317 * - \%RTxuint - Takes a #RTUINT or #RTINT value, formatting it as hex.
1318 * - \%RGi - Takes a #RTGCINT value.
1319 * - \%RGp - Takes a #RTGCPHYS value.
1320 * - \%RGr - Takes a #RTGCUINTREG value.
1321 * - \%RGu - Takes a #RTGCUINT value.
1322 * - \%RGv - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
1323 * - \%RGx - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
1324 * - \%RHi - Takes a #RTHCINT value.
1325 * - \%RHp - Takes a #RTHCPHYS value.
1326 * - \%RHr - Takes a #RTHCUINTREG value.
1327 * - \%RHu - Takes a #RTHCUINT value.
1328 * - \%RHv - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
1329 * - \%RHx - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
1330 * - \%RRv - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
1331 * - \%RCi - Takes a #RTINT value.
1332 * - \%RCp - Takes a #RTCCPHYS value.
1333 * - \%RCr - Takes a #RTCCUINTREG value.
1334 * - \%RCu - Takes a #RTUINT value.
1335 * - \%RCv - Takes a #uintptr_t, #intptr_t, void * value.
1336 * - \%RCx - Takes a #RTUINT or #RTINT value, formatting it as hex.
1339 * Group 2, the generic integer types which are prefered over relying on what
1340 * bit-count a 'long', 'short', or 'long long' has on a platform. This are
1341 * highly prefered for the [u]intXX_t kind of types:
1342 * - \%RI[8|16|32|64] - Signed integer value of the specifed bit count.
1343 * - \%RU[8|16|32|64] - Unsigned integer value of the specifed bit count.
1344 * - \%RX[8|16|32|64] - Hexadecimal integer value of the specifed bit count.
1347 * Group 3, hex dumpers and other complex stuff which requires more than simple
1349 * - \%Rhxd - Takes a pointer to the memory which is to be dumped in typical
1350 * hex format. Use the precision to specify the length, and the width to
1351 * set the number of bytes per line. Default width and precision is 16.
1352 * - \%Rhxs - Takes a pointer to the memory to be displayed as a hex string,
1353 * i.e. a series of space separated bytes formatted as two digit hex value.
1354 * Use the precision to specify the length. Default length is 16 bytes.
1355 * The width, if specified, is ignored.
1356 * - \%Rrc - Takes an integer iprt status code as argument. Will insert the
1357 * status code define corresponding to the iprt status code.
1358 * - \%Rrs - Takes an integer iprt status code as argument. Will insert the
1359 * short description of the specified status code.
1360 * - \%Rrf - Takes an integer iprt status code as argument. Will insert the
1361 * full description of the specified status code.
1362 * - \%Rra - Takes an integer iprt status code as argument. Will insert the
1363 * status code define + full description.
1364 * - \%Rwc - Takes a long Windows error code as argument. Will insert the status
1365 * code define corresponding to the Windows error code.
1366 * - \%Rwf - Takes a long Windows error code as argument. Will insert the
1367 * full description of the specified status code.
1368 * - \%Rwa - Takes a long Windows error code as argument. Will insert the
1369 * error code define + full description.
1371 * - \%Rhrc - Takes a COM/XPCOM status code as argument. Will insert the status
1372 * code define corresponding to the Windows error code.
1373 * - \%Rhrf - Takes a COM/XPCOM status code as argument. Will insert the
1374 * full description of the specified status code.
1375 * - \%Rhra - Takes a COM/XPCOM error code as argument. Will insert the
1376 * error code define + full description.
1378 * - \%Rfn - Pretty printing of a function or method. It drops the
1379 * return code and parameter list.
1380 * - \%Rbn - Prints the base name. For dropping the path in
1381 * order to save space when printing a path name.
1383 * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
1386 * Group 4, structure dumpers:
1387 * - \%RDtimespec - Takes a PCRTTIMESPEC.
1390 * Group 5, XML / HTML escapers:
1391 * - \%RMas - Takes a string pointer (const char *) and outputs
1392 * it as an attribute value with the proper escaping.
1393 * This typically ends up in double quotes.
1395 * - \%RMes - Takes a string pointer (const char *) and outputs
1396 * it as an element with the necessary escaping.
1398 * Group 6, CPU Architecture Register dumpers:
1399 * - \%RAx86[reg] - Takes a 64-bit register value if the register is
1400 * 64-bit or smaller. Check the code wrt which
1401 * registers are implemented.
1405 #ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
1406 # define DECLARED_FNRTSTROUTPUT
1410 * @returns number of bytes written.
1411 * @param pvArg User argument.
1412 * @param pachChars Pointer to an array of utf-8 characters.
1413 * @param cbChars Number of bytes in the character array pointed to by pachChars.
1415 typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg
, const char *pachChars
, size_t cbChars
);
1416 /** Pointer to callback function. */
1417 typedef FNRTSTROUTPUT
*PFNRTSTROUTPUT
;
1420 /** @name Format flag.
1421 * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
1422 * that not all flags makes sense to both of the functions.
1424 #define RTSTR_F_CAPITAL 0x0001
1425 #define RTSTR_F_LEFT 0x0002
1426 #define RTSTR_F_ZEROPAD 0x0004
1427 #define RTSTR_F_SPECIAL 0x0008
1428 #define RTSTR_F_VALSIGNED 0x0010
1429 #define RTSTR_F_PLUS 0x0020
1430 #define RTSTR_F_BLANK 0x0040
1431 #define RTSTR_F_WIDTH 0x0080
1432 #define RTSTR_F_PRECISION 0x0100
1433 #define RTSTR_F_THOUSAND_SEP 0x0200
1434 #define RTSTR_F_OBFUSCATE_PTR 0x0400
1436 #define RTSTR_F_BIT_MASK 0xf800
1437 #define RTSTR_F_8BIT 0x0800
1438 #define RTSTR_F_16BIT 0x1000
1439 #define RTSTR_F_32BIT 0x2000
1440 #define RTSTR_F_64BIT 0x4000
1441 #define RTSTR_F_128BIT 0x8000
1444 /** @def RTSTR_GET_BIT_FLAG
1445 * Gets the bit flag for the specified type.
1447 #define RTSTR_GET_BIT_FLAG(type) \
1448 ( sizeof(type) * 8 == 32 ? RTSTR_F_32BIT \
1449 : sizeof(type) * 8 == 64 ? RTSTR_F_64BIT \
1450 : sizeof(type) * 8 == 16 ? RTSTR_F_16BIT \
1451 : sizeof(type) * 8 == 8 ? RTSTR_F_8BIT \
1452 : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
1457 * Callback to format non-standard format specifiers.
1459 * @returns The number of bytes formatted.
1460 * @param pvArg Formatter argument.
1461 * @param pfnOutput Pointer to output function.
1462 * @param pvArgOutput Argument for the output function.
1463 * @param ppszFormat Pointer to the format string pointer. Advance this till the char
1464 * after the format specifier.
1465 * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
1466 * @param cchWidth Format Width. -1 if not specified.
1467 * @param cchPrecision Format Precision. -1 if not specified.
1468 * @param fFlags Flags (RTSTR_NTFS_*).
1469 * @param chArgSize The argument size specifier, 'l' or 'L'.
1471 typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg
, PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
,
1472 const char **ppszFormat
, va_list *pArgs
, int cchWidth
,
1473 int cchPrecision
, unsigned fFlags
, char chArgSize
);
1474 /** Pointer to a FNSTRFORMAT() function. */
1475 typedef FNSTRFORMAT
*PFNSTRFORMAT
;
1479 * Partial implementation of a printf like formatter.
1480 * It doesn't do everything correct, and there is no floating point support.
1481 * However, it supports custom formats by the means of a format callback.
1483 * @returns number of bytes formatted.
1484 * @param pfnOutput Output worker.
1485 * Called in two ways. Normally with a string and its length.
1486 * For termination, it's called with NULL for string, 0 for length.
1487 * @param pvArgOutput Argument to the output worker.
1488 * @param pfnFormat Custom format worker.
1489 * @param pvArgFormat Argument to the format worker.
1490 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1491 * @param InArgs Argument list.
1493 RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
, PFNSTRFORMAT pfnFormat
, void *pvArgFormat
,
1494 const char *pszFormat
, va_list InArgs
) RT_IPRT_FORMAT_ATTR(5, 0);
1497 * Partial implementation of a printf like formatter.
1498 * It doesn't do everything correct, and there is no floating point support.
1499 * However, it supports custom formats by the means of a format callback.
1501 * @returns number of bytes formatted.
1502 * @param pfnOutput Output worker.
1503 * Called in two ways. Normally with a string and its length.
1504 * For termination, it's called with NULL for string, 0 for length.
1505 * @param pvArgOutput Argument to the output worker.
1506 * @param pfnFormat Custom format worker.
1507 * @param pvArgFormat Argument to the format worker.
1508 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1509 * @param ... Argument list.
1511 RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
, PFNSTRFORMAT pfnFormat
, void *pvArgFormat
,
1512 const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1515 * Formats an integer number according to the parameters.
1517 * @returns Length of the formatted number.
1518 * @param psz Pointer to output string buffer of sufficient size.
1519 * @param u64Value Value to format.
1520 * @param uiBase Number representation base.
1521 * @param cchWidth Width.
1522 * @param cchPrecision Precision.
1523 * @param fFlags Flags, RTSTR_F_XXX.
1525 RTDECL(int) RTStrFormatNumber(char *psz
, uint64_t u64Value
, unsigned int uiBase
, signed int cchWidth
, signed int cchPrecision
,
1526 unsigned int fFlags
);
1529 * Formats an unsigned 8-bit number.
1531 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1532 * @param pszBuf The output buffer.
1533 * @param cbBuf The size of the output buffer.
1534 * @param u8Value The value to format.
1535 * @param uiBase Number representation base.
1536 * @param cchWidth Width.
1537 * @param cchPrecision Precision.
1538 * @param fFlags Flags, RTSTR_F_XXX.
1540 RTDECL(ssize_t
) RTStrFormatU8(char *pszBuf
, size_t cbBuf
, uint8_t u8Value
, unsigned int uiBase
,
1541 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1544 * Formats an unsigned 16-bit number.
1546 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1547 * @param pszBuf The output buffer.
1548 * @param cbBuf The size of the output buffer.
1549 * @param u16Value The value to format.
1550 * @param uiBase Number representation base.
1551 * @param cchWidth Width.
1552 * @param cchPrecision Precision.
1553 * @param fFlags Flags, RTSTR_F_XXX.
1555 RTDECL(ssize_t
) RTStrFormatU16(char *pszBuf
, size_t cbBuf
, uint16_t u16Value
, unsigned int uiBase
,
1556 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1559 * Formats an unsigned 32-bit number.
1561 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1562 * @param pszBuf The output buffer.
1563 * @param cbBuf The size of the output buffer.
1564 * @param u32Value The value to format.
1565 * @param uiBase Number representation base.
1566 * @param cchWidth Width.
1567 * @param cchPrecision Precision.
1568 * @param fFlags Flags, RTSTR_F_XXX.
1570 RTDECL(ssize_t
) RTStrFormatU32(char *pszBuf
, size_t cbBuf
, uint32_t u32Value
, unsigned int uiBase
,
1571 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1574 * Formats an unsigned 64-bit number.
1576 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1577 * @param pszBuf The output buffer.
1578 * @param cbBuf The size of the output buffer.
1579 * @param u64Value The value to format.
1580 * @param uiBase Number representation base.
1581 * @param cchWidth Width.
1582 * @param cchPrecision Precision.
1583 * @param fFlags Flags, RTSTR_F_XXX.
1585 RTDECL(ssize_t
) RTStrFormatU64(char *pszBuf
, size_t cbBuf
, uint64_t u64Value
, unsigned int uiBase
,
1586 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1589 * Formats an unsigned 128-bit number.
1591 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1592 * @param pszBuf The output buffer.
1593 * @param cbBuf The size of the output buffer.
1594 * @param pu128Value The value to format.
1595 * @param uiBase Number representation base.
1596 * @param cchWidth Width.
1597 * @param cchPrecision Precision.
1598 * @param fFlags Flags, RTSTR_F_XXX.
1599 * @remarks The current implementation is limited to base 16 and doesn't do
1600 * width or precision and probably ignores few flags too.
1602 RTDECL(ssize_t
) RTStrFormatU128(char *pszBuf
, size_t cbBuf
, PCRTUINT128U pu128Value
, unsigned int uiBase
,
1603 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1606 * Formats an unsigned 256-bit number.
1608 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1609 * @param pszBuf The output buffer.
1610 * @param cbBuf The size of the output buffer.
1611 * @param pu256Value The value to format.
1612 * @param uiBase Number representation base.
1613 * @param cchWidth Width.
1614 * @param cchPrecision Precision.
1615 * @param fFlags Flags, RTSTR_F_XXX.
1616 * @remarks The current implementation is limited to base 16 and doesn't do
1617 * width or precision and probably ignores few flags too.
1619 RTDECL(ssize_t
) RTStrFormatU256(char *pszBuf
, size_t cbBuf
, PCRTUINT256U pu256Value
, unsigned int uiBase
,
1620 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1623 * Formats an unsigned 512-bit number.
1625 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1626 * @param pszBuf The output buffer.
1627 * @param cbBuf The size of the output buffer.
1628 * @param pu512Value The value to format.
1629 * @param uiBase Number representation base.
1630 * @param cchWidth Width.
1631 * @param cchPrecision Precision.
1632 * @param fFlags Flags, RTSTR_F_XXX.
1633 * @remarks The current implementation is limited to base 16 and doesn't do
1634 * width or precision and probably ignores few flags too.
1636 RTDECL(ssize_t
) RTStrFormatU512(char *pszBuf
, size_t cbBuf
, PCRTUINT512U pu512Value
, unsigned int uiBase
,
1637 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1641 * Formats an 80-bit extended floating point number.
1643 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1644 * @param pszBuf The output buffer.
1645 * @param cbBuf The size of the output buffer.
1646 * @param pr80Value The value to format.
1647 * @param cchWidth Width.
1648 * @param cchPrecision Precision.
1649 * @param fFlags Flags, RTSTR_F_XXX.
1651 RTDECL(ssize_t
) RTStrFormatR80(char *pszBuf
, size_t cbBuf
, PCRTFLOAT80U pr80Value
, signed int cchWidth
,
1652 signed int cchPrecision
, uint32_t fFlags
);
1655 * Formats an 80-bit extended floating point number, version 2.
1657 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1658 * @param pszBuf The output buffer.
1659 * @param cbBuf The size of the output buffer.
1660 * @param pr80Value The value to format.
1661 * @param cchWidth Width.
1662 * @param cchPrecision Precision.
1663 * @param fFlags Flags, RTSTR_F_XXX.
1665 RTDECL(ssize_t
) RTStrFormatR80u2(char *pszBuf
, size_t cbBuf
, PCRTFLOAT80U2 pr80Value
, signed int cchWidth
,
1666 signed int cchPrecision
, uint32_t fFlags
);
1671 * Callback for formatting a type.
1673 * This is registered using the RTStrFormatTypeRegister function and will
1674 * be called during string formatting to handle the specified %R[type].
1675 * The argument for this format type is assumed to be a pointer and it's
1676 * passed in the @a pvValue argument.
1678 * @returns Length of the formatted output.
1679 * @param pfnOutput Output worker.
1680 * @param pvArgOutput Argument to the output worker.
1681 * @param pszType The type name.
1682 * @param pvValue The argument value.
1683 * @param cchWidth Width.
1684 * @param cchPrecision Precision.
1685 * @param fFlags Flags (NTFS_*).
1686 * @param pvUser The user argument.
1688 typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
,
1689 const char *pszType
, void const *pvValue
,
1690 int cchWidth
, int cchPrecision
, unsigned fFlags
,
1692 /** Pointer to a FNRTSTRFORMATTYPE. */
1693 typedef FNRTSTRFORMATTYPE
*PFNRTSTRFORMATTYPE
;
1697 * Register a format handler for a type.
1699 * The format handler is used to handle '%R[type]' format types, where the argument
1700 * in the vector is a pointer value (a bit restrictive, but keeps it simple).
1702 * The caller must ensure that no other thread will be making use of any of
1703 * the dynamic formatting type facilities simultaneously with this call.
1705 * @returns IPRT status code.
1706 * @retval VINF_SUCCESS on success.
1707 * @retval VERR_ALREADY_EXISTS if the type has already been registered.
1708 * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
1710 * @param pszType The type name.
1711 * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
1712 * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
1713 * for how to update this later.
1715 RTDECL(int) RTStrFormatTypeRegister(const char *pszType
, PFNRTSTRFORMATTYPE pfnHandler
, void *pvUser
);
1718 * Deregisters a format type.
1720 * The caller must ensure that no other thread will be making use of any of
1721 * the dynamic formatting type facilities simultaneously with this call.
1723 * @returns IPRT status code.
1724 * @retval VINF_SUCCESS on success.
1725 * @retval VERR_FILE_NOT_FOUND if not found.
1727 * @param pszType The type to deregister.
1729 RTDECL(int) RTStrFormatTypeDeregister(const char *pszType
);
1732 * Sets the user argument for a type.
1734 * This can be used if a user argument needs relocating in GC.
1736 * @returns IPRT status code.
1737 * @retval VINF_SUCCESS on success.
1738 * @retval VERR_FILE_NOT_FOUND if not found.
1740 * @param pszType The type to update.
1741 * @param pvUser The new user argument value.
1743 RTDECL(int) RTStrFormatTypeSetUser(const char *pszType
, void *pvUser
);
1749 * @returns The length of the returned string (in pszBuffer) excluding the
1751 * @param pszBuffer Output buffer.
1752 * @param cchBuffer Size of the output buffer.
1753 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1754 * @param args The format argument.
1756 RTDECL(size_t) RTStrPrintfV(char *pszBuffer
, size_t cchBuffer
, const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(3, 0);
1761 * @returns The length of the returned string (in pszBuffer) excluding the
1763 * @param pszBuffer Output buffer.
1764 * @param cchBuffer Size of the output buffer.
1765 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1766 * @param ... The format argument.
1768 RTDECL(size_t) RTStrPrintf(char *pszBuffer
, size_t cchBuffer
, const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1772 * String printf with custom formatting.
1774 * @returns The length of the returned string (in pszBuffer) excluding the
1776 * @param pfnFormat Pointer to handler function for the custom formats.
1777 * @param pvArg Argument to the pfnFormat function.
1778 * @param pszBuffer Output buffer.
1779 * @param cchBuffer Size of the output buffer.
1780 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1781 * @param args The format argument.
1783 RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cchBuffer
,
1784 const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(5, 0);
1787 * String printf with custom formatting.
1789 * @returns The length of the returned string (in pszBuffer) excluding the
1791 * @param pfnFormat Pointer to handler function for the custom formats.
1792 * @param pvArg Argument to the pfnFormat function.
1793 * @param pszBuffer Output buffer.
1794 * @param cchBuffer Size of the output buffer.
1795 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1796 * @param ... The format argument.
1798 RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cchBuffer
,
1799 const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1803 * Allocating string printf (default tag).
1805 * @returns The length of the string in the returned *ppszBuffer excluding the
1807 * @returns -1 on failure.
1808 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1809 * The buffer should be freed using RTStrFree().
1810 * On failure *ppszBuffer will be set to NULL.
1811 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1812 * @param args The format argument.
1814 #define RTStrAPrintfV(ppszBuffer, pszFormat, args) RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
1817 * Allocating string printf (custom tag).
1819 * @returns The length of the string in the returned *ppszBuffer excluding the
1821 * @returns -1 on failure.
1822 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1823 * The buffer should be freed using RTStrFree().
1824 * On failure *ppszBuffer will be set to NULL.
1825 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1826 * @param args The format argument.
1827 * @param pszTag Allocation tag used for statistics and such.
1829 RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer
, const char *pszFormat
, va_list args
, const char *pszTag
) RT_IPRT_FORMAT_ATTR(2, 0);
1832 * Allocating string printf.
1834 * @returns The length of the string in the returned *ppszBuffer excluding the
1836 * @returns -1 on failure.
1837 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1838 * The buffer should be freed using RTStrFree().
1839 * On failure *ppszBuffer will be set to NULL.
1840 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1841 * @param ... The format argument.
1843 DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer
, const char *pszFormat
, ...)
1847 va_start(va
, pszFormat
);
1848 cbRet
= RTStrAPrintfVTag(ppszBuffer
, pszFormat
, va
, RTSTR_TAG
);
1854 * Allocating string printf (custom tag).
1856 * @returns The length of the string in the returned *ppszBuffer excluding the
1858 * @returns -1 on failure.
1859 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1860 * The buffer should be freed using RTStrFree().
1861 * On failure *ppszBuffer will be set to NULL.
1862 * @param pszTag Allocation tag used for statistics and such.
1863 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1864 * @param ... The format argument.
1866 DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer
, const char *pszTag
, const char *pszFormat
, ...)
1870 va_start(va
, pszFormat
);
1871 cbRet
= RTStrAPrintfVTag(ppszBuffer
, pszFormat
, va
, pszTag
);
1877 * Allocating string printf, version 2.
1879 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
1881 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1882 * @param args The format argument.
1884 #define RTStrAPrintf2V(pszFormat, args) RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
1887 * Allocating string printf, version 2.
1889 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
1891 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1892 * @param args The format argument.
1893 * @param pszTag Allocation tag used for statistics and such.
1895 RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat
, va_list args
, const char *pszTag
) RT_IPRT_FORMAT_ATTR(1, 0);
1898 * Allocating string printf, version 2 (default tag).
1900 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
1902 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1903 * @param ... The format argument.
1905 DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat
, ...)
1909 va_start(va
, pszFormat
);
1910 pszRet
= RTStrAPrintf2VTag(pszFormat
, va
, RTSTR_TAG
);
1916 * Allocating string printf, version 2 (custom tag).
1918 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
1920 * @param pszTag Allocation tag used for statistics and such.
1921 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1922 * @param ... The format argument.
1924 DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag
, const char *pszFormat
, ...)
1928 va_start(va
, pszFormat
);
1929 pszRet
= RTStrAPrintf2VTag(pszFormat
, va
, pszTag
);
1935 * Strips blankspaces from both ends of the string.
1937 * @returns Pointer to first non-blank char in the string.
1938 * @param psz The string to strip.
1940 RTDECL(char *) RTStrStrip(char *psz
);
1943 * Strips blankspaces from the start of the string.
1945 * @returns Pointer to first non-blank char in the string.
1946 * @param psz The string to strip.
1948 RTDECL(char *) RTStrStripL(const char *psz
);
1951 * Strips blankspaces from the end of the string.
1954 * @param psz The string to strip.
1956 RTDECL(char *) RTStrStripR(char *psz
);
1959 * String copy with overflow handling.
1961 * @retval VINF_SUCCESS on success.
1962 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
1963 * buffer will contain as much of the string as it can hold, fully
1966 * @param pszDst The destination buffer.
1967 * @param cbDst The size of the destination buffer (in bytes).
1968 * @param pszSrc The source string. NULL is not OK.
1970 RTDECL(int) RTStrCopy(char *pszDst
, size_t cbDst
, const char *pszSrc
);
1973 * String copy with overflow handling.
1975 * @retval VINF_SUCCESS on success.
1976 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
1977 * buffer will contain as much of the string as it can hold, fully
1980 * @param pszDst The destination buffer.
1981 * @param cbDst The size of the destination buffer (in bytes).
1982 * @param pszSrc The source string. NULL is not OK.
1983 * @param cchSrcMax The maximum number of chars (not code points) to
1984 * copy from the source string, not counting the
1985 * terminator as usual.
1987 RTDECL(int) RTStrCopyEx(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cchSrcMax
);
1990 * String copy with overflow handling and buffer advancing.
1992 * @retval VINF_SUCCESS on success.
1993 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
1994 * buffer will contain as much of the string as it can hold, fully
1997 * @param ppszDst Pointer to the destination buffer pointer.
1998 * This will be advanced to the end of the copied
1999 * bytes (points at the terminator). This is also
2000 * updated on overflow.
2001 * @param pcbDst Pointer to the destination buffer size
2002 * variable. This will be updated in accord with
2003 * the buffer pointer.
2004 * @param pszSrc The source string. NULL is not OK.
2006 RTDECL(int) RTStrCopyP(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
);
2009 * String copy with overflow handling.
2011 * @retval VINF_SUCCESS on success.
2012 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2013 * buffer will contain as much of the string as it can hold, fully
2016 * @param ppszDst Pointer to the destination buffer pointer.
2017 * This will be advanced to the end of the copied
2018 * bytes (points at the terminator). This is also
2019 * updated on overflow.
2020 * @param pcbDst Pointer to the destination buffer size
2021 * variable. This will be updated in accord with
2022 * the buffer pointer.
2023 * @param pszSrc The source string. NULL is not OK.
2024 * @param cchSrcMax The maximum number of chars (not code points) to
2025 * copy from the source string, not counting the
2026 * terminator as usual.
2028 RTDECL(int) RTStrCopyPEx(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
, size_t cchSrcMax
);
2031 * String concatenation with overflow handling.
2033 * @retval VINF_SUCCESS on success.
2034 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2035 * buffer will contain as much of the string as it can hold, fully
2038 * @param pszDst The destination buffer.
2039 * @param cbDst The size of the destination buffer (in bytes).
2040 * @param pszSrc The source string. NULL is not OK.
2042 RTDECL(int) RTStrCat(char *pszDst
, size_t cbDst
, const char *pszSrc
);
2045 * String concatenation with overflow handling.
2047 * @retval VINF_SUCCESS on success.
2048 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2049 * buffer will contain as much of the string as it can hold, fully
2052 * @param pszDst The destination buffer.
2053 * @param cbDst The size of the destination buffer (in bytes).
2054 * @param pszSrc The source string. NULL is not OK.
2055 * @param cchSrcMax The maximum number of chars (not code points) to
2056 * copy from the source string, not counting the
2057 * terminator as usual.
2059 RTDECL(int) RTStrCatEx(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cchSrcMax
);
2062 * String concatenation with overflow handling.
2064 * @retval VINF_SUCCESS on success.
2065 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2066 * buffer will contain as much of the string as it can hold, fully
2069 * @param ppszDst Pointer to the destination buffer pointer.
2070 * This will be advanced to the end of the copied
2071 * bytes (points at the terminator). This is also
2072 * updated on overflow.
2073 * @param pcbDst Pointer to the destination buffer size
2074 * variable. This will be updated in accord with
2075 * the buffer pointer.
2076 * @param pszSrc The source string. NULL is not OK.
2078 RTDECL(int) RTStrCatP(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
);
2081 * String concatenation with overflow handling and buffer advancing.
2083 * @retval VINF_SUCCESS on success.
2084 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2085 * buffer will contain as much of the string as it can hold, fully
2088 * @param ppszDst Pointer to the destination buffer pointer.
2089 * This will be advanced to the end of the copied
2090 * bytes (points at the terminator). This is also
2091 * updated on overflow.
2092 * @param pcbDst Pointer to the destination buffer size
2093 * variable. This will be updated in accord with
2094 * the buffer pointer.
2095 * @param pszSrc The source string. NULL is not OK.
2096 * @param cchSrcMax The maximum number of chars (not code points) to
2097 * copy from the source string, not counting the
2098 * terminator as usual.
2100 RTDECL(int) RTStrCatPEx(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
, size_t cchSrcMax
);
2103 * Performs a case sensitive string compare between two UTF-8 strings.
2105 * Encoding errors are ignored by the current implementation. So, the only
2106 * difference between this and the CRT strcmp function is the handling of
2109 * @returns < 0 if the first string less than the second string.
2110 * @returns 0 if the first string identical to the second string.
2111 * @returns > 0 if the first string greater than the second string.
2112 * @param psz1 First UTF-8 string. Null is allowed.
2113 * @param psz2 Second UTF-8 string. Null is allowed.
2115 RTDECL(int) RTStrCmp(const char *psz1
, const char *psz2
);
2118 * Performs a case sensitive string compare between two UTF-8 strings, given
2119 * a maximum string length.
2121 * Encoding errors are ignored by the current implementation. So, the only
2122 * difference between this and the CRT strncmp function is the handling of
2125 * @returns < 0 if the first string less than the second string.
2126 * @returns 0 if the first string identical to the second string.
2127 * @returns > 0 if the first string greater than the second string.
2128 * @param psz1 First UTF-8 string. Null is allowed.
2129 * @param psz2 Second UTF-8 string. Null is allowed.
2130 * @param cchMax The maximum string length
2132 RTDECL(int) RTStrNCmp(const char *psz1
, const char *psz2
, size_t cchMax
);
2135 * Performs a case insensitive string compare between two UTF-8 strings.
2137 * This is a simplified compare, as only the simplified lower/upper case folding
2138 * specified by the unicode specs are used. It does not consider character pairs
2139 * as they are used in some languages, just simple upper & lower case compares.
2141 * The result is the difference between the mismatching codepoints after they
2142 * both have been lower cased.
2144 * If the string encoding is invalid the function will assert (strict builds)
2145 * and use RTStrCmp for the remainder of the string.
2147 * @returns < 0 if the first string less than the second string.
2148 * @returns 0 if the first string identical to the second string.
2149 * @returns > 0 if the first string greater than the second string.
2150 * @param psz1 First UTF-8 string. Null is allowed.
2151 * @param psz2 Second UTF-8 string. Null is allowed.
2153 RTDECL(int) RTStrICmp(const char *psz1
, const char *psz2
);
2156 * Performs a case insensitive string compare between two UTF-8 strings, given a
2157 * maximum string length.
2159 * This is a simplified compare, as only the simplified lower/upper case folding
2160 * specified by the unicode specs are used. It does not consider character pairs
2161 * as they are used in some languages, just simple upper & lower case compares.
2163 * The result is the difference between the mismatching codepoints after they
2164 * both have been lower cased.
2166 * If the string encoding is invalid the function will assert (strict builds)
2167 * and use RTStrCmp for the remainder of the string.
2169 * @returns < 0 if the first string less than the second string.
2170 * @returns 0 if the first string identical to the second string.
2171 * @returns > 0 if the first string greater than the second string.
2172 * @param psz1 First UTF-8 string. Null is allowed.
2173 * @param psz2 Second UTF-8 string. Null is allowed.
2174 * @param cchMax Maximum string length
2176 RTDECL(int) RTStrNICmp(const char *psz1
, const char *psz2
, size_t cchMax
);
2179 * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
2182 * This is potentially faster than RTStrICmp and drags in less dependencies. It
2183 * is really handy for hardcoded inputs.
2185 * If the string encoding is invalid the function will assert (strict builds)
2186 * and use RTStrCmp for the remainder of the string.
2188 * @returns < 0 if the first string less than the second string.
2189 * @returns 0 if the first string identical to the second string.
2190 * @returns > 0 if the first string greater than the second string.
2191 * @param psz1 First UTF-8 string. Null is allowed.
2192 * @param psz2 Second string, 7-bit ASCII. Null is allowed.
2193 * @sa RTUtf16ICmpAscii
2195 RTDECL(int) RTStrICmpAscii(const char *psz1
, const char *psz2
);
2198 * Checks whether @a pszString starts with @a pszStart.
2200 * @returns true / false.
2201 * @param pszString The string to check.
2202 * @param pszStart The start string to check for.
2204 RTDECL(int) RTStrStartsWith(const char *pszString
, const char *pszStart
);
2207 * Checks whether @a pszString starts with @a pszStart, case insensitive.
2209 * @returns true / false.
2210 * @param pszString The string to check.
2211 * @param pszStart The start string to check for.
2213 RTDECL(int) RTStrIStartsWith(const char *pszString
, const char *pszStart
);
2216 * Locates a case sensitive substring.
2218 * If any of the two strings are NULL, then NULL is returned. If the needle is
2219 * an empty string, then the haystack is returned (i.e. matches anything).
2221 * @returns Pointer to the first occurrence of the substring if found, NULL if
2224 * @param pszHaystack The string to search.
2225 * @param pszNeedle The substring to search for.
2227 * @remarks The difference between this and strstr is the handling of NULL
2230 RTDECL(char *) RTStrStr(const char *pszHaystack
, const char *pszNeedle
);
2233 * Locates a case insensitive substring.
2235 * If any of the two strings are NULL, then NULL is returned. If the needle is
2236 * an empty string, then the haystack is returned (i.e. matches anything).
2238 * @returns Pointer to the first occurrence of the substring if found, NULL if
2241 * @param pszHaystack The string to search.
2242 * @param pszNeedle The substring to search for.
2245 RTDECL(char *) RTStrIStr(const char *pszHaystack
, const char *pszNeedle
);
2248 * Converts the string to lower case.
2250 * @returns Pointer to the converted string.
2251 * @param psz The string to convert.
2253 RTDECL(char *) RTStrToLower(char *psz
);
2256 * Converts the string to upper case.
2258 * @returns Pointer to the converted string.
2259 * @param psz The string to convert.
2261 RTDECL(char *) RTStrToUpper(char *psz
);
2264 * Checks if the string is case foldable, i.e. whether it would change if
2265 * subject to RTStrToLower or RTStrToUpper.
2267 * @returns true / false
2268 * @param psz The string in question.
2270 RTDECL(bool) RTStrIsCaseFoldable(const char *psz
);
2273 * Checks if the string is upper cased (no lower case chars in it).
2275 * @returns true / false
2276 * @param psz The string in question.
2278 RTDECL(bool) RTStrIsUpperCased(const char *psz
);
2281 * Checks if the string is lower cased (no upper case chars in it).
2283 * @returns true / false
2284 * @param psz The string in question.
2286 RTDECL(bool) RTStrIsLowerCased(const char *psz
);
2289 * Find the length of a zero-terminated byte string, given
2290 * a max string length.
2292 * See also RTStrNLenEx.
2294 * @returns The string length or cbMax. The returned length does not include
2295 * the zero terminator if it was found.
2297 * @param pszString The string.
2298 * @param cchMax The max string length.
2300 RTDECL(size_t) RTStrNLen(const char *pszString
, size_t cchMax
);
2303 * Find the length of a zero-terminated byte string, given
2304 * a max string length.
2306 * See also RTStrNLen.
2308 * @returns IPRT status code.
2309 * @retval VINF_SUCCESS if the string has a length less than cchMax.
2310 * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
2311 * before cchMax was reached.
2313 * @param pszString The string.
2314 * @param cchMax The max string length.
2315 * @param pcch Where to store the string length excluding the
2316 * terminator. This is set to cchMax if the terminator
2319 RTDECL(int) RTStrNLenEx(const char *pszString
, size_t cchMax
, size_t *pcch
);
2323 /** The maximum size argument of a memchr call. */
2324 #define RTSTR_MEMCHR_MAX ((~(size_t)0 >> 1) - 15)
2327 * Find the zero terminator in a string with a limited length.
2329 * @returns Pointer to the zero terminator.
2330 * @returns NULL if the zero terminator was not found.
2332 * @param pszString The string.
2333 * @param cchMax The max string length. RTSTR_MAX is fine.
2335 #if defined(__cplusplus) && !defined(DOXYGEN_RUNNING)
2336 DECLINLINE(char const *) RTStrEnd(char const *pszString
, size_t cchMax
)
2338 /* Avoid potential issues with memchr seen in glibc.
2339 * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
2340 while (cchMax
> RTSTR_MEMCHR_MAX
)
2342 char const *pszRet
= (char const *)memchr(pszString
, '\0', RTSTR_MEMCHR_MAX
);
2343 if (RT_LIKELY(pszRet
))
2345 pszString
+= RTSTR_MEMCHR_MAX
;
2346 cchMax
-= RTSTR_MEMCHR_MAX
;
2348 return (char const *)memchr(pszString
, '\0', cchMax
);
2351 DECLINLINE(char *) RTStrEnd(char *pszString
, size_t cchMax
)
2353 DECLINLINE(char *) RTStrEnd(const char *pszString
, size_t cchMax
)
2356 /* Avoid potential issues with memchr seen in glibc.
2357 * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
2358 while (cchMax
> RTSTR_MEMCHR_MAX
)
2360 char *pszRet
= (char *)memchr(pszString
, '\0', RTSTR_MEMCHR_MAX
);
2361 if (RT_LIKELY(pszRet
))
2363 pszString
+= RTSTR_MEMCHR_MAX
;
2364 cchMax
-= RTSTR_MEMCHR_MAX
;
2366 return (char *)memchr(pszString
, '\0', cchMax
);
2372 * Finds the offset at which a simple character first occurs in a string.
2374 * @returns The offset of the first occurence or the terminator offset.
2375 * @param pszHaystack The string to search.
2376 * @param chNeedle The character to search for.
2378 DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack
, char chNeedle
)
2380 const char *psz
= pszHaystack
;
2382 while ( (ch
= *psz
) != chNeedle
2385 return psz
- pszHaystack
;
2390 * Matches a simple string pattern.
2392 * @returns true if the string matches the pattern, otherwise false.
2394 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2395 * asterisk matches zero or more characters and question
2396 * mark matches exactly one character.
2397 * @param pszString The string to match against the pattern.
2399 RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern
, const char *pszString
);
2402 * Matches a simple string pattern, neither which needs to be zero terminated.
2404 * This is identical to RTStrSimplePatternMatch except that you can optionally
2405 * specify the length of both the pattern and the string. The function will
2406 * stop when it hits a string terminator or either of the lengths.
2408 * @returns true if the string matches the pattern, otherwise false.
2410 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2411 * asterisk matches zero or more characters and question
2412 * mark matches exactly one character.
2413 * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
2414 * length and wish to stop at the string terminator.
2415 * @param pszString The string to match against the pattern.
2416 * @param cchString The string length. Pass RTSTR_MAX if you don't know the
2417 * length and wish to match up to the string terminator.
2419 RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern
, size_t cchPattern
,
2420 const char *pszString
, size_t cchString
);
2423 * Matches multiple patterns against a string.
2425 * The patterns are separated by the pipe character (|).
2427 * @returns true if the string matches the pattern, otherwise false.
2429 * @param pszPatterns The patterns.
2430 * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
2431 * stop at the terminator.
2432 * @param pszString The string to match against the pattern.
2433 * @param cchString The string length. Pass RTSTR_MAX stop stop at the
2435 * @param poffPattern Offset into the patterns string of the patttern that
2436 * matched. If no match, this will be set to RTSTR_MAX.
2437 * This is optional, NULL is fine.
2439 RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns
, size_t cchPatterns
,
2440 const char *pszString
, size_t cchString
,
2441 size_t *poffPattern
);
2444 * Compares two version strings RTStrICmp fashion.
2446 * The version string is split up into sections at punctuation, spaces,
2447 * underscores, dashes and plus signs. The sections are then split up into
2448 * numeric and string sub-sections. Finally, the sub-sections are compared
2449 * in a numeric or case insesntivie fashion depending on what they are.
2451 * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
2452 * "1". These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
2454 * @returns < 0 if the first string less than the second string.
2455 * @returns 0 if the first string identical to the second string.
2456 * @returns > 0 if the first string greater than the second string.
2458 * @param pszVer1 First version string to compare.
2459 * @param pszVer2 Second version string to compare first version with.
2461 RTDECL(int) RTStrVersionCompare(const char *pszVer1
, const char *pszVer2
);
2464 /** @defgroup rt_str_conv String To/From Number Conversions
2468 * Converts a string representation of a number to a 64-bit unsigned number.
2470 * @returns iprt status code.
2471 * Warnings are used to indicate conversion problems.
2472 * @retval VWRN_NUMBER_TOO_BIG
2473 * @retval VWRN_NEGATIVE_UNSIGNED
2474 * @retval VWRN_TRAILING_CHARS
2475 * @retval VWRN_TRAILING_SPACES
2476 * @retval VINF_SUCCESS
2477 * @retval VERR_NO_DIGITS
2479 * @param pszValue Pointer to the string value.
2480 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2481 * @param uBase The base of the representation used.
2482 * If 0 the function will look for known prefixes before defaulting to 10.
2483 * @param pu64 Where to store the converted number. (optional)
2485 RTDECL(int) RTStrToUInt64Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint64_t *pu64
);
2488 * Converts a string representation of a number to a 64-bit unsigned number,
2489 * making sure the full string is converted.
2491 * @returns iprt status code.
2492 * Warnings are used to indicate conversion problems.
2493 * @retval VWRN_NUMBER_TOO_BIG
2494 * @retval VWRN_NEGATIVE_UNSIGNED
2495 * @retval VINF_SUCCESS
2496 * @retval VERR_NO_DIGITS
2497 * @retval VERR_TRAILING_SPACES
2498 * @retval VERR_TRAILING_CHARS
2500 * @param pszValue Pointer to the string value.
2501 * @param uBase The base of the representation used.
2502 * If 0 the function will look for known prefixes before defaulting to 10.
2503 * @param pu64 Where to store the converted number. (optional)
2505 RTDECL(int) RTStrToUInt64Full(const char *pszValue
, unsigned uBase
, uint64_t *pu64
);
2508 * Converts a string representation of a number to a 64-bit unsigned number.
2509 * The base is guessed.
2511 * @returns 64-bit unsigned number on success.
2512 * @returns 0 on failure.
2513 * @param pszValue Pointer to the string value.
2515 RTDECL(uint64_t) RTStrToUInt64(const char *pszValue
);
2518 * Converts a string representation of a number to a 32-bit unsigned number.
2520 * @returns iprt status code.
2521 * Warnings are used to indicate conversion problems.
2522 * @retval VWRN_NUMBER_TOO_BIG
2523 * @retval VWRN_NEGATIVE_UNSIGNED
2524 * @retval VWRN_TRAILING_CHARS
2525 * @retval VWRN_TRAILING_SPACES
2526 * @retval VINF_SUCCESS
2527 * @retval VERR_NO_DIGITS
2529 * @param pszValue Pointer to the string value.
2530 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2531 * @param uBase The base of the representation used.
2532 * If 0 the function will look for known prefixes before defaulting to 10.
2533 * @param pu32 Where to store the converted number. (optional)
2535 RTDECL(int) RTStrToUInt32Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint32_t *pu32
);
2538 * Converts a string representation of a number to a 32-bit unsigned number,
2539 * making sure the full string is converted.
2541 * @returns iprt status code.
2542 * Warnings are used to indicate conversion problems.
2543 * @retval VWRN_NUMBER_TOO_BIG
2544 * @retval VWRN_NEGATIVE_UNSIGNED
2545 * @retval VINF_SUCCESS
2546 * @retval VERR_NO_DIGITS
2547 * @retval VERR_TRAILING_SPACES
2548 * @retval VERR_TRAILING_CHARS
2550 * @param pszValue Pointer to the string value.
2551 * @param uBase The base of the representation used.
2552 * If 0 the function will look for known prefixes before defaulting to 10.
2553 * @param pu32 Where to store the converted number. (optional)
2555 RTDECL(int) RTStrToUInt32Full(const char *pszValue
, unsigned uBase
, uint32_t *pu32
);
2558 * Converts a string representation of a number to a 64-bit unsigned number.
2559 * The base is guessed.
2561 * @returns 32-bit unsigned number on success.
2562 * @returns 0 on failure.
2563 * @param pszValue Pointer to the string value.
2565 RTDECL(uint32_t) RTStrToUInt32(const char *pszValue
);
2568 * Converts a string representation of a number to a 16-bit unsigned number.
2570 * @returns iprt status code.
2571 * Warnings are used to indicate conversion problems.
2572 * @retval VWRN_NUMBER_TOO_BIG
2573 * @retval VWRN_NEGATIVE_UNSIGNED
2574 * @retval VWRN_TRAILING_CHARS
2575 * @retval VWRN_TRAILING_SPACES
2576 * @retval VINF_SUCCESS
2577 * @retval VERR_NO_DIGITS
2579 * @param pszValue Pointer to the string value.
2580 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2581 * @param uBase The base of the representation used.
2582 * If 0 the function will look for known prefixes before defaulting to 10.
2583 * @param pu16 Where to store the converted number. (optional)
2585 RTDECL(int) RTStrToUInt16Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint16_t *pu16
);
2588 * Converts a string representation of a number to a 16-bit unsigned number,
2589 * making sure the full string is converted.
2591 * @returns iprt status code.
2592 * Warnings are used to indicate conversion problems.
2593 * @retval VWRN_NUMBER_TOO_BIG
2594 * @retval VWRN_NEGATIVE_UNSIGNED
2595 * @retval VINF_SUCCESS
2596 * @retval VERR_NO_DIGITS
2597 * @retval VERR_TRAILING_SPACES
2598 * @retval VERR_TRAILING_CHARS
2600 * @param pszValue Pointer to the string value.
2601 * @param uBase The base of the representation used.
2602 * If 0 the function will look for known prefixes before defaulting to 10.
2603 * @param pu16 Where to store the converted number. (optional)
2605 RTDECL(int) RTStrToUInt16Full(const char *pszValue
, unsigned uBase
, uint16_t *pu16
);
2608 * Converts a string representation of a number to a 16-bit unsigned number.
2609 * The base is guessed.
2611 * @returns 16-bit unsigned number on success.
2612 * @returns 0 on failure.
2613 * @param pszValue Pointer to the string value.
2615 RTDECL(uint16_t) RTStrToUInt16(const char *pszValue
);
2618 * Converts a string representation of a number to a 8-bit unsigned number.
2620 * @returns iprt status code.
2621 * Warnings are used to indicate conversion problems.
2622 * @retval VWRN_NUMBER_TOO_BIG
2623 * @retval VWRN_NEGATIVE_UNSIGNED
2624 * @retval VWRN_TRAILING_CHARS
2625 * @retval VWRN_TRAILING_SPACES
2626 * @retval VINF_SUCCESS
2627 * @retval VERR_NO_DIGITS
2629 * @param pszValue Pointer to the string value.
2630 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2631 * @param uBase The base of the representation used.
2632 * If 0 the function will look for known prefixes before defaulting to 10.
2633 * @param pu8 Where to store the converted number. (optional)
2635 RTDECL(int) RTStrToUInt8Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint8_t *pu8
);
2638 * Converts a string representation of a number to a 8-bit unsigned number,
2639 * making sure the full string is converted.
2641 * @returns iprt status code.
2642 * Warnings are used to indicate conversion problems.
2643 * @retval VWRN_NUMBER_TOO_BIG
2644 * @retval VWRN_NEGATIVE_UNSIGNED
2645 * @retval VINF_SUCCESS
2646 * @retval VERR_NO_DIGITS
2647 * @retval VERR_TRAILING_SPACES
2648 * @retval VERR_TRAILING_CHARS
2650 * @param pszValue Pointer to the string value.
2651 * @param uBase The base of the representation used.
2652 * If 0 the function will look for known prefixes before defaulting to 10.
2653 * @param pu8 Where to store the converted number. (optional)
2655 RTDECL(int) RTStrToUInt8Full(const char *pszValue
, unsigned uBase
, uint8_t *pu8
);
2658 * Converts a string representation of a number to a 8-bit unsigned number.
2659 * The base is guessed.
2661 * @returns 8-bit unsigned number on success.
2662 * @returns 0 on failure.
2663 * @param pszValue Pointer to the string value.
2665 RTDECL(uint8_t) RTStrToUInt8(const char *pszValue
);
2668 * Converts a string representation of a number to a 64-bit signed number.
2670 * @returns iprt status code.
2671 * Warnings are used to indicate conversion problems.
2672 * @retval VWRN_NUMBER_TOO_BIG
2673 * @retval VWRN_TRAILING_CHARS
2674 * @retval VWRN_TRAILING_SPACES
2675 * @retval VINF_SUCCESS
2676 * @retval VERR_NO_DIGITS
2678 * @param pszValue Pointer to the string value.
2679 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2680 * @param uBase The base of the representation used.
2681 * If 0 the function will look for known prefixes before defaulting to 10.
2682 * @param pi64 Where to store the converted number. (optional)
2684 RTDECL(int) RTStrToInt64Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int64_t *pi64
);
2687 * Converts a string representation of a number to a 64-bit signed number,
2688 * making sure the full string is converted.
2690 * @returns iprt status code.
2691 * Warnings are used to indicate conversion problems.
2692 * @retval VWRN_NUMBER_TOO_BIG
2693 * @retval VINF_SUCCESS
2694 * @retval VERR_TRAILING_CHARS
2695 * @retval VERR_TRAILING_SPACES
2696 * @retval VERR_NO_DIGITS
2698 * @param pszValue Pointer to the string value.
2699 * @param uBase The base of the representation used.
2700 * If 0 the function will look for known prefixes before defaulting to 10.
2701 * @param pi64 Where to store the converted number. (optional)
2703 RTDECL(int) RTStrToInt64Full(const char *pszValue
, unsigned uBase
, int64_t *pi64
);
2706 * Converts a string representation of a number to a 64-bit signed number.
2707 * The base is guessed.
2709 * @returns 64-bit signed number on success.
2710 * @returns 0 on failure.
2711 * @param pszValue Pointer to the string value.
2713 RTDECL(int64_t) RTStrToInt64(const char *pszValue
);
2716 * Converts a string representation of a number to a 32-bit signed number.
2718 * @returns iprt status code.
2719 * Warnings are used to indicate conversion problems.
2720 * @retval VWRN_NUMBER_TOO_BIG
2721 * @retval VWRN_TRAILING_CHARS
2722 * @retval VWRN_TRAILING_SPACES
2723 * @retval VINF_SUCCESS
2724 * @retval VERR_NO_DIGITS
2726 * @param pszValue Pointer to the string value.
2727 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2728 * @param uBase The base of the representation used.
2729 * If 0 the function will look for known prefixes before defaulting to 10.
2730 * @param pi32 Where to store the converted number. (optional)
2732 RTDECL(int) RTStrToInt32Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int32_t *pi32
);
2735 * Converts a string representation of a number to a 32-bit signed number,
2736 * making sure the full string is converted.
2738 * @returns iprt status code.
2739 * Warnings are used to indicate conversion problems.
2740 * @retval VWRN_NUMBER_TOO_BIG
2741 * @retval VINF_SUCCESS
2742 * @retval VERR_TRAILING_CHARS
2743 * @retval VERR_TRAILING_SPACES
2744 * @retval VERR_NO_DIGITS
2746 * @param pszValue Pointer to the string value.
2747 * @param uBase The base of the representation used.
2748 * If 0 the function will look for known prefixes before defaulting to 10.
2749 * @param pi32 Where to store the converted number. (optional)
2751 RTDECL(int) RTStrToInt32Full(const char *pszValue
, unsigned uBase
, int32_t *pi32
);
2754 * Converts a string representation of a number to a 32-bit signed number.
2755 * The base is guessed.
2757 * @returns 32-bit signed number on success.
2758 * @returns 0 on failure.
2759 * @param pszValue Pointer to the string value.
2761 RTDECL(int32_t) RTStrToInt32(const char *pszValue
);
2764 * Converts a string representation of a number to a 16-bit signed number.
2766 * @returns iprt status code.
2767 * Warnings are used to indicate conversion problems.
2768 * @retval VWRN_NUMBER_TOO_BIG
2769 * @retval VWRN_TRAILING_CHARS
2770 * @retval VWRN_TRAILING_SPACES
2771 * @retval VINF_SUCCESS
2772 * @retval VERR_NO_DIGITS
2774 * @param pszValue Pointer to the string value.
2775 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2776 * @param uBase The base of the representation used.
2777 * If 0 the function will look for known prefixes before defaulting to 10.
2778 * @param pi16 Where to store the converted number. (optional)
2780 RTDECL(int) RTStrToInt16Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int16_t *pi16
);
2783 * Converts a string representation of a number to a 16-bit signed number,
2784 * making sure the full string is converted.
2786 * @returns iprt status code.
2787 * Warnings are used to indicate conversion problems.
2788 * @retval VWRN_NUMBER_TOO_BIG
2789 * @retval VINF_SUCCESS
2790 * @retval VERR_TRAILING_CHARS
2791 * @retval VERR_TRAILING_SPACES
2792 * @retval VERR_NO_DIGITS
2794 * @param pszValue Pointer to the string value.
2795 * @param uBase The base of the representation used.
2796 * If 0 the function will look for known prefixes before defaulting to 10.
2797 * @param pi16 Where to store the converted number. (optional)
2799 RTDECL(int) RTStrToInt16Full(const char *pszValue
, unsigned uBase
, int16_t *pi16
);
2802 * Converts a string representation of a number to a 16-bit signed number.
2803 * The base is guessed.
2805 * @returns 16-bit signed number on success.
2806 * @returns 0 on failure.
2807 * @param pszValue Pointer to the string value.
2809 RTDECL(int16_t) RTStrToInt16(const char *pszValue
);
2812 * Converts a string representation of a number to a 8-bit signed number.
2814 * @returns iprt status code.
2815 * Warnings are used to indicate conversion problems.
2816 * @retval VWRN_NUMBER_TOO_BIG
2817 * @retval VWRN_TRAILING_CHARS
2818 * @retval VWRN_TRAILING_SPACES
2819 * @retval VINF_SUCCESS
2820 * @retval VERR_NO_DIGITS
2822 * @param pszValue Pointer to the string value.
2823 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2824 * @param uBase The base of the representation used.
2825 * If 0 the function will look for known prefixes before defaulting to 10.
2826 * @param pi8 Where to store the converted number. (optional)
2828 RTDECL(int) RTStrToInt8Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int8_t *pi8
);
2831 * Converts a string representation of a number to a 8-bit signed number,
2832 * making sure the full string is converted.
2834 * @returns iprt status code.
2835 * Warnings are used to indicate conversion problems.
2836 * @retval VWRN_NUMBER_TOO_BIG
2837 * @retval VINF_SUCCESS
2838 * @retval VERR_TRAILING_CHARS
2839 * @retval VERR_TRAILING_SPACES
2840 * @retval VERR_NO_DIGITS
2842 * @param pszValue Pointer to the string value.
2843 * @param uBase The base of the representation used.
2844 * If 0 the function will look for known prefixes before defaulting to 10.
2845 * @param pi8 Where to store the converted number. (optional)
2847 RTDECL(int) RTStrToInt8Full(const char *pszValue
, unsigned uBase
, int8_t *pi8
);
2850 * Converts a string representation of a number to a 8-bit signed number.
2851 * The base is guessed.
2853 * @returns 8-bit signed number on success.
2854 * @returns 0 on failure.
2855 * @param pszValue Pointer to the string value.
2857 RTDECL(int8_t) RTStrToInt8(const char *pszValue
);
2860 * Formats a buffer stream as hex bytes.
2862 * The default is no separating spaces or line breaks or anything.
2864 * @returns IPRT status code.
2865 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
2866 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
2868 * @param pszBuf Output string buffer.
2869 * @param cbBuf The size of the output buffer.
2870 * @param pv Pointer to the bytes to stringify.
2871 * @param cb The number of bytes to stringify.
2872 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
2873 * @sa RTUtf16PrintHexBytes.
2875 RTDECL(int) RTStrPrintHexBytes(char *pszBuf
, size_t cbBuf
, void const *pv
, size_t cb
, uint32_t fFlags
);
2876 /** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
2878 /** Upper case hex digits, the default is lower case. */
2879 #define RTSTRPRINTHEXBYTES_F_UPPER RT_BIT(0)
2880 /** Add a space between each group. */
2881 #define RTSTRPRINTHEXBYTES_F_SEP_SPACE RT_BIT(1)
2882 /** Add a colon between each group. */
2883 #define RTSTRPRINTHEXBYTES_F_SEP_COLON RT_BIT(2)
2887 * Converts a string of hex bytes back into binary data.
2889 * @returns IPRT status code.
2890 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
2891 * @retval VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
2892 * @retval VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
2893 * the output buffer.
2894 * @retval VERR_UNEVEN_INPUT if the input contains a half byte.
2895 * @retval VERR_NO_DIGITS
2896 * @retval VWRN_TRAILING_CHARS
2897 * @retval VWRN_TRAILING_SPACES
2899 * @param pszHex The string containing the hex bytes.
2900 * @param pv Output buffer.
2901 * @param cb The size of the output buffer.
2902 * @param fFlags Must be zero, reserved for future use.
2904 RTDECL(int) RTStrConvertHexBytes(char const *pszHex
, void *pv
, size_t cb
, uint32_t fFlags
);
2909 /** @defgroup rt_str_space Unique String Space
2913 /** Pointer to a string name space container node core. */
2914 typedef struct RTSTRSPACECORE
*PRTSTRSPACECORE
;
2915 /** Pointer to a pointer to a string name space container node core. */
2916 typedef PRTSTRSPACECORE
*PPRTSTRSPACECORE
;
2919 * String name space container node core.
2921 typedef struct RTSTRSPACECORE
2923 /** Hash key. Don't touch. */
2925 /** Pointer to the left leaf node. Don't touch. */
2926 PRTSTRSPACECORE pLeft
;
2927 /** Pointer to the left right node. Don't touch. */
2928 PRTSTRSPACECORE pRight
;
2929 /** Pointer to the list of string with the same key. Don't touch. */
2930 PRTSTRSPACECORE pList
;
2931 /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
2932 unsigned char uchHeight
;
2933 /** The string length. Read only! */
2935 /** Pointer to the string. Read only! */
2936 const char *pszString
;
2939 /** String space. (Initialize with NULL.) */
2940 typedef PRTSTRSPACECORE RTSTRSPACE
;
2941 /** Pointer to a string space. */
2942 typedef PPRTSTRSPACECORE PRTSTRSPACE
;
2946 * Inserts a string into a unique string space.
2948 * @returns true on success.
2949 * @returns false if the string collided with an existing string.
2950 * @param pStrSpace The space to insert it into.
2951 * @param pStr The string node.
2953 RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace
, PRTSTRSPACECORE pStr
);
2956 * Removes a string from a unique string space.
2958 * @returns Pointer to the removed string node.
2959 * @returns NULL if the string was not found in the string space.
2960 * @param pStrSpace The space to remove it from.
2961 * @param pszString The string to remove.
2963 RTDECL(PRTSTRSPACECORE
) RTStrSpaceRemove(PRTSTRSPACE pStrSpace
, const char *pszString
);
2966 * Gets a string from a unique string space.
2968 * @returns Pointer to the string node.
2969 * @returns NULL if the string was not found in the string space.
2970 * @param pStrSpace The space to get it from.
2971 * @param pszString The string to get.
2973 RTDECL(PRTSTRSPACECORE
) RTStrSpaceGet(PRTSTRSPACE pStrSpace
, const char *pszString
);
2976 * Gets a string from a unique string space.
2978 * @returns Pointer to the string node.
2979 * @returns NULL if the string was not found in the string space.
2980 * @param pStrSpace The space to get it from.
2981 * @param pszString The string to get.
2982 * @param cchMax The max string length to evaluate. Passing
2983 * RTSTR_MAX is ok and makes it behave just like
2986 RTDECL(PRTSTRSPACECORE
) RTStrSpaceGetN(PRTSTRSPACE pStrSpace
, const char *pszString
, size_t cchMax
);
2989 * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
2991 * @returns 0 on continue.
2992 * @returns Non-zero to aborts the operation.
2993 * @param pStr The string node
2994 * @param pvUser The user specified argument.
2996 typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr
, void *pvUser
);
2997 /** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
2998 typedef FNRTSTRSPACECALLBACK
*PFNRTSTRSPACECALLBACK
;
3001 * Destroys the string space.
3003 * The caller supplies a callback which will be called for each of the string
3004 * nodes in for freeing their memory and other resources.
3006 * @returns 0 or what ever non-zero return value pfnCallback returned
3007 * when aborting the destruction.
3008 * @param pStrSpace The space to destroy.
3009 * @param pfnCallback The callback.
3010 * @param pvUser The user argument.
3012 RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace
, PFNRTSTRSPACECALLBACK pfnCallback
, void *pvUser
);
3015 * Enumerates the string space.
3016 * The caller supplies a callback which will be called for each of
3019 * @returns 0 or what ever non-zero return value pfnCallback returned
3020 * when aborting the destruction.
3021 * @param pStrSpace The space to enumerate.
3022 * @param pfnCallback The callback.
3023 * @param pvUser The user argument.
3025 RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace
, PFNRTSTRSPACECALLBACK pfnCallback
, void *pvUser
);
3030 /** @defgroup rt_str_hash Sting hashing
3034 * Hashes the given string using algorithm \#1.
3036 * @returns String hash.
3037 * @param pszString The string to hash.
3039 RTDECL(uint32_t) RTStrHash1(const char *pszString
);
3042 * Hashes the given string using algorithm \#1.
3044 * @returns String hash.
3045 * @param pszString The string to hash.
3046 * @param cchString The max length to hash. Hashing will stop if the
3047 * terminator character is encountered first. Passing
3048 * RTSTR_MAX is fine.
3050 RTDECL(uint32_t) RTStrHash1N(const char *pszString
, size_t cchString
);
3053 * Hashes the given strings as if they were concatenated using algorithm \#1.
3055 * @returns String hash.
3056 * @param cPairs The number of string / length pairs in the
3058 * @param ... List of string (const char *) and length
3059 * (size_t) pairs. Passing RTSTR_MAX as the size is
3062 RTDECL(uint32_t) RTStrHash1ExN(size_t cPairs
, ...);
3065 * Hashes the given strings as if they were concatenated using algorithm \#1.
3067 * @returns String hash.
3068 * @param cPairs The number of string / length pairs in the @a va.
3069 * @param va List of string (const char *) and length
3070 * (size_t) pairs. Passing RTSTR_MAX as the size is
3073 RTDECL(uint32_t) RTStrHash1ExNV(size_t cPairs
, va_list va
);