2 * IPRT - String Manipulation.
6 * Copyright (C) 2006-2017 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 * This differs from RTStrToUtf16 in that it always produces a
832 * @returns iprt status code.
833 * @param pszString UTF-8 string to convert.
834 * @param ppwszString Receives pointer to the allocated UTF-16 string.
835 * The returned string must be freed using RTUtf16Free().
836 * @param pszTag Allocation tag used for statistics and such.
838 RTDECL(int) RTStrToUtf16Tag(const char *pszString
, PRTUTF16
*ppwszString
, const char *pszTag
);
841 * Translate a UTF-8 string into a UTF-16BE allocating the result buffer
844 * This differs from RTStrToUtf16Tag in that it always produces a
847 * @returns iprt status code.
848 * @param pszString UTF-8 string to convert.
849 * @param ppwszString Receives pointer to the allocated UTF-16BE string.
850 * The returned string must be freed using RTUtf16Free().
852 #define RTStrToUtf16Big(pszString, ppwszString) RTStrToUtf16BigTag((pszString), (ppwszString), RTSTR_TAG)
855 * Translate a UTF-8 string into a UTF-16BE allocating the result buffer (custom
858 * @returns iprt status code.
859 * @param pszString UTF-8 string to convert.
860 * @param ppwszString Receives pointer to the allocated UTF-16BE string.
861 * The returned string must be freed using RTUtf16Free().
862 * @param pszTag Allocation tag used for statistics and such.
864 RTDECL(int) RTStrToUtf16BigTag(const char *pszString
, PRTUTF16
*ppwszString
, const char *pszTag
);
867 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
869 * @returns iprt status code.
870 * @param pszString UTF-8 string to convert.
871 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
872 * when it reaches cchString or the string terminator ('\\0').
873 * Use RTSTR_MAX to translate the entire string.
874 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
875 * a buffer of the specified size, or pointer to a NULL pointer.
876 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
877 * will be allocated to hold the translated string.
878 * If a buffer was requested it must be freed using RTUtf16Free().
879 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
880 * @param pcwc Where to store the length of the translated string,
881 * excluding the terminator. (Optional)
883 * This may be set under some error conditions,
884 * however, only for VERR_BUFFER_OVERFLOW and
885 * VERR_NO_STR_MEMORY will it contain a valid string
886 * length that can be used to resize the buffer.
888 #define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
889 RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
892 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
893 * requested (custom tag).
895 * @returns iprt status code.
896 * @param pszString UTF-8 string to convert.
897 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
898 * when it reaches cchString or the string terminator ('\\0').
899 * Use RTSTR_MAX to translate the entire string.
900 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
901 * a buffer of the specified size, or pointer to a NULL pointer.
902 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
903 * will be allocated to hold the translated string.
904 * If a buffer was requested it must be freed using RTUtf16Free().
905 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
906 * @param pcwc Where to store the length of the translated string,
907 * excluding the terminator. (Optional)
909 * This may be set under some error conditions,
910 * however, only for VERR_BUFFER_OVERFLOW and
911 * VERR_NO_STR_MEMORY will it contain a valid string
912 * length that can be used to resize the buffer.
913 * @param pszTag Allocation tag used for statistics and such.
915 RTDECL(int) RTStrToUtf16ExTag(const char *pszString
, size_t cchString
,
916 PRTUTF16
*ppwsz
, size_t cwc
, size_t *pcwc
, const char *pszTag
);
920 * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if requested.
922 * This differs from RTStrToUtf16Ex in that it always produces a
925 * @returns iprt status code.
926 * @param pszString UTF-8 string to convert.
927 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
928 * when it reaches cchString or the string terminator ('\\0').
929 * Use RTSTR_MAX to translate the entire string.
930 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
931 * a buffer of the specified size, or pointer to a NULL pointer.
932 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
933 * will be allocated to hold the translated string.
934 * If a buffer was requested it must be freed using RTUtf16Free().
935 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
936 * @param pcwc Where to store the length of the translated string,
937 * excluding the terminator. (Optional)
939 * This may be set under some error conditions,
940 * however, only for VERR_BUFFER_OVERFLOW and
941 * VERR_NO_STR_MEMORY will it contain a valid string
942 * length that can be used to resize the buffer.
944 #define RTStrToUtf16BigEx(pszString, cchString, ppwsz, cwc, pcwc) \
945 RTStrToUtf16BigExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
948 * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if
949 * requested (custom tag).
951 * This differs from RTStrToUtf16ExTag in that it always produces a
954 * @returns iprt status code.
955 * @param pszString UTF-8 string to convert.
956 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
957 * when it reaches cchString or the string terminator ('\\0').
958 * Use RTSTR_MAX to translate the entire string.
959 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
960 * a buffer of the specified size, or pointer to a NULL pointer.
961 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
962 * will be allocated to hold the translated string.
963 * If a buffer was requested it must be freed using RTUtf16Free().
964 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
965 * @param pcwc Where to store the length of the translated string,
966 * excluding the terminator. (Optional)
968 * This may be set under some error conditions,
969 * however, only for VERR_BUFFER_OVERFLOW and
970 * VERR_NO_STR_MEMORY will it contain a valid string
971 * length that can be used to resize the buffer.
972 * @param pszTag Allocation tag used for statistics and such.
974 RTDECL(int) RTStrToUtf16BigExTag(const char *pszString
, size_t cchString
,
975 PRTUTF16
*ppwsz
, size_t cwc
, size_t *pcwc
, const char *pszTag
);
979 * Calculates the length of the string in Latin-1 characters.
981 * This function will validate the string, and incorrectly encoded UTF-8
982 * strings as well as string with codepoints outside the latin-1 range will be
983 * rejected. The primary purpose of this function is to help allocate buffers
984 * for RTStrToLatin1Ex of the correct size. For most other purposes
985 * RTStrCalcLatin1LenEx() should be used.
987 * @returns Number of Latin-1 characters.
988 * @returns 0 if the string was incorrectly encoded.
989 * @param psz The string.
991 RTDECL(size_t) RTStrCalcLatin1Len(const char *psz
);
994 * Calculates the length of the string in Latin-1 characters.
996 * This function will validate the string, and incorrectly encoded UTF-8
997 * strings as well as string with codepoints outside the latin-1 range will be
1000 * @returns iprt status code.
1001 * @param psz The string.
1002 * @param cch The max string length. Use RTSTR_MAX to process the
1004 * @param pcch Where to store the string length. Optional.
1005 * This is undefined on failure.
1007 RTDECL(int) RTStrCalcLatin1LenEx(const char *psz
, size_t cch
, size_t *pcch
);
1010 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
1013 * @returns iprt status code.
1014 * @param pszString UTF-8 string to convert.
1015 * @param ppszString Receives pointer to the allocated Latin-1 string.
1016 * The returned string must be freed using RTStrFree().
1018 #define RTStrToLatin1(pszString, ppszString) RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
1021 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
1024 * @returns iprt status code.
1025 * @param pszString UTF-8 string to convert.
1026 * @param ppszString Receives pointer to the allocated Latin-1 string.
1027 * The returned string must be freed using RTStrFree().
1028 * @param pszTag Allocation tag used for statistics and such.
1030 RTDECL(int) RTStrToLatin1Tag(const char *pszString
, char **ppszString
, const char *pszTag
);
1033 * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
1035 * @returns iprt status code.
1036 * @param pszString UTF-8 string to convert.
1037 * @param cchString The maximum size in chars (the type) to convert.
1038 * The conversion stop when it reaches cchString or
1039 * the string terminator ('\\0'). Use RTSTR_MAX to
1040 * translate the entire string.
1041 * @param ppsz If cch is non-zero, this must either be pointing to
1042 * pointer to a buffer of the specified size, or
1043 * pointer to a NULL pointer. If *ppsz is NULL or cch
1044 * is zero a buffer of at least cch items will be
1045 * allocated to hold the translated string. If a
1046 * buffer was requested it must be freed using
1048 * @param cch The buffer size in bytes. This includes the
1050 * @param pcch Where to store the length of the translated string,
1051 * excluding the terminator. (Optional)
1053 * This may be set under some error conditions,
1054 * however, only for VERR_BUFFER_OVERFLOW and
1055 * VERR_NO_STR_MEMORY will it contain a valid string
1056 * length that can be used to resize the buffer.
1058 #define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
1059 RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
1062 * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
1063 * requested (custom tag).
1065 * @returns iprt status code.
1066 * @param pszString UTF-8 string to convert.
1067 * @param cchString The maximum size in chars (the type) to convert.
1068 * The conversion stop when it reaches cchString or
1069 * the string terminator ('\\0'). Use RTSTR_MAX to
1070 * translate the entire string.
1071 * @param ppsz If cch is non-zero, this must either be pointing to
1072 * pointer to a buffer of the specified size, or
1073 * pointer to a NULL pointer. If *ppsz is NULL or cch
1074 * is zero a buffer of at least cch items will be
1075 * allocated to hold the translated string. If a
1076 * buffer was requested it must be freed using
1078 * @param cch The buffer size in bytes. This includes the
1080 * @param pcch Where to store the length of the translated string,
1081 * excluding the terminator. (Optional)
1083 * This may be set under some error conditions,
1084 * however, only for VERR_BUFFER_OVERFLOW and
1085 * VERR_NO_STR_MEMORY will it contain a valid string
1086 * length that can be used to resize the buffer.
1087 * @param pszTag Allocation tag used for statistics and such.
1089 RTDECL(int) RTStrToLatin1ExTag(const char *pszString
, size_t cchString
, char **ppsz
, size_t cch
, size_t *pcch
, const char *pszTag
);
1092 * Get the unicode code point at the given string position.
1094 * @returns unicode code point.
1095 * @returns RTUNICP_INVALID if the encoding is invalid.
1096 * @param psz The string.
1098 RTDECL(RTUNICP
) RTStrGetCpInternal(const char *psz
);
1101 * Get the unicode code point at the given string position.
1103 * @returns iprt status code
1104 * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1105 * @param ppsz The string cursor.
1106 * This is advanced one character forward on failure.
1107 * @param pCp Where to store the unicode code point.
1108 * Stores RTUNICP_INVALID if the encoding is invalid.
1110 RTDECL(int) RTStrGetCpExInternal(const char **ppsz
, PRTUNICP pCp
);
1113 * Get the unicode code point at the given string position for a string of a
1116 * @returns iprt status code
1117 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1118 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1120 * @param ppsz The string.
1121 * @param pcch Pointer to the length of the string. This will be
1122 * decremented by the size of the code point.
1123 * @param pCp Where to store the unicode code point.
1124 * Stores RTUNICP_INVALID if the encoding is invalid.
1126 RTDECL(int) RTStrGetCpNExInternal(const char **ppsz
, size_t *pcch
, PRTUNICP pCp
);
1129 * Put the unicode code point at the given string position
1130 * and return the pointer to the char following it.
1132 * This function will not consider anything at or following the
1133 * buffer area pointed to by psz. It is therefore not suitable for
1134 * inserting code points into a string, only appending/overwriting.
1136 * @returns pointer to the char following the written code point.
1137 * @param psz The string.
1138 * @param CodePoint The code point to write.
1139 * This should not be RTUNICP_INVALID or any other
1140 * character out of the UTF-8 range.
1142 * @remark This is a worker function for RTStrPutCp().
1145 RTDECL(char *) RTStrPutCpInternal(char *psz
, RTUNICP CodePoint
);
1148 * Get the unicode code point at the given string position.
1150 * @returns unicode code point.
1151 * @returns RTUNICP_INVALID if the encoding is invalid.
1152 * @param psz The string.
1154 * @remark We optimize this operation by using an inline function for
1155 * the most frequent and simplest sequence, the rest is
1156 * handled by RTStrGetCpInternal().
1158 DECLINLINE(RTUNICP
) RTStrGetCp(const char *psz
)
1160 const unsigned char uch
= *(const unsigned char *)psz
;
1161 if (!(uch
& RT_BIT(7)))
1163 return RTStrGetCpInternal(psz
);
1167 * Get the unicode code point at the given string position.
1169 * @returns iprt status code.
1170 * @param ppsz Pointer to the string pointer. This will be updated to
1171 * point to the char following the current code point.
1172 * This is advanced one character forward on failure.
1173 * @param pCp Where to store the code point.
1174 * RTUNICP_INVALID is stored here on failure.
1176 * @remark We optimize this operation by using an inline function for
1177 * the most frequent and simplest sequence, the rest is
1178 * handled by RTStrGetCpExInternal().
1180 DECLINLINE(int) RTStrGetCpEx(const char **ppsz
, PRTUNICP pCp
)
1182 const unsigned char uch
= **(const unsigned char **)ppsz
;
1183 if (!(uch
& RT_BIT(7)))
1187 return VINF_SUCCESS
;
1189 return RTStrGetCpExInternal(ppsz
, pCp
);
1193 * Get the unicode code point at the given string position for a string of a
1194 * given maximum length.
1196 * @returns iprt status code.
1197 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1198 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1200 * @param ppsz Pointer to the string pointer. This will be updated to
1201 * point to the char following the current code point.
1202 * @param pcch Pointer to the maximum string length. This will be
1203 * decremented by the size of the code point found.
1204 * @param pCp Where to store the code point.
1205 * RTUNICP_INVALID is stored here on failure.
1207 * @remark We optimize this operation by using an inline function for
1208 * the most frequent and simplest sequence, the rest is
1209 * handled by RTStrGetCpNExInternal().
1211 DECLINLINE(int) RTStrGetCpNEx(const char **ppsz
, size_t *pcch
, PRTUNICP pCp
)
1213 if (RT_LIKELY(*pcch
!= 0))
1215 const unsigned char uch
= **(const unsigned char **)ppsz
;
1216 if (!(uch
& RT_BIT(7)))
1221 return VINF_SUCCESS
;
1224 return RTStrGetCpNExInternal(ppsz
, pcch
, pCp
);
1228 * Get the UTF-8 size in characters of a given Unicode code point.
1230 * The code point is expected to be a valid Unicode one, but not necessarily in
1231 * the range supported by UTF-8.
1233 * @returns The number of chars (bytes) required to encode the code point, or
1234 * zero if there is no UTF-8 encoding.
1235 * @param CodePoint The unicode code point.
1237 DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint
)
1239 if (CodePoint
< 0x00000080)
1241 if (CodePoint
< 0x00000800)
1243 if (CodePoint
< 0x00010000)
1245 #ifdef RT_USE_RTC_3629
1246 if (CodePoint
< 0x00011000)
1249 if (CodePoint
< 0x00200000)
1251 if (CodePoint
< 0x04000000)
1253 if (CodePoint
< 0x7fffffff)
1260 * Put the unicode code point at the given string position
1261 * and return the pointer to the char following it.
1263 * This function will not consider anything at or following the
1264 * buffer area pointed to by psz. It is therefore not suitable for
1265 * inserting code points into a string, only appending/overwriting.
1267 * @returns pointer to the char following the written code point.
1268 * @param psz The string.
1269 * @param CodePoint The code point to write.
1270 * This should not be RTUNICP_INVALID or any other
1271 * character out of the UTF-8 range.
1273 * @remark We optimize this operation by using an inline function for
1274 * the most frequent and simplest sequence, the rest is
1275 * handled by RTStrPutCpInternal().
1277 DECLINLINE(char *) RTStrPutCp(char *psz
, RTUNICP CodePoint
)
1279 if (CodePoint
< 0x80)
1281 *psz
++ = (unsigned char)CodePoint
;
1284 return RTStrPutCpInternal(psz
, CodePoint
);
1288 * Skips ahead, past the current code point.
1290 * @returns Pointer to the char after the current code point.
1291 * @param psz Pointer to the current code point.
1292 * @remark This will not move the next valid code point, only past the current one.
1294 DECLINLINE(char *) RTStrNextCp(const char *psz
)
1297 RTStrGetCpEx(&psz
, &Cp
);
1302 * Skips back to the previous code point.
1304 * @returns Pointer to the char before the current code point.
1305 * @returns pszStart on failure.
1306 * @param pszStart Pointer to the start of the string.
1307 * @param psz Pointer to the current code point.
1309 RTDECL(char *) RTStrPrevCp(const char *pszStart
, const char *psz
);
1312 /** @page pg_rt_str_format The IPRT Format Strings
1314 * IPRT implements most of the commonly used format types and flags with the
1315 * exception of floating point which is completely missing. In addition IPRT
1316 * provides a number of IPRT specific format types for the IPRT typedefs and
1317 * other useful things. Note that several of these extensions are similar to
1318 * \%p and doesn't care much if you try add formating flags/width/precision.
1321 * Group 0a, The commonly used format types:
1322 * - \%s - Takes a pointer to a zero terminated string (UTF-8) and
1323 * prints it with the optionally adjustment (width, -) and
1324 * length restriction (precision).
1325 * - \%ls - Same as \%s except that the input is UTF-16 (output UTF-8).
1326 * - \%Ls - Same as \%s except that the input is UCS-32 (output UTF-8).
1327 * - \%S - Same as \%s, used to convert to current codeset but this is
1328 * now done by the streams code. Deprecated, use \%s.
1329 * - \%lS - Ditto. Deprecated, use \%ls.
1330 * - \%LS - Ditto. Deprecated, use \%Ls.
1331 * - \%c - Takes a char and prints it.
1332 * - \%d - Takes a signed integer and prints it as decimal. Thousand
1333 * separator (\'), zero padding (0), adjustment (-+), width,
1335 * - \%i - Same as \%d.
1336 * - \%u - Takes an unsigned integer and prints it as decimal. Thousand
1337 * separator (\'), zero padding (0), adjustment (-+), width,
1339 * - \%x - Takes an unsigned integer and prints it as lowercased
1340 * hexadecimal. The special hash (\#) flag causes a '0x'
1341 * prefixed to be printed. Zero padding (0), adjustment (-+),
1343 * - \%X - Same as \%x except that it is uppercased.
1344 * - \%o - Takes an unsigned (?) integer and prints it as octal. Zero
1345 * padding (0), adjustment (-+), width, precision.
1346 * - \%p - Takes a pointer (void technically) and prints it. Zero
1347 * padding (0), adjustment (-+), width, precision.
1349 * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
1350 * argument type specifiers:
1351 * - \%ll - long long (uint64_t).
1352 * - \%L - long long (uint64_t).
1353 * - \%l - long (uint32_t, uint64_t)
1354 * - \%h - short (int16_t).
1355 * - \%hh - char (int8_t).
1356 * - \%H - char (int8_t).
1358 * - \%j - intmax_t (int64_t).
1359 * - \%t - ptrdiff_t.
1360 * The type in parentheses is typical sizes, however when printing those types
1361 * you are better off using the special group 2 format types below (\%RX32 and
1365 * Group 0b, IPRT format tricks:
1366 * - %M - Replaces the format string, takes a string pointer.
1367 * - %N - Nested formatting, takes a pointer to a format string
1368 * followed by the pointer to a va_list variable. The va_list
1369 * variable will not be modified and the caller must do va_end()
1370 * on it. Make sure the va_list variable is NOT in a parameter
1371 * list or some gcc versions/targets may get it all wrong.
1374 * Group 1, the basic runtime typedefs (excluding those which obviously are
1376 * - \%RTbool - Takes a bool value and prints 'true', 'false', or '!%d!'.
1377 * - \%RTfile - Takes a #RTFILE value.
1378 * - \%RTfmode - Takes a #RTFMODE value.
1379 * - \%RTfoff - Takes a #RTFOFF value.
1380 * - \%RTfp16 - Takes a #RTFAR16 value.
1381 * - \%RTfp32 - Takes a #RTFAR32 value.
1382 * - \%RTfp64 - Takes a #RTFAR64 value.
1383 * - \%RTgid - Takes a #RTGID value.
1384 * - \%RTino - Takes a #RTINODE value.
1385 * - \%RTint - Takes a #RTINT value.
1386 * - \%RTiop - Takes a #RTIOPORT value.
1387 * - \%RTldrm - Takes a #RTLDRMOD value.
1388 * - \%RTmac - Takes a #PCRTMAC pointer.
1389 * - \%RTnaddr - Takes a #PCRTNETADDR value.
1390 * - \%RTnaipv4 - Takes a #RTNETADDRIPV4 value.
1391 * - \%RTnaipv6 - Takes a #PCRTNETADDRIPV6 value.
1392 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1393 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1394 * - \%RTproc - Takes a #RTPROCESS value.
1395 * - \%RTptr - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
1396 * - \%RTreg - Takes a #RTCCUINTREG value.
1397 * - \%RTsel - Takes a #RTSEL value.
1398 * - \%RTsem - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
1399 * - \%RTsock - Takes a #RTSOCKET value.
1400 * - \%RTthrd - Takes a #RTTHREAD value.
1401 * - \%RTuid - Takes a #RTUID value.
1402 * - \%RTuint - Takes a #RTUINT value.
1403 * - \%RTunicp - Takes a #RTUNICP value.
1404 * - \%RTutf16 - Takes a #RTUTF16 value.
1405 * - \%RTuuid - Takes a #PCRTUUID and will print the UUID as a string.
1406 * - \%RTxuint - Takes a #RTUINT or #RTINT value, formatting it as hex.
1407 * - \%RGi - Takes a #RTGCINT value.
1408 * - \%RGp - Takes a #RTGCPHYS value.
1409 * - \%RGr - Takes a #RTGCUINTREG value.
1410 * - \%RGu - Takes a #RTGCUINT value.
1411 * - \%RGv - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
1412 * - \%RGx - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
1413 * - \%RHi - Takes a #RTHCINT value.
1414 * - \%RHp - Takes a #RTHCPHYS value.
1415 * - \%RHr - Takes a #RTHCUINTREG value.
1416 * - \%RHu - Takes a #RTHCUINT value.
1417 * - \%RHv - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
1418 * - \%RHx - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
1419 * - \%RRv - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
1420 * - \%RCi - Takes a #RTINT value.
1421 * - \%RCp - Takes a #RTCCPHYS value.
1422 * - \%RCr - Takes a #RTCCUINTREG value.
1423 * - \%RCu - Takes a #RTUINT value.
1424 * - \%RCv - Takes a #uintptr_t, #intptr_t, void * value.
1425 * - \%RCx - Takes a #RTUINT or #RTINT value, formatting it as hex.
1428 * Group 2, the generic integer types which are prefered over relying on what
1429 * bit-count a 'long', 'short', or 'long long' has on a platform. This are
1430 * highly prefered for the [u]intXX_t kind of types:
1431 * - \%RI[8|16|32|64] - Signed integer value of the specifed bit count.
1432 * - \%RU[8|16|32|64] - Unsigned integer value of the specifed bit count.
1433 * - \%RX[8|16|32|64] - Hexadecimal integer value of the specifed bit count.
1436 * Group 3, hex dumpers and other complex stuff which requires more than simple
1438 * - \%Rhxd - Takes a pointer to the memory which is to be dumped in typical
1439 * hex format. Use the precision to specify the length, and the width to
1440 * set the number of bytes per line. Default width and precision is 16.
1441 * - \%RhxD - Same as \%Rhxd, except that it skips duplicate lines.
1442 * - \%Rhxs - Takes a pointer to the memory to be displayed as a hex string,
1443 * i.e. a series of space separated bytes formatted as two digit hex value.
1444 * Use the precision to specify the length. Default length is 16 bytes.
1445 * The width, if specified, is ignored.
1446 * - \%Rrc - Takes an integer iprt status code as argument. Will insert the
1447 * status code define corresponding to the iprt status code.
1448 * - \%Rrs - Takes an integer iprt status code as argument. Will insert the
1449 * short description of the specified status code.
1450 * - \%Rrf - Takes an integer iprt status code as argument. Will insert the
1451 * full description of the specified status code.
1452 * - \%Rra - Takes an integer iprt status code as argument. Will insert the
1453 * status code define + full description.
1454 * - \%Rwc - Takes a long Windows error code as argument. Will insert the status
1455 * code define corresponding to the Windows error code.
1456 * - \%Rwf - Takes a long Windows error code as argument. Will insert the
1457 * full description of the specified status code.
1458 * - \%Rwa - Takes a long Windows error code as argument. Will insert the
1459 * error code define + full description.
1461 * - \%Rhrc - Takes a COM/XPCOM status code as argument. Will insert the status
1462 * code define corresponding to the Windows error code.
1463 * - \%Rhrf - Takes a COM/XPCOM status code as argument. Will insert the
1464 * full description of the specified status code.
1465 * - \%Rhra - Takes a COM/XPCOM error code as argument. Will insert the
1466 * error code define + full description.
1468 * - \%Rfn - Pretty printing of a function or method. It drops the
1469 * return code and parameter list.
1470 * - \%Rbn - Prints the base name. For dropping the path in
1471 * order to save space when printing a path name.
1473 * - \%lRbs - Same as \%ls except inlut is big endian UTF-16.
1475 * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
1478 * Group 4, structure dumpers:
1479 * - \%RDtimespec - Takes a PCRTTIMESPEC.
1482 * Group 5, XML / HTML escapers:
1483 * - \%RMas - Takes a string pointer (const char *) and outputs
1484 * it as an attribute value with the proper escaping.
1485 * This typically ends up in double quotes.
1487 * - \%RMes - Takes a string pointer (const char *) and outputs
1488 * it as an element with the necessary escaping.
1490 * Group 6, CPU Architecture Register dumpers:
1491 * - \%RAx86[reg] - Takes a 64-bit register value if the register is
1492 * 64-bit or smaller. Check the code wrt which
1493 * registers are implemented.
1497 #ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
1498 # define DECLARED_FNRTSTROUTPUT
1502 * @returns number of bytes written.
1503 * @param pvArg User argument.
1504 * @param pachChars Pointer to an array of utf-8 characters.
1505 * @param cbChars Number of bytes in the character array pointed to by pachChars.
1507 typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg
, const char *pachChars
, size_t cbChars
);
1508 /** Pointer to callback function. */
1509 typedef FNRTSTROUTPUT
*PFNRTSTROUTPUT
;
1512 /** @name Format flag.
1513 * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
1514 * that not all flags makes sense to both of the functions.
1516 #define RTSTR_F_CAPITAL 0x0001
1517 #define RTSTR_F_LEFT 0x0002
1518 #define RTSTR_F_ZEROPAD 0x0004
1519 #define RTSTR_F_SPECIAL 0x0008
1520 #define RTSTR_F_VALSIGNED 0x0010
1521 #define RTSTR_F_PLUS 0x0020
1522 #define RTSTR_F_BLANK 0x0040
1523 #define RTSTR_F_WIDTH 0x0080
1524 #define RTSTR_F_PRECISION 0x0100
1525 #define RTSTR_F_THOUSAND_SEP 0x0200
1526 #define RTSTR_F_OBFUSCATE_PTR 0x0400
1528 #define RTSTR_F_BIT_MASK 0xf800
1529 #define RTSTR_F_8BIT 0x0800
1530 #define RTSTR_F_16BIT 0x1000
1531 #define RTSTR_F_32BIT 0x2000
1532 #define RTSTR_F_64BIT 0x4000
1533 #define RTSTR_F_128BIT 0x8000
1536 /** @def RTSTR_GET_BIT_FLAG
1537 * Gets the bit flag for the specified type.
1539 #define RTSTR_GET_BIT_FLAG(type) \
1540 ( sizeof(type) * 8 == 32 ? RTSTR_F_32BIT \
1541 : sizeof(type) * 8 == 64 ? RTSTR_F_64BIT \
1542 : sizeof(type) * 8 == 16 ? RTSTR_F_16BIT \
1543 : sizeof(type) * 8 == 8 ? RTSTR_F_8BIT \
1544 : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
1549 * Callback to format non-standard format specifiers.
1551 * @returns The number of bytes formatted.
1552 * @param pvArg Formatter argument.
1553 * @param pfnOutput Pointer to output function.
1554 * @param pvArgOutput Argument for the output function.
1555 * @param ppszFormat Pointer to the format string pointer. Advance this till the char
1556 * after the format specifier.
1557 * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
1558 * @param cchWidth Format Width. -1 if not specified.
1559 * @param cchPrecision Format Precision. -1 if not specified.
1560 * @param fFlags Flags (RTSTR_NTFS_*).
1561 * @param chArgSize The argument size specifier, 'l' or 'L'.
1563 typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg
, PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
,
1564 const char **ppszFormat
, va_list *pArgs
, int cchWidth
,
1565 int cchPrecision
, unsigned fFlags
, char chArgSize
);
1566 /** Pointer to a FNSTRFORMAT() function. */
1567 typedef FNSTRFORMAT
*PFNSTRFORMAT
;
1571 * Partial implementation of a printf like formatter.
1572 * It doesn't do everything correct, and there is no floating point support.
1573 * However, it supports custom formats by the means of a format callback.
1575 * @returns number of bytes formatted.
1576 * @param pfnOutput Output worker.
1577 * Called in two ways. Normally with a string and its length.
1578 * For termination, it's called with NULL for string, 0 for length.
1579 * @param pvArgOutput Argument to the output worker.
1580 * @param pfnFormat Custom format worker.
1581 * @param pvArgFormat Argument to the format worker.
1582 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1583 * @param InArgs Argument list.
1585 RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
, PFNSTRFORMAT pfnFormat
, void *pvArgFormat
,
1586 const char *pszFormat
, va_list InArgs
) RT_IPRT_FORMAT_ATTR(5, 0);
1589 * Partial implementation of a printf like formatter.
1591 * It doesn't do everything correct, and there is no floating point support.
1592 * However, it supports custom formats by the means of a format callback.
1594 * @returns number of bytes formatted.
1595 * @param pfnOutput Output worker.
1596 * Called in two ways. Normally with a string and its length.
1597 * For termination, it's called with NULL for string, 0 for length.
1598 * @param pvArgOutput Argument to the output worker.
1599 * @param pfnFormat Custom format worker.
1600 * @param pvArgFormat Argument to the format worker.
1601 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1602 * @param ... Argument list.
1604 RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
, PFNSTRFORMAT pfnFormat
, void *pvArgFormat
,
1605 const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1608 * Formats an integer number according to the parameters.
1610 * @returns Length of the formatted number.
1611 * @param psz Pointer to output string buffer of sufficient size.
1612 * @param u64Value Value to format.
1613 * @param uiBase Number representation base.
1614 * @param cchWidth Width.
1615 * @param cchPrecision Precision.
1616 * @param fFlags Flags, RTSTR_F_XXX.
1618 RTDECL(int) RTStrFormatNumber(char *psz
, uint64_t u64Value
, unsigned int uiBase
, signed int cchWidth
, signed int cchPrecision
,
1619 unsigned int fFlags
);
1622 * Formats an unsigned 8-bit number.
1624 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1625 * @param pszBuf The output buffer.
1626 * @param cbBuf The size of the output buffer.
1627 * @param u8Value The value to format.
1628 * @param uiBase Number representation base.
1629 * @param cchWidth Width.
1630 * @param cchPrecision Precision.
1631 * @param fFlags Flags, RTSTR_F_XXX.
1633 RTDECL(ssize_t
) RTStrFormatU8(char *pszBuf
, size_t cbBuf
, uint8_t u8Value
, unsigned int uiBase
,
1634 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1637 * Formats an unsigned 16-bit number.
1639 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1640 * @param pszBuf The output buffer.
1641 * @param cbBuf The size of the output buffer.
1642 * @param u16Value The value to format.
1643 * @param uiBase Number representation base.
1644 * @param cchWidth Width.
1645 * @param cchPrecision Precision.
1646 * @param fFlags Flags, RTSTR_F_XXX.
1648 RTDECL(ssize_t
) RTStrFormatU16(char *pszBuf
, size_t cbBuf
, uint16_t u16Value
, unsigned int uiBase
,
1649 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1652 * Formats an unsigned 32-bit number.
1654 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1655 * @param pszBuf The output buffer.
1656 * @param cbBuf The size of the output buffer.
1657 * @param u32Value The value to format.
1658 * @param uiBase Number representation base.
1659 * @param cchWidth Width.
1660 * @param cchPrecision Precision.
1661 * @param fFlags Flags, RTSTR_F_XXX.
1663 RTDECL(ssize_t
) RTStrFormatU32(char *pszBuf
, size_t cbBuf
, uint32_t u32Value
, unsigned int uiBase
,
1664 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1667 * Formats an unsigned 64-bit number.
1669 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1670 * @param pszBuf The output buffer.
1671 * @param cbBuf The size of the output buffer.
1672 * @param u64Value The value to format.
1673 * @param uiBase Number representation base.
1674 * @param cchWidth Width.
1675 * @param cchPrecision Precision.
1676 * @param fFlags Flags, RTSTR_F_XXX.
1678 RTDECL(ssize_t
) RTStrFormatU64(char *pszBuf
, size_t cbBuf
, uint64_t u64Value
, unsigned int uiBase
,
1679 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1682 * Formats an unsigned 128-bit number.
1684 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1685 * @param pszBuf The output buffer.
1686 * @param cbBuf The size of the output buffer.
1687 * @param pu128Value The value to format.
1688 * @param uiBase Number representation base.
1689 * @param cchWidth Width.
1690 * @param cchPrecision Precision.
1691 * @param fFlags Flags, RTSTR_F_XXX.
1692 * @remarks The current implementation is limited to base 16 and doesn't do
1693 * width or precision and probably ignores few flags too.
1695 RTDECL(ssize_t
) RTStrFormatU128(char *pszBuf
, size_t cbBuf
, PCRTUINT128U pu128Value
, unsigned int uiBase
,
1696 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1699 * Formats an unsigned 256-bit number.
1701 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1702 * @param pszBuf The output buffer.
1703 * @param cbBuf The size of the output buffer.
1704 * @param pu256Value The value to format.
1705 * @param uiBase Number representation base.
1706 * @param cchWidth Width.
1707 * @param cchPrecision Precision.
1708 * @param fFlags Flags, RTSTR_F_XXX.
1709 * @remarks The current implementation is limited to base 16 and doesn't do
1710 * width or precision and probably ignores few flags too.
1712 RTDECL(ssize_t
) RTStrFormatU256(char *pszBuf
, size_t cbBuf
, PCRTUINT256U pu256Value
, unsigned int uiBase
,
1713 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1716 * Formats an unsigned 512-bit number.
1718 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1719 * @param pszBuf The output buffer.
1720 * @param cbBuf The size of the output buffer.
1721 * @param pu512Value The value to format.
1722 * @param uiBase Number representation base.
1723 * @param cchWidth Width.
1724 * @param cchPrecision Precision.
1725 * @param fFlags Flags, RTSTR_F_XXX.
1726 * @remarks The current implementation is limited to base 16 and doesn't do
1727 * width or precision and probably ignores few flags too.
1729 RTDECL(ssize_t
) RTStrFormatU512(char *pszBuf
, size_t cbBuf
, PCRTUINT512U pu512Value
, unsigned int uiBase
,
1730 signed int cchWidth
, signed int cchPrecision
, uint32_t fFlags
);
1734 * Formats an 80-bit extended floating point number.
1736 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1737 * @param pszBuf The output buffer.
1738 * @param cbBuf The size of the output buffer.
1739 * @param pr80Value The value to format.
1740 * @param cchWidth Width.
1741 * @param cchPrecision Precision.
1742 * @param fFlags Flags, RTSTR_F_XXX.
1744 RTDECL(ssize_t
) RTStrFormatR80(char *pszBuf
, size_t cbBuf
, PCRTFLOAT80U pr80Value
, signed int cchWidth
,
1745 signed int cchPrecision
, uint32_t fFlags
);
1748 * Formats an 80-bit extended floating point number, version 2.
1750 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1751 * @param pszBuf The output buffer.
1752 * @param cbBuf The size of the output buffer.
1753 * @param pr80Value The value to format.
1754 * @param cchWidth Width.
1755 * @param cchPrecision Precision.
1756 * @param fFlags Flags, RTSTR_F_XXX.
1758 RTDECL(ssize_t
) RTStrFormatR80u2(char *pszBuf
, size_t cbBuf
, PCRTFLOAT80U2 pr80Value
, signed int cchWidth
,
1759 signed int cchPrecision
, uint32_t fFlags
);
1764 * Callback for formatting a type.
1766 * This is registered using the RTStrFormatTypeRegister function and will
1767 * be called during string formatting to handle the specified %R[type].
1768 * The argument for this format type is assumed to be a pointer and it's
1769 * passed in the @a pvValue argument.
1771 * @returns Length of the formatted output.
1772 * @param pfnOutput Output worker.
1773 * @param pvArgOutput Argument to the output worker.
1774 * @param pszType The type name.
1775 * @param pvValue The argument value.
1776 * @param cchWidth Width.
1777 * @param cchPrecision Precision.
1778 * @param fFlags Flags (NTFS_*).
1779 * @param pvUser The user argument.
1781 typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput
, void *pvArgOutput
,
1782 const char *pszType
, void const *pvValue
,
1783 int cchWidth
, int cchPrecision
, unsigned fFlags
,
1785 /** Pointer to a FNRTSTRFORMATTYPE. */
1786 typedef FNRTSTRFORMATTYPE
*PFNRTSTRFORMATTYPE
;
1790 * Register a format handler for a type.
1792 * The format handler is used to handle '%R[type]' format types, where the argument
1793 * in the vector is a pointer value (a bit restrictive, but keeps it simple).
1795 * The caller must ensure that no other thread will be making use of any of
1796 * the dynamic formatting type facilities simultaneously with this call.
1798 * @returns IPRT status code.
1799 * @retval VINF_SUCCESS on success.
1800 * @retval VERR_ALREADY_EXISTS if the type has already been registered.
1801 * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
1803 * @param pszType The type name.
1804 * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
1805 * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
1806 * for how to update this later.
1808 RTDECL(int) RTStrFormatTypeRegister(const char *pszType
, PFNRTSTRFORMATTYPE pfnHandler
, void *pvUser
);
1811 * Deregisters a format type.
1813 * The caller must ensure that no other thread will be making use of any of
1814 * the dynamic formatting type facilities simultaneously with this call.
1816 * @returns IPRT status code.
1817 * @retval VINF_SUCCESS on success.
1818 * @retval VERR_FILE_NOT_FOUND if not found.
1820 * @param pszType The type to deregister.
1822 RTDECL(int) RTStrFormatTypeDeregister(const char *pszType
);
1825 * Sets the user argument for a type.
1827 * This can be used if a user argument needs relocating in GC.
1829 * @returns IPRT status code.
1830 * @retval VINF_SUCCESS on success.
1831 * @retval VERR_FILE_NOT_FOUND if not found.
1833 * @param pszType The type to update.
1834 * @param pvUser The new user argument value.
1836 RTDECL(int) RTStrFormatTypeSetUser(const char *pszType
, void *pvUser
);
1842 * @returns The length of the returned string (in pszBuffer) excluding the
1844 * @param pszBuffer Output buffer.
1845 * @param cchBuffer Size of the output buffer.
1846 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1847 * @param args The format argument.
1849 * @deprecated Use RTStrPrintf2V! Problematic return value on overflow.
1851 RTDECL(size_t) RTStrPrintfV(char *pszBuffer
, size_t cchBuffer
, const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(3, 0);
1856 * @returns The length of the returned string (in pszBuffer) excluding the
1858 * @param pszBuffer Output buffer.
1859 * @param cchBuffer Size of the output buffer.
1860 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1861 * @param ... The format argument.
1863 * @deprecated Use RTStrPrintf2! Problematic return value on overflow.
1865 RTDECL(size_t) RTStrPrintf(char *pszBuffer
, size_t cchBuffer
, const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1868 * String printf with custom formatting.
1870 * @returns The length of the returned string (in pszBuffer) excluding the
1872 * @param pfnFormat Pointer to handler function for the custom formats.
1873 * @param pvArg Argument to the pfnFormat function.
1874 * @param pszBuffer Output buffer.
1875 * @param cchBuffer Size of the output buffer.
1876 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1877 * @param args The format argument.
1879 * @deprecated Use RTStrPrintf2ExV! Problematic return value on overflow.
1881 RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cchBuffer
,
1882 const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(5, 0);
1885 * String printf with custom formatting.
1887 * @returns The length of the returned string (in pszBuffer) excluding the
1889 * @param pfnFormat Pointer to handler function for the custom formats.
1890 * @param pvArg Argument to the pfnFormat function.
1891 * @param pszBuffer Output buffer.
1892 * @param cchBuffer Size of the output buffer.
1893 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1894 * @param ... The format argument.
1896 * @deprecated Use RTStrPrintf2Ex! Problematic return value on overflow.
1898 RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cchBuffer
,
1899 const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1902 * String printf, version 2.
1904 * @returns On success, positive count of formatted character excluding the
1905 * terminator. On buffer overflow, negative number giving the required
1906 * buffer size (including terminator char).
1908 * @param pszBuffer Output buffer.
1909 * @param cbBuffer Size of the output buffer.
1910 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1911 * @param args The format argument.
1913 RTDECL(ssize_t
) RTStrPrintf2V(char *pszBuffer
, size_t cbBuffer
, const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(3, 0);
1916 * String printf, version 2.
1918 * @returns On success, positive count of formatted character excluding the
1919 * terminator. On buffer overflow, negative number giving the required
1920 * buffer size (including terminator char).
1922 * @param pszBuffer Output buffer.
1923 * @param cbBuffer Size of the output buffer.
1924 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1925 * @param ... The format argument.
1927 RTDECL(ssize_t
) RTStrPrintf2(char *pszBuffer
, size_t cbBuffer
, const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1930 * String printf with custom formatting, version 2.
1932 * @returns On success, positive count of formatted character excluding the
1933 * terminator. On buffer overflow, negative number giving the required
1934 * buffer size (including terminator char).
1936 * @param pfnFormat Pointer to handler function for the custom formats.
1937 * @param pvArg Argument to the pfnFormat function.
1938 * @param pszBuffer Output buffer.
1939 * @param cbBuffer Size of the output buffer.
1940 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1941 * @param args The format argument.
1943 RTDECL(ssize_t
) RTStrPrintf2ExV(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cbBuffer
,
1944 const char *pszFormat
, va_list args
) RT_IPRT_FORMAT_ATTR(5, 0);
1947 * String printf with custom formatting, version 2.
1949 * @returns On success, positive count of formatted character excluding the
1950 * terminator. On buffer overflow, negative number giving the required
1951 * buffer size (including terminator char).
1953 * @param pfnFormat Pointer to handler function for the custom formats.
1954 * @param pvArg Argument to the pfnFormat function.
1955 * @param pszBuffer Output buffer.
1956 * @param cbBuffer Size of the output buffer.
1957 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1958 * @param ... The format argument.
1960 RTDECL(ssize_t
) RTStrPrintf2Ex(PFNSTRFORMAT pfnFormat
, void *pvArg
, char *pszBuffer
, size_t cbBuffer
,
1961 const char *pszFormat
, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1964 * Allocating string printf (default tag).
1966 * @returns The length of the string in the returned *ppszBuffer excluding the
1968 * @returns -1 on failure.
1969 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1970 * The buffer should be freed using RTStrFree().
1971 * On failure *ppszBuffer will be set to NULL.
1972 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1973 * @param args The format argument.
1975 #define RTStrAPrintfV(ppszBuffer, pszFormat, args) RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
1978 * Allocating string printf (custom tag).
1980 * @returns The length of the string in the returned *ppszBuffer excluding the
1982 * @returns -1 on failure.
1983 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1984 * The buffer should be freed using RTStrFree().
1985 * On failure *ppszBuffer will be set to NULL.
1986 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1987 * @param args The format argument.
1988 * @param pszTag Allocation tag used for statistics and such.
1990 RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer
, const char *pszFormat
, va_list args
, const char *pszTag
) RT_IPRT_FORMAT_ATTR(2, 0);
1993 * Allocating string printf.
1995 * @returns The length of the string in the returned *ppszBuffer excluding the
1997 * @returns -1 on failure.
1998 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
1999 * The buffer should be freed using RTStrFree().
2000 * On failure *ppszBuffer will be set to NULL.
2001 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2002 * @param ... The format argument.
2004 DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer
, const char *pszFormat
, ...)
2008 va_start(va
, pszFormat
);
2009 cbRet
= RTStrAPrintfVTag(ppszBuffer
, pszFormat
, va
, RTSTR_TAG
);
2015 * Allocating string printf (custom tag).
2017 * @returns The length of the string in the returned *ppszBuffer excluding the
2019 * @returns -1 on failure.
2020 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
2021 * The buffer should be freed using RTStrFree().
2022 * On failure *ppszBuffer will be set to NULL.
2023 * @param pszTag Allocation tag used for statistics and such.
2024 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2025 * @param ... The format argument.
2027 DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer
, const char *pszTag
, const char *pszFormat
, ...)
2031 va_start(va
, pszFormat
);
2032 cbRet
= RTStrAPrintfVTag(ppszBuffer
, pszFormat
, va
, pszTag
);
2038 * Allocating string printf, version 2.
2040 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2042 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2043 * @param args The format argument.
2045 #define RTStrAPrintf2V(pszFormat, args) RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
2048 * Allocating string printf, version 2.
2050 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2052 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2053 * @param args The format argument.
2054 * @param pszTag Allocation tag used for statistics and such.
2056 RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat
, va_list args
, const char *pszTag
) RT_IPRT_FORMAT_ATTR(1, 0);
2059 * Allocating string printf, version 2 (default tag).
2061 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2063 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2064 * @param ... The format argument.
2066 DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat
, ...)
2070 va_start(va
, pszFormat
);
2071 pszRet
= RTStrAPrintf2VTag(pszFormat
, va
, RTSTR_TAG
);
2077 * Allocating string printf, version 2 (custom tag).
2079 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2081 * @param pszTag Allocation tag used for statistics and such.
2082 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2083 * @param ... The format argument.
2085 DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag
, const char *pszFormat
, ...)
2089 va_start(va
, pszFormat
);
2090 pszRet
= RTStrAPrintf2VTag(pszFormat
, va
, pszTag
);
2096 * Strips blankspaces from both ends of the string.
2098 * @returns Pointer to first non-blank char in the string.
2099 * @param psz The string to strip.
2101 RTDECL(char *) RTStrStrip(char *psz
);
2104 * Strips blankspaces from the start of the string.
2106 * @returns Pointer to first non-blank char in the string.
2107 * @param psz The string to strip.
2109 RTDECL(char *) RTStrStripL(const char *psz
);
2112 * Strips blankspaces from the end of the string.
2115 * @param psz The string to strip.
2117 RTDECL(char *) RTStrStripR(char *psz
);
2120 * String copy with overflow handling.
2122 * @retval VINF_SUCCESS on success.
2123 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2124 * buffer will contain as much of the string as it can hold, fully
2127 * @param pszDst The destination buffer.
2128 * @param cbDst The size of the destination buffer (in bytes).
2129 * @param pszSrc The source string. NULL is not OK.
2131 RTDECL(int) RTStrCopy(char *pszDst
, size_t cbDst
, const char *pszSrc
);
2134 * String copy with overflow handling.
2136 * @retval VINF_SUCCESS on success.
2137 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2138 * buffer will contain as much of the string as it can hold, fully
2141 * @param pszDst The destination buffer.
2142 * @param cbDst The size of the destination buffer (in bytes).
2143 * @param pszSrc The source string. NULL is not OK.
2144 * @param cchSrcMax The maximum number of chars (not code points) to
2145 * copy from the source string, not counting the
2146 * terminator as usual.
2148 RTDECL(int) RTStrCopyEx(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cchSrcMax
);
2151 * String copy with overflow handling and buffer advancing.
2153 * @retval VINF_SUCCESS on success.
2154 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2155 * buffer will contain as much of the string as it can hold, fully
2158 * @param ppszDst Pointer to the destination buffer pointer.
2159 * This will be advanced to the end of the copied
2160 * bytes (points at the terminator). This is also
2161 * updated on overflow.
2162 * @param pcbDst Pointer to the destination buffer size
2163 * variable. This will be updated in accord with
2164 * the buffer pointer.
2165 * @param pszSrc The source string. NULL is not OK.
2167 RTDECL(int) RTStrCopyP(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
);
2170 * String copy with overflow handling.
2172 * @retval VINF_SUCCESS on success.
2173 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2174 * buffer will contain as much of the string as it can hold, fully
2177 * @param ppszDst Pointer to the destination buffer pointer.
2178 * This will be advanced to the end of the copied
2179 * bytes (points at the terminator). This is also
2180 * updated on overflow.
2181 * @param pcbDst Pointer to the destination buffer size
2182 * variable. This will be updated in accord with
2183 * the buffer pointer.
2184 * @param pszSrc The source string. NULL is not OK.
2185 * @param cchSrcMax The maximum number of chars (not code points) to
2186 * copy from the source string, not counting the
2187 * terminator as usual.
2189 RTDECL(int) RTStrCopyPEx(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
, size_t cchSrcMax
);
2192 * String concatenation with overflow handling.
2194 * @retval VINF_SUCCESS on success.
2195 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2196 * buffer will contain as much of the string as it can hold, fully
2199 * @param pszDst The destination buffer.
2200 * @param cbDst The size of the destination buffer (in bytes).
2201 * @param pszSrc The source string. NULL is not OK.
2203 RTDECL(int) RTStrCat(char *pszDst
, size_t cbDst
, const char *pszSrc
);
2206 * String concatenation with overflow handling.
2208 * @retval VINF_SUCCESS on success.
2209 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2210 * buffer will contain as much of the string as it can hold, fully
2213 * @param pszDst The destination buffer.
2214 * @param cbDst The size of the destination buffer (in bytes).
2215 * @param pszSrc The source string. NULL is not OK.
2216 * @param cchSrcMax The maximum number of chars (not code points) to
2217 * copy from the source string, not counting the
2218 * terminator as usual.
2220 RTDECL(int) RTStrCatEx(char *pszDst
, size_t cbDst
, const char *pszSrc
, size_t cchSrcMax
);
2223 * String concatenation with overflow handling.
2225 * @retval VINF_SUCCESS on success.
2226 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2227 * buffer will contain as much of the string as it can hold, fully
2230 * @param ppszDst Pointer to the destination buffer pointer.
2231 * This will be advanced to the end of the copied
2232 * bytes (points at the terminator). This is also
2233 * updated on overflow.
2234 * @param pcbDst Pointer to the destination buffer size
2235 * variable. This will be updated in accord with
2236 * the buffer pointer.
2237 * @param pszSrc The source string. NULL is not OK.
2239 RTDECL(int) RTStrCatP(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
);
2242 * String concatenation with overflow handling and buffer advancing.
2244 * @retval VINF_SUCCESS on success.
2245 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2246 * buffer will contain as much of the string as it can hold, fully
2249 * @param ppszDst Pointer to the destination buffer pointer.
2250 * This will be advanced to the end of the copied
2251 * bytes (points at the terminator). This is also
2252 * updated on overflow.
2253 * @param pcbDst Pointer to the destination buffer size
2254 * variable. This will be updated in accord with
2255 * the buffer pointer.
2256 * @param pszSrc The source string. NULL is not OK.
2257 * @param cchSrcMax The maximum number of chars (not code points) to
2258 * copy from the source string, not counting the
2259 * terminator as usual.
2261 RTDECL(int) RTStrCatPEx(char **ppszDst
, size_t *pcbDst
, const char *pszSrc
, size_t cchSrcMax
);
2264 * Performs a case sensitive string compare between two UTF-8 strings.
2266 * Encoding errors are ignored by the current implementation. So, the only
2267 * difference between this and the CRT strcmp function is the handling of
2270 * @returns < 0 if the first string less than the second string.
2271 * @returns 0 if the first string identical to the second string.
2272 * @returns > 0 if the first string greater than the second string.
2273 * @param psz1 First UTF-8 string. Null is allowed.
2274 * @param psz2 Second UTF-8 string. Null is allowed.
2276 RTDECL(int) RTStrCmp(const char *psz1
, const char *psz2
);
2279 * Performs a case sensitive string compare between two UTF-8 strings, given
2280 * a maximum string length.
2282 * Encoding errors are ignored by the current implementation. So, the only
2283 * difference between this and the CRT strncmp function is the handling of
2286 * @returns < 0 if the first string less than the second string.
2287 * @returns 0 if the first string identical to the second string.
2288 * @returns > 0 if the first string greater than the second string.
2289 * @param psz1 First UTF-8 string. Null is allowed.
2290 * @param psz2 Second UTF-8 string. Null is allowed.
2291 * @param cchMax The maximum string length
2293 RTDECL(int) RTStrNCmp(const char *psz1
, const char *psz2
, size_t cchMax
);
2296 * Performs a case insensitive string compare between two UTF-8 strings.
2298 * This is a simplified compare, as only the simplified lower/upper case folding
2299 * specified by the unicode specs are used. It does not consider character pairs
2300 * as they are used in some languages, just simple upper & lower case compares.
2302 * The result is the difference between the mismatching codepoints after they
2303 * both have been lower cased.
2305 * If the string encoding is invalid the function will assert (strict builds)
2306 * and use RTStrCmp for the remainder of the string.
2308 * @returns < 0 if the first string less than the second string.
2309 * @returns 0 if the first string identical to the second string.
2310 * @returns > 0 if the first string greater than the second string.
2311 * @param psz1 First UTF-8 string. Null is allowed.
2312 * @param psz2 Second UTF-8 string. Null is allowed.
2314 RTDECL(int) RTStrICmp(const char *psz1
, const char *psz2
);
2317 * Performs a case insensitive string compare between two UTF-8 strings, given a
2318 * maximum string length.
2320 * This is a simplified compare, as only the simplified lower/upper case folding
2321 * specified by the unicode specs are used. It does not consider character pairs
2322 * as they are used in some languages, just simple upper & lower case compares.
2324 * The result is the difference between the mismatching codepoints after they
2325 * both have been lower cased.
2327 * If the string encoding is invalid the function will assert (strict builds)
2328 * and use RTStrCmp for the remainder of the string.
2330 * @returns < 0 if the first string less than the second string.
2331 * @returns 0 if the first string identical to the second string.
2332 * @returns > 0 if the first string greater than the second string.
2333 * @param psz1 First UTF-8 string. Null is allowed.
2334 * @param psz2 Second UTF-8 string. Null is allowed.
2335 * @param cchMax Maximum string length
2337 RTDECL(int) RTStrNICmp(const char *psz1
, const char *psz2
, size_t cchMax
);
2340 * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
2343 * This is potentially faster than RTStrICmp and drags in less dependencies. It
2344 * is really handy for hardcoded inputs.
2346 * If the string encoding is invalid the function will assert (strict builds)
2347 * and use RTStrCmp for the remainder of the string.
2349 * @returns < 0 if the first string less than the second string.
2350 * @returns 0 if the first string identical to the second string.
2351 * @returns > 0 if the first string greater than the second string.
2352 * @param psz1 First UTF-8 string. Null is allowed.
2353 * @param psz2 Second string, 7-bit ASCII. Null is allowed.
2354 * @sa RTUtf16ICmpAscii
2356 RTDECL(int) RTStrICmpAscii(const char *psz1
, const char *psz2
);
2359 * Checks whether @a pszString starts with @a pszStart.
2361 * @returns true / false.
2362 * @param pszString The string to check.
2363 * @param pszStart The start string to check for.
2365 RTDECL(int) RTStrStartsWith(const char *pszString
, const char *pszStart
);
2368 * Checks whether @a pszString starts with @a pszStart, case insensitive.
2370 * @returns true / false.
2371 * @param pszString The string to check.
2372 * @param pszStart The start string to check for.
2374 RTDECL(int) RTStrIStartsWith(const char *pszString
, const char *pszStart
);
2377 * Locates a case sensitive substring.
2379 * If any of the two strings are NULL, then NULL is returned. If the needle is
2380 * an empty string, then the haystack is returned (i.e. matches anything).
2382 * @returns Pointer to the first occurrence of the substring if found, NULL if
2385 * @param pszHaystack The string to search.
2386 * @param pszNeedle The substring to search for.
2388 * @remarks The difference between this and strstr is the handling of NULL
2391 RTDECL(char *) RTStrStr(const char *pszHaystack
, const char *pszNeedle
);
2394 * Locates a case insensitive substring.
2396 * If any of the two strings are NULL, then NULL is returned. If the needle is
2397 * an empty string, then the haystack is returned (i.e. matches anything).
2399 * @returns Pointer to the first occurrence of the substring if found, NULL if
2402 * @param pszHaystack The string to search.
2403 * @param pszNeedle The substring to search for.
2406 RTDECL(char *) RTStrIStr(const char *pszHaystack
, const char *pszNeedle
);
2409 * Converts the string to lower case.
2411 * @returns Pointer to the converted string.
2412 * @param psz The string to convert.
2414 RTDECL(char *) RTStrToLower(char *psz
);
2417 * Converts the string to upper case.
2419 * @returns Pointer to the converted string.
2420 * @param psz The string to convert.
2422 RTDECL(char *) RTStrToUpper(char *psz
);
2425 * Checks if the string is case foldable, i.e. whether it would change if
2426 * subject to RTStrToLower or RTStrToUpper.
2428 * @returns true / false
2429 * @param psz The string in question.
2431 RTDECL(bool) RTStrIsCaseFoldable(const char *psz
);
2434 * Checks if the string is upper cased (no lower case chars in it).
2436 * @returns true / false
2437 * @param psz The string in question.
2439 RTDECL(bool) RTStrIsUpperCased(const char *psz
);
2442 * Checks if the string is lower cased (no upper case chars in it).
2444 * @returns true / false
2445 * @param psz The string in question.
2447 RTDECL(bool) RTStrIsLowerCased(const char *psz
);
2450 * Find the length of a zero-terminated byte string, given
2451 * a max string length.
2453 * See also RTStrNLenEx.
2455 * @returns The string length or cbMax. The returned length does not include
2456 * the zero terminator if it was found.
2458 * @param pszString The string.
2459 * @param cchMax The max string length.
2461 RTDECL(size_t) RTStrNLen(const char *pszString
, size_t cchMax
);
2464 * Find the length of a zero-terminated byte string, given
2465 * a max string length.
2467 * See also RTStrNLen.
2469 * @returns IPRT status code.
2470 * @retval VINF_SUCCESS if the string has a length less than cchMax.
2471 * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
2472 * before cchMax was reached.
2474 * @param pszString The string.
2475 * @param cchMax The max string length.
2476 * @param pcch Where to store the string length excluding the
2477 * terminator. This is set to cchMax if the terminator
2480 RTDECL(int) RTStrNLenEx(const char *pszString
, size_t cchMax
, size_t *pcch
);
2484 /** The maximum size argument of a memchr call. */
2485 #define RTSTR_MEMCHR_MAX ((~(size_t)0 >> 1) - 15)
2488 * Find the zero terminator in a string with a limited length.
2490 * @returns Pointer to the zero terminator.
2491 * @returns NULL if the zero terminator was not found.
2493 * @param pszString The string.
2494 * @param cchMax The max string length. RTSTR_MAX is fine.
2496 #if defined(__cplusplus) && !defined(DOXYGEN_RUNNING)
2497 DECLINLINE(char const *) RTStrEnd(char const *pszString
, size_t cchMax
)
2499 /* Avoid potential issues with memchr seen in glibc.
2500 * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
2501 while (cchMax
> RTSTR_MEMCHR_MAX
)
2503 char const *pszRet
= (char const *)memchr(pszString
, '\0', RTSTR_MEMCHR_MAX
);
2504 if (RT_LIKELY(pszRet
))
2506 pszString
+= RTSTR_MEMCHR_MAX
;
2507 cchMax
-= RTSTR_MEMCHR_MAX
;
2509 return (char const *)memchr(pszString
, '\0', cchMax
);
2512 DECLINLINE(char *) RTStrEnd(char *pszString
, size_t cchMax
)
2514 DECLINLINE(char *) RTStrEnd(const char *pszString
, size_t cchMax
)
2517 /* Avoid potential issues with memchr seen in glibc.
2518 * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
2519 while (cchMax
> RTSTR_MEMCHR_MAX
)
2521 char *pszRet
= (char *)memchr(pszString
, '\0', RTSTR_MEMCHR_MAX
);
2522 if (RT_LIKELY(pszRet
))
2524 pszString
+= RTSTR_MEMCHR_MAX
;
2525 cchMax
-= RTSTR_MEMCHR_MAX
;
2527 return (char *)memchr(pszString
, '\0', cchMax
);
2533 * Finds the offset at which a simple character first occurs in a string.
2535 * @returns The offset of the first occurence or the terminator offset.
2536 * @param pszHaystack The string to search.
2537 * @param chNeedle The character to search for.
2539 DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack
, char chNeedle
)
2541 const char *psz
= pszHaystack
;
2543 while ( (ch
= *psz
) != chNeedle
2546 return psz
- pszHaystack
;
2551 * Matches a simple string pattern.
2553 * @returns true if the string matches the pattern, otherwise false.
2555 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2556 * asterisk matches zero or more characters and question
2557 * mark matches exactly one character.
2558 * @param pszString The string to match against the pattern.
2560 RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern
, const char *pszString
);
2563 * Matches a simple string pattern, neither which needs to be zero terminated.
2565 * This is identical to RTStrSimplePatternMatch except that you can optionally
2566 * specify the length of both the pattern and the string. The function will
2567 * stop when it hits a string terminator or either of the lengths.
2569 * @returns true if the string matches the pattern, otherwise false.
2571 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2572 * asterisk matches zero or more characters and question
2573 * mark matches exactly one character.
2574 * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
2575 * length and wish to stop at the string terminator.
2576 * @param pszString The string to match against the pattern.
2577 * @param cchString The string length. Pass RTSTR_MAX if you don't know the
2578 * length and wish to match up to the string terminator.
2580 RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern
, size_t cchPattern
,
2581 const char *pszString
, size_t cchString
);
2584 * Matches multiple patterns against a string.
2586 * The patterns are separated by the pipe character (|).
2588 * @returns true if the string matches the pattern, otherwise false.
2590 * @param pszPatterns The patterns.
2591 * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
2592 * stop at the terminator.
2593 * @param pszString The string to match against the pattern.
2594 * @param cchString The string length. Pass RTSTR_MAX stop stop at the
2596 * @param poffPattern Offset into the patterns string of the patttern that
2597 * matched. If no match, this will be set to RTSTR_MAX.
2598 * This is optional, NULL is fine.
2600 RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns
, size_t cchPatterns
,
2601 const char *pszString
, size_t cchString
,
2602 size_t *poffPattern
);
2605 * Compares two version strings RTStrICmp fashion.
2607 * The version string is split up into sections at punctuation, spaces,
2608 * underscores, dashes and plus signs. The sections are then split up into
2609 * numeric and string sub-sections. Finally, the sub-sections are compared
2610 * in a numeric or case insesntivie fashion depending on what they are.
2612 * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
2613 * "1". These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
2615 * @returns < 0 if the first string less than the second string.
2616 * @returns 0 if the first string identical to the second string.
2617 * @returns > 0 if the first string greater than the second string.
2619 * @param pszVer1 First version string to compare.
2620 * @param pszVer2 Second version string to compare first version with.
2622 RTDECL(int) RTStrVersionCompare(const char *pszVer1
, const char *pszVer2
);
2625 /** @defgroup rt_str_conv String To/From Number Conversions
2629 * Converts a string representation of a number to a 64-bit unsigned number.
2631 * @returns iprt status code.
2632 * Warnings are used to indicate conversion problems.
2633 * @retval VWRN_NUMBER_TOO_BIG
2634 * @retval VWRN_NEGATIVE_UNSIGNED
2635 * @retval VWRN_TRAILING_CHARS
2636 * @retval VWRN_TRAILING_SPACES
2637 * @retval VINF_SUCCESS
2638 * @retval VERR_NO_DIGITS
2640 * @param pszValue Pointer to the string value.
2641 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2642 * @param uBase The base of the representation used.
2643 * If 0 the function will look for known prefixes before defaulting to 10.
2644 * @param pu64 Where to store the converted number. (optional)
2646 RTDECL(int) RTStrToUInt64Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint64_t *pu64
);
2649 * Converts a string representation of a number to a 64-bit unsigned number,
2650 * making sure the full string is converted.
2652 * @returns iprt status code.
2653 * Warnings are used to indicate conversion problems.
2654 * @retval VWRN_NUMBER_TOO_BIG
2655 * @retval VWRN_NEGATIVE_UNSIGNED
2656 * @retval VINF_SUCCESS
2657 * @retval VERR_NO_DIGITS
2658 * @retval VERR_TRAILING_SPACES
2659 * @retval VERR_TRAILING_CHARS
2661 * @param pszValue Pointer to the string value.
2662 * @param uBase The base of the representation used.
2663 * If 0 the function will look for known prefixes before defaulting to 10.
2664 * @param pu64 Where to store the converted number. (optional)
2666 RTDECL(int) RTStrToUInt64Full(const char *pszValue
, unsigned uBase
, uint64_t *pu64
);
2669 * Converts a string representation of a number to a 64-bit unsigned number.
2670 * The base is guessed.
2672 * @returns 64-bit unsigned number on success.
2673 * @returns 0 on failure.
2674 * @param pszValue Pointer to the string value.
2676 RTDECL(uint64_t) RTStrToUInt64(const char *pszValue
);
2679 * Converts a string representation of a number to a 32-bit unsigned number.
2681 * @returns iprt status code.
2682 * Warnings are used to indicate conversion problems.
2683 * @retval VWRN_NUMBER_TOO_BIG
2684 * @retval VWRN_NEGATIVE_UNSIGNED
2685 * @retval VWRN_TRAILING_CHARS
2686 * @retval VWRN_TRAILING_SPACES
2687 * @retval VINF_SUCCESS
2688 * @retval VERR_NO_DIGITS
2690 * @param pszValue Pointer to the string value.
2691 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2692 * @param uBase The base of the representation used.
2693 * If 0 the function will look for known prefixes before defaulting to 10.
2694 * @param pu32 Where to store the converted number. (optional)
2696 RTDECL(int) RTStrToUInt32Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint32_t *pu32
);
2699 * Converts a string representation of a number to a 32-bit unsigned number,
2700 * making sure the full string is converted.
2702 * @returns iprt status code.
2703 * Warnings are used to indicate conversion problems.
2704 * @retval VWRN_NUMBER_TOO_BIG
2705 * @retval VWRN_NEGATIVE_UNSIGNED
2706 * @retval VINF_SUCCESS
2707 * @retval VERR_NO_DIGITS
2708 * @retval VERR_TRAILING_SPACES
2709 * @retval VERR_TRAILING_CHARS
2711 * @param pszValue Pointer to the string value.
2712 * @param uBase The base of the representation used.
2713 * If 0 the function will look for known prefixes before defaulting to 10.
2714 * @param pu32 Where to store the converted number. (optional)
2716 RTDECL(int) RTStrToUInt32Full(const char *pszValue
, unsigned uBase
, uint32_t *pu32
);
2719 * Converts a string representation of a number to a 64-bit unsigned number.
2720 * The base is guessed.
2722 * @returns 32-bit unsigned number on success.
2723 * @returns 0 on failure.
2724 * @param pszValue Pointer to the string value.
2726 RTDECL(uint32_t) RTStrToUInt32(const char *pszValue
);
2729 * Converts a string representation of a number to a 16-bit unsigned number.
2731 * @returns iprt status code.
2732 * Warnings are used to indicate conversion problems.
2733 * @retval VWRN_NUMBER_TOO_BIG
2734 * @retval VWRN_NEGATIVE_UNSIGNED
2735 * @retval VWRN_TRAILING_CHARS
2736 * @retval VWRN_TRAILING_SPACES
2737 * @retval VINF_SUCCESS
2738 * @retval VERR_NO_DIGITS
2740 * @param pszValue Pointer to the string value.
2741 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2742 * @param uBase The base of the representation used.
2743 * If 0 the function will look for known prefixes before defaulting to 10.
2744 * @param pu16 Where to store the converted number. (optional)
2746 RTDECL(int) RTStrToUInt16Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint16_t *pu16
);
2749 * Converts a string representation of a number to a 16-bit unsigned number,
2750 * making sure the full string is converted.
2752 * @returns iprt status code.
2753 * Warnings are used to indicate conversion problems.
2754 * @retval VWRN_NUMBER_TOO_BIG
2755 * @retval VWRN_NEGATIVE_UNSIGNED
2756 * @retval VINF_SUCCESS
2757 * @retval VERR_NO_DIGITS
2758 * @retval VERR_TRAILING_SPACES
2759 * @retval VERR_TRAILING_CHARS
2761 * @param pszValue Pointer to the string value.
2762 * @param uBase The base of the representation used.
2763 * If 0 the function will look for known prefixes before defaulting to 10.
2764 * @param pu16 Where to store the converted number. (optional)
2766 RTDECL(int) RTStrToUInt16Full(const char *pszValue
, unsigned uBase
, uint16_t *pu16
);
2769 * Converts a string representation of a number to a 16-bit unsigned number.
2770 * The base is guessed.
2772 * @returns 16-bit unsigned number on success.
2773 * @returns 0 on failure.
2774 * @param pszValue Pointer to the string value.
2776 RTDECL(uint16_t) RTStrToUInt16(const char *pszValue
);
2779 * Converts a string representation of a number to a 8-bit unsigned number.
2781 * @returns iprt status code.
2782 * Warnings are used to indicate conversion problems.
2783 * @retval VWRN_NUMBER_TOO_BIG
2784 * @retval VWRN_NEGATIVE_UNSIGNED
2785 * @retval VWRN_TRAILING_CHARS
2786 * @retval VWRN_TRAILING_SPACES
2787 * @retval VINF_SUCCESS
2788 * @retval VERR_NO_DIGITS
2790 * @param pszValue Pointer to the string value.
2791 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2792 * @param uBase The base of the representation used.
2793 * If 0 the function will look for known prefixes before defaulting to 10.
2794 * @param pu8 Where to store the converted number. (optional)
2796 RTDECL(int) RTStrToUInt8Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, uint8_t *pu8
);
2799 * Converts a string representation of a number to a 8-bit unsigned number,
2800 * making sure the full string is converted.
2802 * @returns iprt status code.
2803 * Warnings are used to indicate conversion problems.
2804 * @retval VWRN_NUMBER_TOO_BIG
2805 * @retval VWRN_NEGATIVE_UNSIGNED
2806 * @retval VINF_SUCCESS
2807 * @retval VERR_NO_DIGITS
2808 * @retval VERR_TRAILING_SPACES
2809 * @retval VERR_TRAILING_CHARS
2811 * @param pszValue Pointer to the string value.
2812 * @param uBase The base of the representation used.
2813 * If 0 the function will look for known prefixes before defaulting to 10.
2814 * @param pu8 Where to store the converted number. (optional)
2816 RTDECL(int) RTStrToUInt8Full(const char *pszValue
, unsigned uBase
, uint8_t *pu8
);
2819 * Converts a string representation of a number to a 8-bit unsigned number.
2820 * The base is guessed.
2822 * @returns 8-bit unsigned number on success.
2823 * @returns 0 on failure.
2824 * @param pszValue Pointer to the string value.
2826 RTDECL(uint8_t) RTStrToUInt8(const char *pszValue
);
2829 * Converts a string representation of a number to a 64-bit signed number.
2831 * @returns iprt status code.
2832 * Warnings are used to indicate conversion problems.
2833 * @retval VWRN_NUMBER_TOO_BIG
2834 * @retval VWRN_TRAILING_CHARS
2835 * @retval VWRN_TRAILING_SPACES
2836 * @retval VINF_SUCCESS
2837 * @retval VERR_NO_DIGITS
2839 * @param pszValue Pointer to the string value.
2840 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2841 * @param uBase The base of the representation used.
2842 * If 0 the function will look for known prefixes before defaulting to 10.
2843 * @param pi64 Where to store the converted number. (optional)
2845 RTDECL(int) RTStrToInt64Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int64_t *pi64
);
2848 * Converts a string representation of a number to a 64-bit signed number,
2849 * making sure the full string is converted.
2851 * @returns iprt status code.
2852 * Warnings are used to indicate conversion problems.
2853 * @retval VWRN_NUMBER_TOO_BIG
2854 * @retval VINF_SUCCESS
2855 * @retval VERR_TRAILING_CHARS
2856 * @retval VERR_TRAILING_SPACES
2857 * @retval VERR_NO_DIGITS
2859 * @param pszValue Pointer to the string value.
2860 * @param uBase The base of the representation used.
2861 * If 0 the function will look for known prefixes before defaulting to 10.
2862 * @param pi64 Where to store the converted number. (optional)
2864 RTDECL(int) RTStrToInt64Full(const char *pszValue
, unsigned uBase
, int64_t *pi64
);
2867 * Converts a string representation of a number to a 64-bit signed number.
2868 * The base is guessed.
2870 * @returns 64-bit signed number on success.
2871 * @returns 0 on failure.
2872 * @param pszValue Pointer to the string value.
2874 RTDECL(int64_t) RTStrToInt64(const char *pszValue
);
2877 * Converts a string representation of a number to a 32-bit signed number.
2879 * @returns iprt status code.
2880 * Warnings are used to indicate conversion problems.
2881 * @retval VWRN_NUMBER_TOO_BIG
2882 * @retval VWRN_TRAILING_CHARS
2883 * @retval VWRN_TRAILING_SPACES
2884 * @retval VINF_SUCCESS
2885 * @retval VERR_NO_DIGITS
2887 * @param pszValue Pointer to the string value.
2888 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2889 * @param uBase The base of the representation used.
2890 * If 0 the function will look for known prefixes before defaulting to 10.
2891 * @param pi32 Where to store the converted number. (optional)
2893 RTDECL(int) RTStrToInt32Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int32_t *pi32
);
2896 * Converts a string representation of a number to a 32-bit signed number,
2897 * making sure the full string is converted.
2899 * @returns iprt status code.
2900 * Warnings are used to indicate conversion problems.
2901 * @retval VWRN_NUMBER_TOO_BIG
2902 * @retval VINF_SUCCESS
2903 * @retval VERR_TRAILING_CHARS
2904 * @retval VERR_TRAILING_SPACES
2905 * @retval VERR_NO_DIGITS
2907 * @param pszValue Pointer to the string value.
2908 * @param uBase The base of the representation used.
2909 * If 0 the function will look for known prefixes before defaulting to 10.
2910 * @param pi32 Where to store the converted number. (optional)
2912 RTDECL(int) RTStrToInt32Full(const char *pszValue
, unsigned uBase
, int32_t *pi32
);
2915 * Converts a string representation of a number to a 32-bit signed number.
2916 * The base is guessed.
2918 * @returns 32-bit signed number on success.
2919 * @returns 0 on failure.
2920 * @param pszValue Pointer to the string value.
2922 RTDECL(int32_t) RTStrToInt32(const char *pszValue
);
2925 * Converts a string representation of a number to a 16-bit signed number.
2927 * @returns iprt status code.
2928 * Warnings are used to indicate conversion problems.
2929 * @retval VWRN_NUMBER_TOO_BIG
2930 * @retval VWRN_TRAILING_CHARS
2931 * @retval VWRN_TRAILING_SPACES
2932 * @retval VINF_SUCCESS
2933 * @retval VERR_NO_DIGITS
2935 * @param pszValue Pointer to the string value.
2936 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2937 * @param uBase The base of the representation used.
2938 * If 0 the function will look for known prefixes before defaulting to 10.
2939 * @param pi16 Where to store the converted number. (optional)
2941 RTDECL(int) RTStrToInt16Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int16_t *pi16
);
2944 * Converts a string representation of a number to a 16-bit signed number,
2945 * making sure the full string is converted.
2947 * @returns iprt status code.
2948 * Warnings are used to indicate conversion problems.
2949 * @retval VWRN_NUMBER_TOO_BIG
2950 * @retval VINF_SUCCESS
2951 * @retval VERR_TRAILING_CHARS
2952 * @retval VERR_TRAILING_SPACES
2953 * @retval VERR_NO_DIGITS
2955 * @param pszValue Pointer to the string value.
2956 * @param uBase The base of the representation used.
2957 * If 0 the function will look for known prefixes before defaulting to 10.
2958 * @param pi16 Where to store the converted number. (optional)
2960 RTDECL(int) RTStrToInt16Full(const char *pszValue
, unsigned uBase
, int16_t *pi16
);
2963 * Converts a string representation of a number to a 16-bit signed number.
2964 * The base is guessed.
2966 * @returns 16-bit signed number on success.
2967 * @returns 0 on failure.
2968 * @param pszValue Pointer to the string value.
2970 RTDECL(int16_t) RTStrToInt16(const char *pszValue
);
2973 * Converts a string representation of a number to a 8-bit signed number.
2975 * @returns iprt status code.
2976 * Warnings are used to indicate conversion problems.
2977 * @retval VWRN_NUMBER_TOO_BIG
2978 * @retval VWRN_TRAILING_CHARS
2979 * @retval VWRN_TRAILING_SPACES
2980 * @retval VINF_SUCCESS
2981 * @retval VERR_NO_DIGITS
2983 * @param pszValue Pointer to the string value.
2984 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
2985 * @param uBase The base of the representation used.
2986 * If 0 the function will look for known prefixes before defaulting to 10.
2987 * @param pi8 Where to store the converted number. (optional)
2989 RTDECL(int) RTStrToInt8Ex(const char *pszValue
, char **ppszNext
, unsigned uBase
, int8_t *pi8
);
2992 * Converts a string representation of a number to a 8-bit signed number,
2993 * making sure the full string is converted.
2995 * @returns iprt status code.
2996 * Warnings are used to indicate conversion problems.
2997 * @retval VWRN_NUMBER_TOO_BIG
2998 * @retval VINF_SUCCESS
2999 * @retval VERR_TRAILING_CHARS
3000 * @retval VERR_TRAILING_SPACES
3001 * @retval VERR_NO_DIGITS
3003 * @param pszValue Pointer to the string value.
3004 * @param uBase The base of the representation used.
3005 * If 0 the function will look for known prefixes before defaulting to 10.
3006 * @param pi8 Where to store the converted number. (optional)
3008 RTDECL(int) RTStrToInt8Full(const char *pszValue
, unsigned uBase
, int8_t *pi8
);
3011 * Converts a string representation of a number to a 8-bit signed number.
3012 * The base is guessed.
3014 * @returns 8-bit signed number on success.
3015 * @returns 0 on failure.
3016 * @param pszValue Pointer to the string value.
3018 RTDECL(int8_t) RTStrToInt8(const char *pszValue
);
3021 * Formats a buffer stream as hex bytes.
3023 * The default is no separating spaces or line breaks or anything.
3025 * @returns IPRT status code.
3026 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
3027 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
3029 * @param pszBuf Output string buffer.
3030 * @param cbBuf The size of the output buffer.
3031 * @param pv Pointer to the bytes to stringify.
3032 * @param cb The number of bytes to stringify.
3033 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
3034 * @sa RTUtf16PrintHexBytes.
3036 RTDECL(int) RTStrPrintHexBytes(char *pszBuf
, size_t cbBuf
, void const *pv
, size_t cb
, uint32_t fFlags
);
3037 /** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
3039 /** Upper case hex digits, the default is lower case. */
3040 #define RTSTRPRINTHEXBYTES_F_UPPER RT_BIT(0)
3041 /** Add a space between each group. */
3042 #define RTSTRPRINTHEXBYTES_F_SEP_SPACE RT_BIT(1)
3043 /** Add a colon between each group. */
3044 #define RTSTRPRINTHEXBYTES_F_SEP_COLON RT_BIT(2)
3048 * Converts a string of hex bytes back into binary data.
3050 * @returns IPRT status code.
3051 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
3052 * @retval VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
3053 * @retval VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
3054 * the output buffer.
3055 * @retval VERR_UNEVEN_INPUT if the input contains a half byte.
3056 * @retval VERR_NO_DIGITS
3057 * @retval VWRN_TRAILING_CHARS
3058 * @retval VWRN_TRAILING_SPACES
3060 * @param pszHex The string containing the hex bytes.
3061 * @param pv Output buffer.
3062 * @param cb The size of the output buffer.
3063 * @param fFlags Must be zero, reserved for future use.
3065 RTDECL(int) RTStrConvertHexBytes(char const *pszHex
, void *pv
, size_t cb
, uint32_t fFlags
);
3070 /** @defgroup rt_str_space Unique String Space
3074 /** Pointer to a string name space container node core. */
3075 typedef struct RTSTRSPACECORE
*PRTSTRSPACECORE
;
3076 /** Pointer to a pointer to a string name space container node core. */
3077 typedef PRTSTRSPACECORE
*PPRTSTRSPACECORE
;
3080 * String name space container node core.
3082 typedef struct RTSTRSPACECORE
3084 /** Hash key. Don't touch. */
3086 /** Pointer to the left leaf node. Don't touch. */
3087 PRTSTRSPACECORE pLeft
;
3088 /** Pointer to the left right node. Don't touch. */
3089 PRTSTRSPACECORE pRight
;
3090 /** Pointer to the list of string with the same key. Don't touch. */
3091 PRTSTRSPACECORE pList
;
3092 /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
3093 unsigned char uchHeight
;
3094 /** The string length. Read only! */
3096 /** Pointer to the string. Read only! */
3097 const char *pszString
;
3100 /** String space. (Initialize with NULL.) */
3101 typedef PRTSTRSPACECORE RTSTRSPACE
;
3102 /** Pointer to a string space. */
3103 typedef PPRTSTRSPACECORE PRTSTRSPACE
;
3107 * Inserts a string into a unique string space.
3109 * @returns true on success.
3110 * @returns false if the string collided with an existing string.
3111 * @param pStrSpace The space to insert it into.
3112 * @param pStr The string node.
3114 RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace
, PRTSTRSPACECORE pStr
);
3117 * Removes a string from a unique string space.
3119 * @returns Pointer to the removed string node.
3120 * @returns NULL if the string was not found in the string space.
3121 * @param pStrSpace The space to remove it from.
3122 * @param pszString The string to remove.
3124 RTDECL(PRTSTRSPACECORE
) RTStrSpaceRemove(PRTSTRSPACE pStrSpace
, const char *pszString
);
3127 * Gets a string from a unique string space.
3129 * @returns Pointer to the string node.
3130 * @returns NULL if the string was not found in the string space.
3131 * @param pStrSpace The space to get it from.
3132 * @param pszString The string to get.
3134 RTDECL(PRTSTRSPACECORE
) RTStrSpaceGet(PRTSTRSPACE pStrSpace
, const char *pszString
);
3137 * Gets a string from a unique string space.
3139 * @returns Pointer to the string node.
3140 * @returns NULL if the string was not found in the string space.
3141 * @param pStrSpace The space to get it from.
3142 * @param pszString The string to get.
3143 * @param cchMax The max string length to evaluate. Passing
3144 * RTSTR_MAX is ok and makes it behave just like
3147 RTDECL(PRTSTRSPACECORE
) RTStrSpaceGetN(PRTSTRSPACE pStrSpace
, const char *pszString
, size_t cchMax
);
3150 * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
3152 * @returns 0 on continue.
3153 * @returns Non-zero to aborts the operation.
3154 * @param pStr The string node
3155 * @param pvUser The user specified argument.
3157 typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr
, void *pvUser
);
3158 /** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
3159 typedef FNRTSTRSPACECALLBACK
*PFNRTSTRSPACECALLBACK
;
3162 * Destroys the string space.
3164 * The caller supplies a callback which will be called for each of the string
3165 * nodes in for freeing their memory and other resources.
3167 * @returns 0 or what ever non-zero return value pfnCallback returned
3168 * when aborting the destruction.
3169 * @param pStrSpace The space to destroy.
3170 * @param pfnCallback The callback.
3171 * @param pvUser The user argument.
3173 RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace
, PFNRTSTRSPACECALLBACK pfnCallback
, void *pvUser
);
3176 * Enumerates the string space.
3177 * The caller supplies a callback which will be called for each of
3180 * @returns 0 or what ever non-zero return value pfnCallback returned
3181 * when aborting the destruction.
3182 * @param pStrSpace The space to enumerate.
3183 * @param pfnCallback The callback.
3184 * @param pvUser The user argument.
3186 RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace
, PFNRTSTRSPACECALLBACK pfnCallback
, void *pvUser
);
3191 /** @defgroup rt_str_hash Sting hashing
3195 * Hashes the given string using algorithm \#1.
3197 * @returns String hash.
3198 * @param pszString The string to hash.
3200 RTDECL(uint32_t) RTStrHash1(const char *pszString
);
3203 * Hashes the given string using algorithm \#1.
3205 * @returns String hash.
3206 * @param pszString The string to hash.
3207 * @param cchString The max length to hash. Hashing will stop if the
3208 * terminator character is encountered first. Passing
3209 * RTSTR_MAX is fine.
3211 RTDECL(uint32_t) RTStrHash1N(const char *pszString
, size_t cchString
);
3214 * Hashes the given strings as if they were concatenated using algorithm \#1.
3216 * @returns String hash.
3217 * @param cPairs The number of string / length pairs in the
3219 * @param ... List of string (const char *) and length
3220 * (size_t) pairs. Passing RTSTR_MAX as the size is
3223 RTDECL(uint32_t) RTStrHash1ExN(size_t cPairs
, ...);
3226 * Hashes the given strings as if they were concatenated using algorithm \#1.
3228 * @returns String hash.
3229 * @param cPairs The number of string / length pairs in the @a va.
3230 * @param va List of string (const char *) and length
3231 * (size_t) pairs. Passing RTSTR_MAX as the size is
3234 RTDECL(uint32_t) RTStrHash1ExNV(size_t cPairs
, va_list va
);