VirtualBox

source: vbox/trunk/include/iprt/string.h@ 103224

Last change on this file since 103224 was 103024, checked in by vboxsync, 8 months ago

iprt/string.h,VBoxGuest-linux.c,linux/sharedfolders/vfsmod.c: Replaced the very few RT_STRSCPY uses with RTStrCopy and removed the macro. bugref:10584

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 157.2 KB
Line 
1/** @file
2 * IPRT - String Manipulation.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_string_h
37#define IPRT_INCLUDED_string_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/assert.h>
45#include <iprt/stdarg.h>
46#include <iprt/errcore.h> /* for VINF_SUCCESS */
47#if defined(RT_OS_LINUX) && defined(__KERNEL__)
48 /* no C++ hacks ('new' etc) here anymore! */
49# include <linux/string.h>
50# include <iprt/linux/version.h>
51
52#elif defined(IN_XF86_MODULE) && !defined(NO_ANSIC)
53 RT_C_DECLS_BEGIN
54# include "xf86_ansic.h"
55 RT_C_DECLS_END
56
57#elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
58 RT_C_DECLS_BEGIN
59# include <sys/libkern.h>
60 RT_C_DECLS_END
61
62#elif defined(RT_OS_NETBSD) && defined(_KERNEL)
63 RT_C_DECLS_BEGIN
64# include <lib/libkern/libkern.h>
65 RT_C_DECLS_END
66
67#elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
68 /*
69 * Same case as with FreeBSD kernel:
70 * The string.h stuff clashes with sys/system.h
71 * ffs = find first set bit.
72 */
73# define ffs ffs_string_h
74# define fls fls_string_h
75# include <string.h>
76# undef fls
77# undef ffs
78# undef strpbrk
79
80#else
81# include <string.h>
82#endif
83
84/*
85 * Supply prototypes for standard string functions provided by
86 * IPRT instead of the operating environment.
87 */
88#if defined(RT_OS_DARWIN) && defined(KERNEL)
89RT_C_DECLS_BEGIN
90void *memchr(const void *pv, int ch, size_t cb);
91char *strpbrk(const char *pszStr, const char *pszChars);
92RT_C_DECLS_END
93#endif
94
95#if defined(RT_OS_FREEBSD) && defined(_KERNEL)
96RT_C_DECLS_BEGIN
97char *strpbrk(const char *pszStr, const char *pszChars);
98RT_C_DECLS_END
99#endif
100
101#if defined(RT_OS_NETBSD) && defined(_KERNEL)
102RT_C_DECLS_BEGIN
103char *strpbrk(const char *pszStr, const char *pszChars);
104RT_C_DECLS_END
105#endif
106
107#if (defined(RT_OS_DARWIN) || defined(RT_OS_SOLARIS) || defined(RT_OS_WINDOWS)) && !defined(IPRT_NO_CRT)
108RT_C_DECLS_BEGIN
109# if !defined(RT_OS_DARWIN) || RT_CLANG_PREREQ(7 /* whatever post gcc-4.2 */, 0)
110RTDECL(void *) mempcpy(void *pvDst, const void *pvSrc, size_t cb);
111# else
112void *mempcpy(void *pvDst, const void *pvSrc, size_t cb);
113# endif
114RT_C_DECLS_END
115#endif
116
117#if (!defined(RT_OS_LINUX) || !defined(_GNU_SOURCE)) \
118 && (!defined(RT_OS_OS2) || !defined(_GNU_SOURCE)) \
119 && !defined(RT_OS_FREEBSD) \
120 && !defined(RT_OS_NETBSD)
121RT_C_DECLS_BEGIN
122void *memrchr(const void *pv, int ch, size_t cb);
123RT_C_DECLS_END
124#endif
125
126
127/** @def RT_USE_RTC_3629
128 * When defined the UTF-8 range will stop at 0x10ffff. If not defined, the
129 * range stops at 0x7fffffff.
130 * @remarks Must be defined both when building and using the IPRT. */
131#ifdef DOXYGEN_RUNNING
132# define RT_USE_RTC_3629
133#endif
134
135
136/** @defgroup grp_rt_str RTStr - String Manipulation
137 * Mostly UTF-8 related helpers where the standard string functions won't do.
138 * @ingroup grp_rt
139 * @{
140 */
141
142RT_C_DECLS_BEGIN
143
144
145/**
146 * The maximum string length.
147 */
148#define RTSTR_MAX (~(size_t)0)
149
150
151/** @def RTSTR_TAG
152 * The default allocation tag used by the RTStr allocation APIs.
153 *
154 * When not defined before the inclusion of iprt/string.h, this will default to
155 * the pointer to the current file name. The string API will make of use of
156 * this as pointer to a volatile but read-only string.
157 */
158#if !defined(RTSTR_TAG) || defined(DOXYGEN_RUNNING)
159# define RTSTR_TAG (__FILE__)
160#endif
161
162
163/**
164 * Byte zero the specified object.
165 *
166 * This will use sizeof(Obj) to figure the size and will call memset, bzero
167 * or some compiler intrinsic to perform the actual zeroing.
168 *
169 * @param Obj The object to zero. Make sure to dereference pointers.
170 *
171 * @remarks Because the macro may use memset it has been placed in string.h
172 * instead of cdefs.h to avoid build issues because someone forgot
173 * to include this header.
174 *
175 * @ingroup grp_rt_cdefs
176 */
177#define RT_ZERO(Obj) RT_BZERO(&(Obj), sizeof(Obj))
178
179/**
180 * Byte zero the specified memory area.
181 *
182 * This will call memset, bzero or some compiler intrinsic to clear the
183 * specified bytes of memory.
184 *
185 * @param pv Pointer to the memory.
186 * @param cb The number of bytes to clear. Please, don't pass 0.
187 *
188 * @remarks Because the macro may use memset it has been placed in string.h
189 * instead of cdefs.h to avoid build issues because someone forgot
190 * to include this header.
191 *
192 * @ingroup grp_rt_cdefs
193 */
194#define RT_BZERO(pv, cb) do { memset((pv), 0, cb); } while (0)
195
196
197/**
198 * For copying a volatile variable to a non-volatile one.
199 * @param a_Dst The non-volatile destination variable.
200 * @param a_VolatileSrc The volatile source variable / dereferenced pointer.
201 */
202#define RT_COPY_VOLATILE(a_Dst, a_VolatileSrc) \
203 do { \
204 void const volatile *a_pvVolatileSrc_BCopy_Volatile = &(a_VolatileSrc); \
205 AssertCompile(sizeof(a_Dst) == sizeof(a_VolatileSrc)); \
206 memcpy(&(a_Dst), (void const *)a_pvVolatileSrc_BCopy_Volatile, sizeof(a_Dst)); \
207 } while (0)
208
209/**
210 * For copy a number of bytes from a volatile buffer to a non-volatile one.
211 *
212 * @param a_pDst Pointer to the destination buffer.
213 * @param a_pVolatileSrc Pointer to the volatile source buffer.
214 * @param a_cbToCopy Number of bytes to copy.
215 */
216#define RT_BCOPY_VOLATILE(a_pDst, a_pVolatileSrc, a_cbToCopy) \
217 do { \
218 void const volatile *a_pvVolatileSrc_BCopy_Volatile = (a_pVolatileSrc); \
219 memcpy((a_pDst), (void const *)a_pvVolatileSrc_BCopy_Volatile, (a_cbToCopy)); \
220 } while (0)
221
222/** @def RT_BCOPY_UNFORTIFIED
223 * For copying a number of bytes from/to variable length structures.
224 *
225 * This is for working around false positives ("field-spanning writes") in the
226 * linux kernel's fortified memcpy (v5.18+) when copying from/to
227 * RT_FLEXIBLE_ARRAY fields and similar tricks going beyond the strict
228 * definition of a target or source structure.
229 *
230 * @param a_pDst Pointer to the destination buffer.
231 * @param a_pSrc Pointer to the source buffer.
232 * @param a_cbToCopy Number of bytes to copy.
233 * @see @bugref{10209}, @ticketref{21410}
234 */
235#if defined(RT_OS_LINUX) && defined(__KERNEL__)
236# if (RTLNX_VER_MIN(5,18,0) || RTLNX_RHEL_RANGE(9,3, 9,99)) \
237 && !defined(__NO_FORTIFY) \
238 && defined(__OPTIMIZE__) \
239 && defined(CONFIG_FORTIFY_SOURCE)
240# define RT_BCOPY_UNFORTIFIED(a_pDst, a_pSrc, a_cbToCopy) __underlying_memcpy((a_pDst), (a_pSrc), (a_cbToCopy))
241# else
242# define RT_BCOPY_UNFORTIFIED(a_pDst, a_pSrc, a_cbToCopy) memcpy((a_pDst), (a_pSrc), (a_cbToCopy))
243# endif
244#else /* !RT_OS_LINUX && !__KERNEL__ */
245# define RT_BCOPY_UNFORTIFIED(a_pDst, a_pSrc, a_cbToCopy) memcpy((a_pDst), (a_pSrc), (a_cbToCopy))
246#endif /* !RT_OS_LINUX && !__KERNEL__ */
247
248
249#ifdef IN_RING3
250
251/**
252 * Allocates tmp buffer with default tag, translates pszString from UTF8 to
253 * current codepage.
254 *
255 * @returns iprt status code.
256 * @param ppszString Receives pointer of allocated native CP string.
257 * The returned pointer must be freed using RTStrFree().
258 * @param pszString UTF-8 string to convert.
259 */
260#define RTStrUtf8ToCurrentCP(ppszString, pszString) RTStrUtf8ToCurrentCPTag((ppszString), (pszString), RTSTR_TAG)
261
262/**
263 * Allocates tmp buffer with custom tag, translates pszString from UTF-8 to
264 * current codepage.
265 *
266 * @returns iprt status code.
267 * @param ppszString Receives pointer of allocated native CP string.
268 * The returned pointer must be freed using
269 * RTStrFree()., const char *pszTag
270 * @param pszString UTF-8 string to convert.
271 * @param pszTag Allocation tag used for statistics and such.
272 */
273RTR3DECL(int) RTStrUtf8ToCurrentCPTag(char **ppszString, const char *pszString, const char *pszTag);
274
275/**
276 * Allocates tmp buffer with default tag, translates pszString from UTF-8 to
277 * current codepage, extended version.
278 *
279 * @returns iprt status code.
280 * @param ppszString Receives pointer of allocated native CP string.
281 * The returned pointer must be freed using RTStrFree().
282 * @param pszString UTF-8 string to convert.
283 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
284 * when it reaches cchString or the string terminator ('\\0').
285 * Use RTSTR_MAX to translate the entire string.
286 */
287#define RTStrUtf8ToCurrentCPEx(ppszString, pszString, cchString) \
288 RTStrUtf8ToCurrentCPExTag((ppszString), (pszString), (cchString), RTSTR_TAG)
289
290/**
291 * Allocates tmp buffer with custom tag, translates pszString from UTF8 to
292 * current codepage.
293 *
294 * @returns iprt status code.
295 * @param ppszString Receives pointer of allocated native CP string.
296 * The returned pointer must be freed using
297 * RTStrFree()., const char *pszTag
298 * @param pszString UTF-8 string to convert.
299 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
300 * when it reaches cchString or the string terminator ('\\0').
301 * Use RTSTR_MAX to translate the entire string.
302 * @param pszTag Allocation tag used for statistics and such.
303 */
304RTR3DECL(int) RTStrUtf8ToCurrentCPExTag(char **ppszString, const char *pszString, size_t cchString, const char *pszTag);
305
306/**
307 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
308 *
309 * @returns iprt status code.
310 * @param ppszString Receives pointer of allocated UTF-8 string.
311 * The returned pointer must be freed using RTStrFree().
312 * @param pszString Native string to convert.
313 */
314#define RTStrCurrentCPToUtf8(ppszString, pszString) RTStrCurrentCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
315
316/**
317 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
318 *
319 * @returns iprt status code.
320 * @param ppszString Receives pointer of allocated UTF-8 string.
321 * The returned pointer must be freed using RTStrFree().
322 * @param pszString Native string to convert.
323 * @param pszTag Allocation tag used for statistics and such.
324 */
325RTR3DECL(int) RTStrCurrentCPToUtf8Tag(char **ppszString, const char *pszString, const char *pszTag);
326
327/**
328 * Allocates tmp buffer, translates pszString from console codepage to UTF-8.
329 *
330 * @returns iprt status code.
331 * @param ppszString Receives pointer of allocated UTF-8 string.
332 * The returned pointer must be freed using RTStrFree().
333 * @param pszString Native string to convert.
334 */
335#define RTStrConsoleCPToUtf8(ppszString, pszString) RTStrConsoleCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
336
337/**
338 * Allocates tmp buffer, translates pszString from console codepage to UTF-8.
339 *
340 * @returns iprt status code.
341 * @param ppszString Receives pointer of allocated UTF-8 string.
342 * The returned pointer must be freed using RTStrFree().
343 * @param pszString Native string to convert.
344 * @param pszTag Allocation tag used for statistics and such.
345 */
346RTR3DECL(int) RTStrConsoleCPToUtf8Tag(char **ppszString, const char *pszString, const char *pszTag);
347
348#endif /* IN_RING3 */
349
350/**
351 * Free string allocated by any of the non-UCS-2 string functions.
352 *
353 * @param pszString Pointer to buffer with string to free.
354 * NULL is accepted.
355 */
356RTDECL(void) RTStrFree(char *pszString);
357
358/**
359 * Allocates a new copy of the given UTF-8 string (default tag).
360 *
361 * @returns Pointer to the allocated UTF-8 string.
362 * @param pszString UTF-8 string to duplicate.
363 */
364#define RTStrDup(pszString) RTStrDupTag((pszString), RTSTR_TAG)
365
366/**
367 * Allocates a new copy of the given UTF-8 string (custom tag).
368 *
369 * @returns Pointer to the allocated UTF-8 string.
370 * @param pszString UTF-8 string to duplicate.
371 * @param pszTag Allocation tag used for statistics and such.
372 */
373RTDECL(char *) RTStrDupTag(const char *pszString, const char *pszTag);
374
375/**
376 * Allocates a new copy of the given UTF-8 string (default tag).
377 *
378 * @returns iprt status code.
379 * @param ppszCopy Receives pointer of the allocated UTF-8 string.
380 * The returned pointer must be freed using RTStrFree().
381 * @param pszString UTF-8 string to duplicate.
382 */
383#define RTStrDupEx(ppszCopy, pszString) RTStrDupExTag((ppszCopy), (pszString), RTSTR_TAG)
384
385/**
386 * Allocates a new copy of the given UTF-8 string (custom tag).
387 *
388 * @returns iprt status code.
389 * @param ppszCopy Receives pointer of the allocated UTF-8 string.
390 * The returned pointer must be freed using RTStrFree().
391 * @param pszString UTF-8 string to duplicate.
392 * @param pszTag Allocation tag used for statistics and such.
393 */
394RTDECL(int) RTStrDupExTag(char **ppszCopy, const char *pszString, const char *pszTag);
395
396/**
397 * Allocates a new copy of the given UTF-8 substring (default tag).
398 *
399 * @returns Pointer to the allocated UTF-8 substring.
400 * @param pszString UTF-8 string to duplicate.
401 * @param cchMax The max number of chars to duplicate, not counting
402 * the terminator.
403 */
404#define RTStrDupN(pszString, cchMax) RTStrDupNTag((pszString), (cchMax), RTSTR_TAG)
405
406/**
407 * Allocates a new copy of the given UTF-8 substring (custom tag).
408 *
409 * @returns Pointer to the allocated UTF-8 substring.
410 * @param pszString UTF-8 string to duplicate.
411 * @param cchMax The max number of chars to duplicate, not counting
412 * the terminator.
413 * @param pszTag Allocation tag used for statistics and such.
414 */
415RTDECL(char *) RTStrDupNTag(const char *pszString, size_t cchMax, const char *pszTag);
416
417/**
418 * Allocates a new copy of the given UTF-8 substring (default tag).
419 *
420 * @returns iprt status code (VINF_SUCCESS or VERR_NO_STR_MEMORY).
421 * @param ppszCopy Receives pointer of the allocated UTF-8 substring.
422 * The returned pointer must be freed using RTStrFree().
423 * @param pszString UTF-8 string to duplicate.
424 * @param cchMax The max number of chars to duplicate, not counting
425 * the terminator.
426 */
427#define RTStrDupNEx(ppszCopy, pszString, cchMax) RTStrDupNExTag((ppszCopy), (pszString), (cchMax), RTSTR_TAG)
428
429/**
430 * Allocates a new copy of the given UTF-8 substring (custom tag).
431 *
432 * @returns iprt status code (VINF_SUCCESS or VERR_NO_STR_MEMORY).
433 * @param ppszCopy Receives pointer of the allocated UTF-8 substring.
434 * The returned pointer must be freed using RTStrFree().
435 * @param pszString UTF-8 string to duplicate.
436 * @param cchMax The max number of chars to duplicate, not counting
437 * the terminator.
438 * @param pszTag Allocation tag used for statistics and such.
439 */
440RTDECL(int) RTStrDupNExTag(char **ppszCopy, const char *pszString, size_t cchMax, const char *pszTag);
441
442/**
443 * Appends a string onto an existing IPRT allocated string (default tag).
444 *
445 * @retval VINF_SUCCESS
446 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
447 * remains unchanged.
448 *
449 * @param ppsz Pointer to the string pointer. The string
450 * pointer must either be NULL or point to a string
451 * returned by an IPRT string API. (In/Out)
452 * @param pszAppend The string to append. NULL and empty strings
453 * are quietly ignored.
454 */
455#define RTStrAAppend(ppsz, pszAppend) RTStrAAppendTag((ppsz), (pszAppend), RTSTR_TAG)
456
457/**
458 * Appends a string onto an existing IPRT allocated string (custom tag).
459 *
460 * @retval VINF_SUCCESS
461 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
462 * remains unchanged.
463 *
464 * @param ppsz Pointer to the string pointer. The string
465 * pointer must either be NULL or point to a string
466 * returned by an IPRT string API. (In/Out)
467 * @param pszAppend The string to append. NULL and empty strings
468 * are quietly ignored.
469 * @param pszTag Allocation tag used for statistics and such.
470 */
471RTDECL(int) RTStrAAppendTag(char **ppsz, const char *pszAppend, const char *pszTag);
472
473/**
474 * Appends N bytes from a strings onto an existing IPRT allocated string
475 * (default tag).
476 *
477 * @retval VINF_SUCCESS
478 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
479 * remains unchanged.
480 *
481 * @param ppsz Pointer to the string pointer. The string
482 * pointer must either be NULL or point to a string
483 * returned by an IPRT string API. (In/Out)
484 * @param pszAppend The string to append. Can be NULL if cchAppend
485 * is NULL.
486 * @param cchAppend The number of chars (not code points) to append
487 * from pszAppend. Must not be more than
488 * @a pszAppend contains, except for the special
489 * value RTSTR_MAX that can be used to indicate all
490 * of @a pszAppend without having to strlen it.
491 */
492#define RTStrAAppendN(ppsz, pszAppend, cchAppend) RTStrAAppendNTag((ppsz), (pszAppend), (cchAppend), RTSTR_TAG)
493
494/**
495 * Appends N bytes from a strings onto an existing IPRT allocated string (custom
496 * tag).
497 *
498 * @retval VINF_SUCCESS
499 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
500 * remains unchanged.
501 *
502 * @param ppsz Pointer to the string pointer. The string
503 * pointer must either be NULL or point to a string
504 * returned by an IPRT string API. (In/Out)
505 * @param pszAppend The string to append. Can be NULL if cchAppend
506 * is NULL.
507 * @param cchAppend The number of chars (not code points) to append
508 * from pszAppend. Must not be more than
509 * @a pszAppend contains, except for the special
510 * value RTSTR_MAX that can be used to indicate all
511 * of @a pszAppend without having to strlen it.
512 * @param pszTag Allocation tag used for statistics and such.
513 */
514RTDECL(int) RTStrAAppendNTag(char **ppsz, const char *pszAppend, size_t cchAppend, const char *pszTag);
515
516/**
517 * Appends one or more strings onto an existing IPRT allocated string.
518 *
519 * This is a very flexible and efficient alternative to using RTStrAPrintf to
520 * combine several strings together.
521 *
522 * @retval VINF_SUCCESS
523 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
524 * remains unchanged.
525 *
526 * @param ppsz Pointer to the string pointer. The string
527 * pointer must either be NULL or point to a string
528 * returned by an IPRT string API. (In/Out)
529 * @param cPairs The number of string / length pairs in the
530 * @a va.
531 * @param va List of string (const char *) and length
532 * (size_t) pairs. The strings will be appended to
533 * the string in the first argument.
534 */
535#define RTStrAAppendExNV(ppsz, cPairs, va) RTStrAAppendExNVTag((ppsz), (cPairs), (va), RTSTR_TAG)
536
537/**
538 * Appends one or more strings onto an existing IPRT allocated string.
539 *
540 * This is a very flexible and efficient alternative to using RTStrAPrintf to
541 * combine several strings together.
542 *
543 * @retval VINF_SUCCESS
544 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
545 * remains unchanged.
546 *
547 * @param ppsz Pointer to the string pointer. The string
548 * pointer must either be NULL or point to a string
549 * returned by an IPRT string API. (In/Out)
550 * @param cPairs The number of string / length pairs in the
551 * @a va.
552 * @param va List of string (const char *) and length
553 * (size_t) pairs. The strings will be appended to
554 * the string in the first argument.
555 * @param pszTag Allocation tag used for statistics and such.
556 */
557RTDECL(int) RTStrAAppendExNVTag(char **ppsz, size_t cPairs, va_list va, const char *pszTag);
558
559/**
560 * Appends one or more strings onto an existing IPRT allocated string
561 * (untagged).
562 *
563 * This is a very flexible and efficient alternative to using RTStrAPrintf to
564 * combine several strings together.
565 *
566 * @retval VINF_SUCCESS
567 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
568 * remains unchanged.
569 *
570 * @param ppsz Pointer to the string pointer. The string
571 * pointer must either be NULL or point to a string
572 * returned by an IPRT string API. (In/Out)
573 * @param cPairs The number of string / length pairs in the
574 * ellipsis.
575 * @param ... List of string (const char *) and length
576 * (size_t) pairs. The strings will be appended to
577 * the string in the first argument.
578 */
579DECLINLINE(int) RTStrAAppendExN(char **ppsz, size_t cPairs, ...)
580{
581 int rc;
582 va_list va;
583 va_start(va, cPairs);
584 rc = RTStrAAppendExNVTag(ppsz, cPairs, va, RTSTR_TAG);
585 va_end(va);
586 return rc;
587}
588
589/**
590 * Appends one or more strings onto an existing IPRT allocated string (custom
591 * tag).
592 *
593 * This is a very flexible and efficient alternative to using RTStrAPrintf to
594 * combine several strings together.
595 *
596 * @retval VINF_SUCCESS
597 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
598 * remains unchanged.
599 *
600 * @param ppsz Pointer to the string pointer. The string
601 * pointer must either be NULL or point to a string
602 * returned by an IPRT string API. (In/Out)
603 * @param pszTag Allocation tag used for statistics and such.
604 * @param cPairs The number of string / length pairs in the
605 * ellipsis.
606 * @param ... List of string (const char *) and length
607 * (size_t) pairs. The strings will be appended to
608 * the string in the first argument.
609 */
610DECLINLINE(int) RTStrAAppendExNTag(char **ppsz, const char *pszTag, size_t cPairs, ...)
611{
612 int rc;
613 va_list va;
614 va_start(va, cPairs);
615 rc = RTStrAAppendExNVTag(ppsz, cPairs, va, pszTag);
616 va_end(va);
617 return rc;
618}
619
620/**
621 * Truncates an IPRT allocated string (default tag).
622 *
623 * @retval VINF_SUCCESS.
624 * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
625 *
626 * @param ppsz Pointer to the string pointer. The string
627 * pointer can be NULL if @a cchNew is 0, no change
628 * is made then. If we actually reallocate the
629 * string, the string pointer might be changed by
630 * this call. (In/Out)
631 * @param cchNew The new string length (excluding the
632 * terminator). The string must be at least this
633 * long or we'll return VERR_OUT_OF_RANGE and
634 * assert on you.
635 */
636#define RTStrATruncate(ppsz, cchNew) RTStrATruncateTag((ppsz), (cchNew), RTSTR_TAG)
637
638/**
639 * Truncates an IPRT allocated string.
640 *
641 * @retval VINF_SUCCESS.
642 * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
643 *
644 * @param ppsz Pointer to the string pointer. The string
645 * pointer can be NULL if @a cchNew is 0, no change
646 * is made then. If we actually reallocate the
647 * string, the string pointer might be changed by
648 * this call. (In/Out)
649 * @param cchNew The new string length (excluding the
650 * terminator). The string must be at least this
651 * long or we'll return VERR_OUT_OF_RANGE and
652 * assert on you.
653 * @param pszTag Allocation tag used for statistics and such.
654 */
655RTDECL(int) RTStrATruncateTag(char **ppsz, size_t cchNew, const char *pszTag);
656
657/**
658 * Allocates memory for string storage (default tag).
659 *
660 * You should normally not use this function, except if there is some very
661 * custom string handling you need doing that isn't covered by any of the other
662 * APIs.
663 *
664 * @returns Pointer to the allocated string. The first byte is always set
665 * to the string terminator char, the contents of the remainder of the
666 * memory is undefined. The string must be freed by calling RTStrFree.
667 *
668 * NULL is returned if the allocation failed. Please translate this to
669 * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
670 * RTStrAllocEx if an IPRT status code is required.
671 *
672 * @param cb How many bytes to allocate. If this is zero, we
673 * will allocate a terminator byte anyway.
674 */
675#define RTStrAlloc(cb) RTStrAllocTag((cb), RTSTR_TAG)
676
677/**
678 * Allocates memory for string storage (custom tag).
679 *
680 * You should normally not use this function, except if there is some very
681 * custom string handling you need doing that isn't covered by any of the other
682 * APIs.
683 *
684 * @returns Pointer to the allocated string. The first byte is always set
685 * to the string terminator char, the contents of the remainder of the
686 * memory is undefined. The string must be freed by calling RTStrFree.
687 *
688 * NULL is returned if the allocation failed. Please translate this to
689 * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
690 * RTStrAllocEx if an IPRT status code is required.
691 *
692 * @param cb How many bytes to allocate. If this is zero, we
693 * will allocate a terminator byte anyway.
694 * @param pszTag Allocation tag used for statistics and such.
695 */
696RTDECL(char *) RTStrAllocTag(size_t cb, const char *pszTag);
697
698/**
699 * Allocates memory for string storage, with status code (default tag).
700 *
701 * You should normally not use this function, except if there is some very
702 * custom string handling you need doing that isn't covered by any of the other
703 * APIs.
704 *
705 * @retval VINF_SUCCESS
706 * @retval VERR_NO_STR_MEMORY
707 *
708 * @param ppsz Where to return the allocated string. This will
709 * be set to NULL on failure. On success, the
710 * returned memory will always start with a
711 * terminator char so that it is considered a valid
712 * C string, the contents of rest of the memory is
713 * undefined.
714 * @param cb How many bytes to allocate. If this is zero, we
715 * will allocate a terminator byte anyway.
716 */
717#define RTStrAllocEx(ppsz, cb) RTStrAllocExTag((ppsz), (cb), RTSTR_TAG)
718
719/**
720 * Allocates memory for string storage, with status code (custom tag).
721 *
722 * You should normally not use this function, except if there is some very
723 * custom string handling you need doing that isn't covered by any of the other
724 * APIs.
725 *
726 * @retval VINF_SUCCESS
727 * @retval VERR_NO_STR_MEMORY
728 *
729 * @param ppsz Where to return the allocated string. This will
730 * be set to NULL on failure. On success, the
731 * returned memory will always start with a
732 * terminator char so that it is considered a valid
733 * C string, the contents of rest of the memory is
734 * undefined.
735 * @param cb How many bytes to allocate. If this is zero, we
736 * will allocate a terminator byte anyway.
737 * @param pszTag Allocation tag used for statistics and such.
738 */
739RTDECL(int) RTStrAllocExTag(char **ppsz, size_t cb, const char *pszTag);
740
741/**
742 * Reallocates the specified string (default tag).
743 *
744 * You should normally not have use this function, except perhaps to truncate a
745 * really long string you've got from some IPRT string API, but then you should
746 * use RTStrATruncate.
747 *
748 * @returns VINF_SUCCESS.
749 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
750 * remains unchanged.
751 *
752 * @param ppsz Pointer to the string variable containing the
753 * input and output string.
754 *
755 * When not freeing the string, the result will
756 * always have the last byte set to the terminator
757 * character so that when used for string
758 * truncation the result will be a valid C string
759 * (your job to keep it a valid UTF-8 string).
760 *
761 * When the input string is NULL and we're supposed
762 * to reallocate, the returned string will also
763 * have the first byte set to the terminator char
764 * so it will be a valid C string.
765 *
766 * @param cbNew When @a cbNew is zero, we'll behave like
767 * RTStrFree and @a *ppsz will be set to NULL.
768 *
769 * When not zero, this will be the new size of the
770 * memory backing the string, i.e. it includes the
771 * terminator char.
772 */
773#define RTStrRealloc(ppsz, cbNew) RTStrReallocTag((ppsz), (cbNew), RTSTR_TAG)
774
775/**
776 * Reallocates the specified string (custom tag).
777 *
778 * You should normally not have use this function, except perhaps to truncate a
779 * really long string you've got from some IPRT string API, but then you should
780 * use RTStrATruncate.
781 *
782 * @returns VINF_SUCCESS.
783 * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
784 * remains unchanged.
785 *
786 * @param ppsz Pointer to the string variable containing the
787 * input and output string.
788 *
789 * When not freeing the string, the result will
790 * always have the last byte set to the terminator
791 * character so that when used for string
792 * truncation the result will be a valid C string
793 * (your job to keep it a valid UTF-8 string).
794 *
795 * When the input string is NULL and we're supposed
796 * to reallocate, the returned string will also
797 * have the first byte set to the terminator char
798 * so it will be a valid C string.
799 *
800 * @param cbNew When @a cbNew is zero, we'll behave like
801 * RTStrFree and @a *ppsz will be set to NULL.
802 *
803 * When not zero, this will be the new size of the
804 * memory backing the string, i.e. it includes the
805 * terminator char.
806 * @param pszTag Allocation tag used for statistics and such.
807 */
808RTDECL(int) RTStrReallocTag(char **ppsz, size_t cbNew, const char *pszTag);
809
810/**
811 * Validates the UTF-8 encoding of the string.
812 *
813 * @returns iprt status code.
814 * @param psz The string.
815 */
816RTDECL(int) RTStrValidateEncoding(const char *psz);
817
818/** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
819 * @{
820 */
821/** Check that the string is zero terminated within the given size.
822 * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
823#define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED RT_BIT_32(0)
824/** Check that the string is exactly the given length.
825 * If it terminates early, VERR_BUFFER_UNDERFLOW will be returned. When used
826 * together with RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED, the given length must
827 * include the terminator or VERR_BUFFER_OVERFLOW will be returned. */
828#define RTSTR_VALIDATE_ENCODING_EXACT_LENGTH RT_BIT_32(1)
829/** @} */
830
831/**
832 * Validates the UTF-8 encoding of the string.
833 *
834 * @returns iprt status code.
835 * @param psz The string.
836 * @param cch The max string length (/ size). Use RTSTR_MAX to
837 * process the entire string.
838 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
839 */
840RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
841
842/**
843 * Checks if the UTF-8 encoding is valid.
844 *
845 * @returns true / false.
846 * @param psz The string.
847 */
848RTDECL(bool) RTStrIsValidEncoding(const char *psz);
849
850/**
851 * Purge all bad UTF-8 encoding in the string, replacing it with '?'.
852 *
853 * @returns The number of bad characters (0 if nothing was done).
854 * @param psz The string to purge.
855 */
856RTDECL(size_t) RTStrPurgeEncoding(char *psz);
857
858/**
859 * Sanitizes a (valid) UTF-8 string by replacing all characters outside a white
860 * list in-place by an ASCII replacedment character.
861 *
862 * Multi-byte characters will be replaced byte by byte.
863 *
864 * @returns The number of code points replaced. In the case of an incorrectly
865 * encoded string -1 will be returned, and the string is not completely
866 * processed. In the case of puszValidPairs having an odd number of
867 * code points, -1 will be also return but without any modification to
868 * the string.
869 * @param psz The string to sanitise.
870 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
871 * Each pair is the start and end point of a range,
872 * and the union of these ranges forms the white list.
873 * @param chReplacement The ASCII replacement character.
874 */
875RTDECL(ssize_t) RTStrPurgeComplementSet(char *psz, PCRTUNICP puszValidPairs, char chReplacement);
876
877/**
878 * Gets the number of code points the string is made up of, excluding
879 * the terminator.
880 *
881 *
882 * @returns Number of code points (RTUNICP).
883 * @returns 0 if the string was incorrectly encoded.
884 * @param psz The string.
885 */
886RTDECL(size_t) RTStrUniLen(const char *psz);
887
888/**
889 * Gets the number of code points the string is made up of, excluding
890 * the terminator.
891 *
892 * This function will validate the string, and incorrectly encoded UTF-8
893 * strings will be rejected.
894 *
895 * @returns iprt status code.
896 * @param psz The string.
897 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
898 * @param pcuc Where to store the code point count.
899 * This is undefined on failure.
900 */
901RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
902
903/**
904 * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
905 *
906 * @returns iprt status code.
907 * @param pszString UTF-8 string to convert.
908 * @param ppUniString Receives pointer to the allocated unicode string.
909 * The returned string must be freed using RTUniFree().
910 */
911RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
912
913/**
914 * Translates pszString from UTF-8 to an array of code points, allocating the result
915 * array if requested.
916 *
917 * @returns iprt status code.
918 * @param pszString UTF-8 string to convert.
919 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
920 * when it reaches cchString or the string terminator ('\\0').
921 * Use RTSTR_MAX to translate the entire string.
922 * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
923 * a buffer of the specified size, or pointer to a NULL pointer.
924 * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
925 * will be allocated to hold the translated string.
926 * If a buffer was requested it must be freed using RTUtf16Free().
927 * @param cCps The number of code points in the unicode string. This includes the terminator.
928 * @param pcCps Where to store the length of the translated string,
929 * excluding the terminator. (Optional)
930 *
931 * This may be set under some error conditions,
932 * however, only for VERR_BUFFER_OVERFLOW and
933 * VERR_NO_STR_MEMORY will it contain a valid string
934 * length that can be used to resize the buffer.
935 */
936RTDECL(int) RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
937
938/**
939 * Calculates the length of the string in RTUTF16 items.
940 *
941 * This function will validate the string, and incorrectly encoded UTF-8
942 * strings will be rejected. The primary purpose of this function is to
943 * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
944 * other purposes RTStrCalcUtf16LenEx() should be used.
945 *
946 * @returns Number of RTUTF16 items.
947 * @returns 0 if the string was incorrectly encoded.
948 * @param psz The string.
949 */
950RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
951
952/**
953 * Calculates the length of the string in RTUTF16 items.
954 *
955 * This function will validate the string, and incorrectly encoded UTF-8
956 * strings will be rejected.
957 *
958 * @returns iprt status code.
959 * @param psz The string.
960 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
961 * @param pcwc Where to store the string length. Optional.
962 * This is undefined on failure.
963 */
964RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
965
966/**
967 * Translate a UTF-8 string into a UTF-16 allocating the result buffer (default
968 * tag).
969 *
970 * @returns iprt status code.
971 * @param pszString UTF-8 string to convert.
972 * @param ppwszString Receives pointer to the allocated UTF-16 string.
973 * The returned string must be freed using RTUtf16Free().
974 */
975#define RTStrToUtf16(pszString, ppwszString) RTStrToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
976
977/**
978 * Translate a UTF-8 string into a UTF-16 allocating the result buffer (custom
979 * tag).
980 *
981 * This differs from RTStrToUtf16 in that it always produces a
982 * big-endian string.
983 *
984 * @returns iprt status code.
985 * @param pszString UTF-8 string to convert.
986 * @param ppwszString Receives pointer to the allocated UTF-16 string.
987 * The returned string must be freed using RTUtf16Free().
988 * @param pszTag Allocation tag used for statistics and such.
989 */
990RTDECL(int) RTStrToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
991
992/**
993 * Translate a UTF-8 string into a UTF-16BE allocating the result buffer
994 * (default tag).
995 *
996 * This differs from RTStrToUtf16Tag in that it always produces a
997 * big-endian string.
998 *
999 * @returns iprt status code.
1000 * @param pszString UTF-8 string to convert.
1001 * @param ppwszString Receives pointer to the allocated UTF-16BE string.
1002 * The returned string must be freed using RTUtf16Free().
1003 */
1004#define RTStrToUtf16Big(pszString, ppwszString) RTStrToUtf16BigTag((pszString), (ppwszString), RTSTR_TAG)
1005
1006/**
1007 * Translate a UTF-8 string into a UTF-16BE allocating the result buffer (custom
1008 * tag).
1009 *
1010 * @returns iprt status code.
1011 * @param pszString UTF-8 string to convert.
1012 * @param ppwszString Receives pointer to the allocated UTF-16BE string.
1013 * The returned string must be freed using RTUtf16Free().
1014 * @param pszTag Allocation tag used for statistics and such.
1015 */
1016RTDECL(int) RTStrToUtf16BigTag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
1017
1018/**
1019 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
1020 *
1021 * @returns iprt status code.
1022 * @param pszString UTF-8 string to convert.
1023 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
1024 * when it reaches cchString or the string terminator ('\\0').
1025 * Use RTSTR_MAX to translate the entire string.
1026 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
1027 * a buffer of the specified size, or pointer to a NULL pointer.
1028 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
1029 * will be allocated to hold the translated string.
1030 * If a buffer was requested it must be freed using RTUtf16Free().
1031 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
1032 * @param pcwc Where to store the length of the translated string,
1033 * excluding the terminator. (Optional)
1034 *
1035 * This may be set under some error conditions,
1036 * however, only for VERR_BUFFER_OVERFLOW and
1037 * VERR_NO_STR_MEMORY will it contain a valid string
1038 * length that can be used to resize the buffer.
1039 */
1040#define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
1041 RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
1042
1043/**
1044 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
1045 * requested (custom tag).
1046 *
1047 * @returns iprt status code.
1048 * @param pszString UTF-8 string to convert.
1049 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
1050 * when it reaches cchString or the string terminator ('\\0').
1051 * Use RTSTR_MAX to translate the entire string.
1052 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
1053 * a buffer of the specified size, or pointer to a NULL pointer.
1054 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
1055 * will be allocated to hold the translated string.
1056 * If a buffer was requested it must be freed using RTUtf16Free().
1057 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
1058 * @param pcwc Where to store the length of the translated string,
1059 * excluding the terminator. (Optional)
1060 *
1061 * This may be set under some error conditions,
1062 * however, only for VERR_BUFFER_OVERFLOW and
1063 * VERR_NO_STR_MEMORY will it contain a valid string
1064 * length that can be used to resize the buffer.
1065 * @param pszTag Allocation tag used for statistics and such.
1066 */
1067RTDECL(int) RTStrToUtf16ExTag(const char *pszString, size_t cchString,
1068 PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
1069
1070
1071/**
1072 * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if requested.
1073 *
1074 * This differs from RTStrToUtf16Ex in that it always produces a
1075 * big-endian string.
1076 *
1077 * @returns iprt status code.
1078 * @param pszString UTF-8 string to convert.
1079 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
1080 * when it reaches cchString or the string terminator ('\\0').
1081 * Use RTSTR_MAX to translate the entire string.
1082 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
1083 * a buffer of the specified size, or pointer to a NULL pointer.
1084 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
1085 * will be allocated to hold the translated string.
1086 * If a buffer was requested it must be freed using RTUtf16Free().
1087 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
1088 * @param pcwc Where to store the length of the translated string,
1089 * excluding the terminator. (Optional)
1090 *
1091 * This may be set under some error conditions,
1092 * however, only for VERR_BUFFER_OVERFLOW and
1093 * VERR_NO_STR_MEMORY will it contain a valid string
1094 * length that can be used to resize the buffer.
1095 */
1096#define RTStrToUtf16BigEx(pszString, cchString, ppwsz, cwc, pcwc) \
1097 RTStrToUtf16BigExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
1098
1099/**
1100 * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if
1101 * requested (custom tag).
1102 *
1103 * This differs from RTStrToUtf16ExTag in that it always produces a
1104 * big-endian string.
1105 *
1106 * @returns iprt status code.
1107 * @param pszString UTF-8 string to convert.
1108 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
1109 * when it reaches cchString or the string terminator ('\\0').
1110 * Use RTSTR_MAX to translate the entire string.
1111 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
1112 * a buffer of the specified size, or pointer to a NULL pointer.
1113 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
1114 * will be allocated to hold the translated string.
1115 * If a buffer was requested it must be freed using RTUtf16Free().
1116 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
1117 * @param pcwc Where to store the length of the translated string,
1118 * excluding the terminator. (Optional)
1119 *
1120 * This may be set under some error conditions,
1121 * however, only for VERR_BUFFER_OVERFLOW and
1122 * VERR_NO_STR_MEMORY will it contain a valid string
1123 * length that can be used to resize the buffer.
1124 * @param pszTag Allocation tag used for statistics and such.
1125 */
1126RTDECL(int) RTStrToUtf16BigExTag(const char *pszString, size_t cchString,
1127 PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
1128
1129
1130/**
1131 * Calculates the length of the string in Latin-1 characters.
1132 *
1133 * This function will validate the string, and incorrectly encoded UTF-8
1134 * strings as well as string with codepoints outside the latin-1 range will be
1135 * rejected. The primary purpose of this function is to help allocate buffers
1136 * for RTStrToLatin1Ex of the correct size. For most other purposes
1137 * RTStrCalcLatin1LenEx() should be used.
1138 *
1139 * @returns Number of Latin-1 characters.
1140 * @returns 0 if the string was incorrectly encoded.
1141 * @param psz The string.
1142 */
1143RTDECL(size_t) RTStrCalcLatin1Len(const char *psz);
1144
1145/**
1146 * Calculates the length of the string in Latin-1 characters.
1147 *
1148 * This function will validate the string, and incorrectly encoded UTF-8
1149 * strings as well as string with codepoints outside the latin-1 range will be
1150 * rejected.
1151 *
1152 * @returns iprt status code.
1153 * @param psz The string.
1154 * @param cch The max string length. Use RTSTR_MAX to process the
1155 * entire string.
1156 * @param pcch Where to store the string length. Optional.
1157 * This is undefined on failure.
1158 */
1159RTDECL(int) RTStrCalcLatin1LenEx(const char *psz, size_t cch, size_t *pcch);
1160
1161/**
1162 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
1163 * tag).
1164 *
1165 * @returns iprt status code.
1166 * @param pszString UTF-8 string to convert.
1167 * @param ppszString Receives pointer to the allocated Latin-1 string.
1168 * The returned string must be freed using RTStrFree().
1169 */
1170#define RTStrToLatin1(pszString, ppszString) RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
1171
1172/**
1173 * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
1174 * tag).
1175 *
1176 * @returns iprt status code.
1177 * @param pszString UTF-8 string to convert.
1178 * @param ppszString Receives pointer to the allocated Latin-1 string.
1179 * The returned string must be freed using RTStrFree().
1180 * @param pszTag Allocation tag used for statistics and such.
1181 */
1182RTDECL(int) RTStrToLatin1Tag(const char *pszString, char **ppszString, const char *pszTag);
1183
1184/**
1185 * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
1186 *
1187 * @returns iprt status code.
1188 * @param pszString UTF-8 string to convert.
1189 * @param cchString The maximum size in chars (the type) to convert.
1190 * The conversion stop when it reaches cchString or
1191 * the string terminator ('\\0'). Use RTSTR_MAX to
1192 * translate the entire string.
1193 * @param ppsz If cch is non-zero, this must either be pointing to
1194 * pointer to a buffer of the specified size, or
1195 * pointer to a NULL pointer. If *ppsz is NULL or cch
1196 * is zero a buffer of at least cch items will be
1197 * allocated to hold the translated string. If a
1198 * buffer was requested it must be freed using
1199 * RTStrFree().
1200 * @param cch The buffer size in bytes. This includes the
1201 * terminator.
1202 * @param pcch Where to store the length of the translated string,
1203 * excluding the terminator. (Optional)
1204 *
1205 * This may be set under some error conditions,
1206 * however, only for VERR_BUFFER_OVERFLOW and
1207 * VERR_NO_STR_MEMORY will it contain a valid string
1208 * length that can be used to resize the buffer.
1209 */
1210#define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
1211 RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
1212
1213/**
1214 * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
1215 * requested (custom tag).
1216 *
1217 * @returns iprt status code.
1218 * @param pszString UTF-8 string to convert.
1219 * @param cchString The maximum size in chars (the type) to convert.
1220 * The conversion stop when it reaches cchString or
1221 * the string terminator ('\\0'). Use RTSTR_MAX to
1222 * translate the entire string.
1223 * @param ppsz If cch is non-zero, this must either be pointing to
1224 * pointer to a buffer of the specified size, or
1225 * pointer to a NULL pointer. If *ppsz is NULL or cch
1226 * is zero a buffer of at least cch items will be
1227 * allocated to hold the translated string. If a
1228 * buffer was requested it must be freed using
1229 * RTStrFree().
1230 * @param cch The buffer size in bytes. This includes the
1231 * terminator.
1232 * @param pcch Where to store the length of the translated string,
1233 * excluding the terminator. (Optional)
1234 *
1235 * This may be set under some error conditions,
1236 * however, only for VERR_BUFFER_OVERFLOW and
1237 * VERR_NO_STR_MEMORY will it contain a valid string
1238 * length that can be used to resize the buffer.
1239 * @param pszTag Allocation tag used for statistics and such.
1240 */
1241RTDECL(int) RTStrToLatin1ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
1242
1243/**
1244 * Get the unicode code point at the given string position.
1245 *
1246 * @returns unicode code point.
1247 * @returns RTUNICP_INVALID if the encoding is invalid.
1248 * @param psz The string.
1249 */
1250RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
1251
1252/**
1253 * Get the unicode code point at the given string position.
1254 *
1255 * @returns iprt status code
1256 * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1257 * @param ppsz The string cursor.
1258 * This is advanced one character forward on failure.
1259 * @param pCp Where to store the unicode code point.
1260 * Stores RTUNICP_INVALID if the encoding is invalid.
1261 */
1262RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
1263
1264/**
1265 * Get the unicode code point at the given string position for a string of a
1266 * given length.
1267 *
1268 * @returns iprt status code
1269 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1270 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1271 *
1272 * @param ppsz The string.
1273 * @param pcch Pointer to the length of the string. This will be
1274 * decremented by the size of the code point.
1275 * @param pCp Where to store the unicode code point.
1276 * Stores RTUNICP_INVALID if the encoding is invalid.
1277 */
1278RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
1279
1280/**
1281 * Put the unicode code point at the given string position
1282 * and return the pointer to the char following it.
1283 *
1284 * This function will not consider anything at or following the
1285 * buffer area pointed to by psz. It is therefore not suitable for
1286 * inserting code points into a string, only appending/overwriting.
1287 *
1288 * @returns pointer to the char following the written code point.
1289 * @param psz The string.
1290 * @param CodePoint The code point to write.
1291 * This should not be RTUNICP_INVALID or any other
1292 * character out of the UTF-8 range.
1293 *
1294 * @remark This is a worker function for RTStrPutCp().
1295 *
1296 */
1297RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
1298
1299/**
1300 * Get the unicode code point at the given string position.
1301 *
1302 * @returns unicode code point.
1303 * @returns RTUNICP_INVALID if the encoding is invalid.
1304 * @param psz The string.
1305 *
1306 * @remark We optimize this operation by using an inline function for
1307 * the most frequent and simplest sequence, the rest is
1308 * handled by RTStrGetCpInternal().
1309 */
1310DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
1311{
1312 const unsigned char uch = *(const unsigned char *)psz;
1313 if (!(uch & RT_BIT(7)))
1314 return uch;
1315 return RTStrGetCpInternal(psz);
1316}
1317
1318/**
1319 * Get the unicode code point at the given string position.
1320 *
1321 * @returns iprt status code.
1322 * @param ppsz Pointer to the string pointer. This will be updated to
1323 * point to the char following the current code point.
1324 * This is advanced one character forward on failure.
1325 * @param pCp Where to store the code point.
1326 * RTUNICP_INVALID is stored here on failure.
1327 *
1328 * @remark We optimize this operation by using an inline function for
1329 * the most frequent and simplest sequence, the rest is
1330 * handled by RTStrGetCpExInternal().
1331 */
1332DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
1333{
1334 const unsigned char uch = **(const unsigned char **)ppsz;
1335 if (!(uch & RT_BIT(7)))
1336 {
1337 (*ppsz)++;
1338 *pCp = uch;
1339 return VINF_SUCCESS;
1340 }
1341 return RTStrGetCpExInternal(ppsz, pCp);
1342}
1343
1344/**
1345 * Get the unicode code point at the given string position for a string of a
1346 * given maximum length.
1347 *
1348 * @returns iprt status code.
1349 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
1350 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
1351 *
1352 * @param ppsz Pointer to the string pointer. This will be updated to
1353 * point to the char following the current code point.
1354 * @param pcch Pointer to the maximum string length. This will be
1355 * decremented by the size of the code point found.
1356 * @param pCp Where to store the code point.
1357 * RTUNICP_INVALID is stored here on failure.
1358 *
1359 * @remark We optimize this operation by using an inline function for
1360 * the most frequent and simplest sequence, the rest is
1361 * handled by RTStrGetCpNExInternal().
1362 */
1363DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
1364{
1365 if (RT_LIKELY(*pcch != 0))
1366 {
1367 const unsigned char uch = **(const unsigned char **)ppsz;
1368 if (!(uch & RT_BIT(7)))
1369 {
1370 (*ppsz)++;
1371 (*pcch)--;
1372 *pCp = uch;
1373 return VINF_SUCCESS;
1374 }
1375 }
1376 return RTStrGetCpNExInternal(ppsz, pcch, pCp);
1377}
1378
1379/**
1380 * Get the UTF-8 size in characters of a given Unicode code point.
1381 *
1382 * The code point is expected to be a valid Unicode one, but not necessarily in
1383 * the range supported by UTF-8.
1384 *
1385 * @returns The number of chars (bytes) required to encode the code point, or
1386 * zero if there is no UTF-8 encoding.
1387 * @param CodePoint The unicode code point.
1388 */
1389DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint)
1390{
1391 if (CodePoint < 0x00000080)
1392 return 1;
1393 if (CodePoint < 0x00000800)
1394 return 2;
1395 if (CodePoint < 0x00010000)
1396 return 3;
1397#ifdef RT_USE_RTC_3629
1398 if (CodePoint < 0x00011000)
1399 return 4;
1400#else
1401 if (CodePoint < 0x00200000)
1402 return 4;
1403 if (CodePoint < 0x04000000)
1404 return 5;
1405 if (CodePoint < 0x7fffffff)
1406 return 6;
1407#endif
1408 return 0;
1409}
1410
1411/**
1412 * Put the unicode code point at the given string position
1413 * and return the pointer to the char following it.
1414 *
1415 * This function will not consider anything at or following the
1416 * buffer area pointed to by psz. It is therefore not suitable for
1417 * inserting code points into a string, only appending/overwriting.
1418 *
1419 * @returns pointer to the char following the written code point.
1420 * @param psz The string.
1421 * @param CodePoint The code point to write.
1422 * This should not be RTUNICP_INVALID or any other
1423 * character out of the UTF-8 range.
1424 *
1425 * @remark We optimize this operation by using an inline function for
1426 * the most frequent and simplest sequence, the rest is
1427 * handled by RTStrPutCpInternal().
1428 */
1429DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
1430{
1431 if (CodePoint < 0x80)
1432 {
1433 *psz++ = (char)CodePoint;
1434 return psz;
1435 }
1436 return RTStrPutCpInternal(psz, CodePoint);
1437}
1438
1439/**
1440 * Skips ahead, past the current code point.
1441 *
1442 * @returns Pointer to the char after the current code point.
1443 * @param psz Pointer to the current code point.
1444 * @remark This will not move the next valid code point, only past the current one.
1445 */
1446DECLINLINE(char *) RTStrNextCp(const char *psz)
1447{
1448 RTUNICP Cp;
1449 RTStrGetCpEx(&psz, &Cp);
1450 return (char *)psz;
1451}
1452
1453/**
1454 * Skips back to the previous code point.
1455 *
1456 * @returns Pointer to the char before the current code point.
1457 * @returns pszStart on failure.
1458 * @param pszStart Pointer to the start of the string.
1459 * @param psz Pointer to the current code point.
1460 */
1461RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
1462
1463
1464/** @page pg_rt_str_format The IPRT Format Strings
1465 *
1466 * IPRT implements most of the commonly used format types and flags with the
1467 * exception of floating point which is completely missing. In addition IPRT
1468 * provides a number of IPRT specific format types for the IPRT typedefs and
1469 * other useful things. Note that several of these extensions are similar to
1470 * \%p and doesn't care much if you try add formating flags/width/precision.
1471 *
1472 *
1473 * Group 0a, The commonly used format types:
1474 * - \%s - Takes a pointer to a zero terminated string (UTF-8) and
1475 * prints it with the optionally adjustment (width, -) and
1476 * length restriction (precision).
1477 * - \%ls - Same as \%s except that the input is UTF-16 (output UTF-8).
1478 * - \%Ls - Same as \%s except that the input is UCS-32 (output UTF-8).
1479 * - \%S - Same as \%s, used to convert to current codeset but this is
1480 * now done by the streams code. Deprecated, use \%s.
1481 * - \%lS - Ditto. Deprecated, use \%ls.
1482 * - \%LS - Ditto. Deprecated, use \%Ls.
1483 * - \%c - Takes a char and prints it.
1484 * - \%d - Takes a signed integer and prints it as decimal. Thousand
1485 * separator (\'), zero padding (0), adjustment (-+), width,
1486 * precision
1487 * - \%i - Same as \%d.
1488 * - \%u - Takes an unsigned integer and prints it as decimal. Thousand
1489 * separator (\'), zero padding (0), adjustment (-+), width,
1490 * precision
1491 * - \%x - Takes an unsigned integer and prints it as lowercased
1492 * hexadecimal. The special hash (\#) flag causes a '0x'
1493 * prefixed to be printed. Zero padding (0), adjustment (-+),
1494 * width, precision.
1495 * - \%X - Same as \%x except that it is uppercased.
1496 * - \%o - Takes an unsigned (?) integer and prints it as octal. Zero
1497 * padding (0), adjustment (-+), width, precision.
1498 * - \%p - Takes a pointer (void technically) and prints it. Zero
1499 * padding (0), adjustment (-+), width, precision.
1500 *
1501 * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
1502 * argument type specifiers:
1503 * - \%ll - long long (uint64_t).
1504 * - \%L - long long (uint64_t).
1505 * - \%l - long (uint32_t, uint64_t)
1506 * - \%h - short (int16_t).
1507 * - \%hh - char (int8_t).
1508 * - \%H - char (int8_t).
1509 * - \%z - size_t.
1510 * - \%j - intmax_t (int64_t).
1511 * - \%t - ptrdiff_t.
1512 * The type in parentheses is typical sizes, however when printing those types
1513 * you are better off using the special group 2 format types below (\%RX32 and
1514 * such).
1515 *
1516 *
1517 * Group 0b, IPRT format tricks:
1518 * - %M - Replaces the format string, takes a string pointer.
1519 * - %N - Nested formatting, takes a pointer to a format string
1520 * followed by the pointer to a va_list variable. The va_list
1521 * variable will not be modified and the caller must do va_end()
1522 * on it. Make sure the va_list variable is NOT in a parameter
1523 * list or some gcc versions/targets may get it all wrong.
1524 *
1525 *
1526 * Group 1, the basic runtime typedefs (excluding those which obviously are
1527 * pointer):
1528 * - \%RTbool - Takes a bool value and prints 'true', 'false', or '!%d!'.
1529 * - \%RTeic - Takes a #PCRTERRINFO value outputting 'rc: msg',
1530 * or 'rc - msg' with the \# flag.
1531 * - \%RTeim - Takes a #PCRTERRINFO value outputting ': msg', or
1532 * ' - msg' with the \# flag.
1533 * - \%RTfile - Takes a #RTFILE value.
1534 * - \%RTfmode - Takes a #RTFMODE value.
1535 * - \%RTfoff - Takes a #RTFOFF value.
1536 * - \%RTfp16 - Takes a #RTFAR16 value.
1537 * - \%RTfp32 - Takes a #RTFAR32 value.
1538 * - \%RTfp64 - Takes a #RTFAR64 value.
1539 * - \%RTgid - Takes a #RTGID value.
1540 * - \%RTino - Takes a #RTINODE value.
1541 * - \%RTint - Takes a #RTINT value.
1542 * - \%RTiop - Takes a #RTIOPORT value.
1543 * - \%RTldrm - Takes a #RTLDRMOD value.
1544 * - \%RTmac - Takes a #PCRTMAC pointer.
1545 * - \%RTnaddr - Takes a #PCRTNETADDR value.
1546 * - \%RTnaipv4 - Takes a #RTNETADDRIPV4 value.
1547 * - \%RTnaipv6 - Takes a #PCRTNETADDRIPV6 value.
1548 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1549 * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
1550 * - \%RTproc - Takes a #RTPROCESS value.
1551 * - \%RTptr - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
1552 * - \%RTreg - Takes a #RTCCUINTREG value.
1553 * - \%RTsel - Takes a #RTSEL value.
1554 * - \%RTsem - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
1555 * - \%RTsock - Takes a #RTSOCKET value.
1556 * - \%RTthrd - Takes a #RTTHREAD value.
1557 * - \%RTuid - Takes a #RTUID value.
1558 * - \%RTuint - Takes a #RTUINT value.
1559 * - \%RTunicp - Takes a #RTUNICP value.
1560 * - \%RTutf16 - Takes a #RTUTF16 value.
1561 * - \%RTuuid - Takes a #PCRTUUID and will print the UUID as a string.
1562 * - \%RTxuint - Takes a #RTUINT or #RTINT value, formatting it as hex.
1563 * - \%RGi - Takes a #RTGCINT value.
1564 * - \%RGp - Takes a #RTGCPHYS value.
1565 * - \%RGr - Takes a #RTGCUINTREG value.
1566 * - \%RGu - Takes a #RTGCUINT value.
1567 * - \%RGv - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
1568 * - \%RGx - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
1569 * - \%RHi - Takes a #RTHCINT value.
1570 * - \%RHp - Takes a #RTHCPHYS value.
1571 * - \%RHr - Takes a #RTHCUINTREG value.
1572 * - \%RHu - Takes a #RTHCUINT value.
1573 * - \%RHv - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
1574 * - \%RHx - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
1575 * - \%RRv - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
1576 * - \%RCi - Takes a #RTINT value.
1577 * - \%RCp - Takes a #RTCCPHYS value.
1578 * - \%RCr - Takes a #RTCCUINTREG value.
1579 * - \%RCu - Takes a #RTUINT value.
1580 * - \%RCv - Takes a #uintptr_t, #intptr_t, void * value.
1581 * - \%RCx - Takes a #RTUINT or #RTINT value, formatting it as hex.
1582 *
1583 *
1584 * Group 2, the generic integer types which are prefered over relying on what
1585 * bit-count a 'long', 'short', or 'long long' has on a platform. This are
1586 * highly prefered for the [u]intXX_t kind of types:
1587 * - \%RI[8|16|32|64] - Signed integer value of the specifed bit count.
1588 * - \%RU[8|16|32|64] - Unsigned integer value of the specifed bit count.
1589 * - \%RX[8|16|32|64] - Hexadecimal integer value of the specifed bit count.
1590 *
1591 *
1592 * Group 3, hex dumpers and other complex stuff which requires more than simple
1593 * formatting:
1594 * - \%Rhxd - Takes a pointer to the memory which is to be dumped in typical
1595 * hex format. Use the precision to specify the length, and the width to
1596 * set the number of bytes per line. Default width and precision is 16.
1597 * - \%RhxD - Same as \%Rhxd, except that it skips duplicate lines.
1598 * - \%Rhxs - Takes a pointer to the memory to be displayed as a hex string,
1599 * i.e. a series of space separated bytes formatted as two digit hex value.
1600 * Use the precision to specify the length. Default length is 16 bytes.
1601 * The width, if specified, is ignored.
1602 * The space separtor can get change to a colon by
1603 * using the ' flag, and removed entirely using \#.
1604 * - \%RhXd - Same as \%Rhxd, but takes an additional uint64_t
1605 * value with the memory start address/offset after
1606 * the memory pointer.
1607 * - \%RhXD - Same as \%RhxD, but takes an additional uint64_t
1608 * value with the memory start address/offset after
1609 * the memory pointer.
1610 * - \%RhXs - Same as \%Rhxs, but takes an additional uint64_t
1611 * value with the memory start address/offset after
1612 * the memory pointer.
1613 *
1614 * - \%Rhcb - Human readable byte size formatting, using
1615 * binary unit prefixes (GiB, MiB and such). Takes a
1616 * 64-bit unsigned integer as input. Does one
1617 * decimal point by default, can do 0-3 via precision
1618 * field. No rounding when calculating fraction.
1619 * The space flag add a space between the value and
1620 * unit.
1621 * - \%RhcB - Same a \%Rhcb only the 'i' is skipped in the unit.
1622 * - \%Rhci - SI variant of \%Rhcb, fraction is rounded.
1623 * - \%Rhub - Human readable number formatting, using
1624 * binary unit prefixes. Takes a 64-bit unsigned
1625 * integer as input. Does one decimal point by
1626 * default, can do 0-3 via precision field. No
1627 * rounding when calculating fraction. The space
1628 * flag add a space between the value and unit.
1629 * - \%RhuB - Same a \%Rhub only the 'i' is skipped in the unit.
1630 * - \%Rhui - SI variant of \%Rhub, fraction is rounded.
1631 *
1632 * - \%Rrc - Takes an integer iprt status code as argument. Will insert the
1633 * status code define corresponding to the iprt status code.
1634 * - \%Rrs - Takes an integer iprt status code as argument. Will insert the
1635 * short description of the specified status code.
1636 * - \%Rrf - Takes an integer iprt status code as argument. Will insert the
1637 * full description of the specified status code.
1638 * Note! Works like \%Rrs when IN_RT_STATIC is defined (so please avoid).
1639 * - \%Rra - Takes an integer iprt status code as argument. Will insert the
1640 * status code define + full description.
1641 * Note! Reduced output when IN_RT_STATIC is defined (so please avoid).
1642 * - \%Rwc - Takes a long Windows error code as argument. Will insert the status
1643 * code define corresponding to the Windows error code.
1644 * - \%Rwf - Takes a long Windows error code as argument. Will insert the
1645 * full description of the specified status code.
1646 * Note! Works like \%Rwc when IN_RT_STATIC is defined.
1647 * - \%Rwa - Takes a long Windows error code as argument. Will insert the
1648 * error code define + full description.
1649 * Note! Reduced output when IN_RT_STATIC is defined (so please avoid).
1650 *
1651 * - \%Rhrc - Takes a COM/XPCOM status code as argument. Will insert the status
1652 * code define corresponding to the Windows error code.
1653 * - \%Rhrf - Takes a COM/XPCOM status code as argument. Will insert the
1654 * full description of the specified status code.
1655 * Note! Works like \%Rhrc when IN_RT_STATIC is
1656 * defined on Windows (so please avoid).
1657 * - \%Rhra - Takes a COM/XPCOM error code as argument. Will insert the
1658 * error code define + full description.
1659 * Note! Reduced output when IN_RT_STATIC is defined on Windows (so please avoid).
1660 *
1661 * - \%Rfn - Pretty printing of a function or method. It drops the
1662 * return code and parameter list.
1663 * - \%Rbn - Prints the base name. For dropping the path in
1664 * order to save space when printing a path name.
1665 *
1666 * - \%lRbs - Same as \%ls except inlut is big endian UTF-16.
1667 *
1668 * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
1669 *
1670 *
1671 * Group 4, structure dumpers:
1672 * - \%RDtimespec - Takes a PCRTTIMESPEC.
1673 *
1674 *
1675 * Group 5, XML / HTML, JSON and URI escapers:
1676 * - \%RMas - Takes a string pointer (const char *) and outputs
1677 * it as an attribute value with the proper escaping.
1678 * This typically ends up in double quotes.
1679 *
1680 * - \%RMes - Takes a string pointer (const char *) and outputs
1681 * it as an element with the necessary escaping.
1682 *
1683 * - \%RMjs - Takes a string pointer (const char *) and outputs
1684 * it in quotes with proper JSON escaping.
1685 *
1686 * - \%RMpa - Takes a string pointer (const char *) and outputs
1687 * it percent-encoded (RFC-3986). All reserved characters
1688 * are encoded.
1689 *
1690 * - \%RMpf - Takes a string pointer (const char *) and outputs
1691 * it percent-encoded (RFC-3986), form style. This
1692 * means '+' is used to escape space (' ') and '%2B'
1693 * is used to escape '+'.
1694 *
1695 * - \%RMpp - Takes a string pointer (const char *) and outputs
1696 * it percent-encoded (RFC-3986), path style. This
1697 * means '/' will not be escaped.
1698 *
1699 * - \%RMpq - Takes a string pointer (const char *) and outputs
1700 * it percent-encoded (RFC-3986), query style. This
1701 * means '+' will not be escaped.
1702 *
1703 *
1704 * Group 6, CPU Architecture Register dumpers:
1705 * - \%RAx86[reg] - Takes a 64-bit register value if the register is
1706 * 64-bit or smaller. Check the code wrt which
1707 * registers are implemented.
1708 *
1709 */
1710
1711#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h & errcore.h */
1712# define DECLARED_FNRTSTROUTPUT
1713/**
1714 * Output callback.
1715 *
1716 * @returns number of bytes written.
1717 * @param pvArg User argument.
1718 * @param pachChars Pointer to an array of utf-8 characters.
1719 * @param cbChars Number of bytes in the character array pointed to by pachChars.
1720 */
1721typedef DECLCALLBACKTYPE(size_t, FNRTSTROUTPUT,(void *pvArg, const char *pachChars, size_t cbChars));
1722/** Pointer to callback function. */
1723typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
1724#endif
1725
1726/** @name Format flag.
1727 * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
1728 * that not all flags makes sense to both of the functions.
1729 * @{ */
1730#define RTSTR_F_CAPITAL 0x0001
1731#define RTSTR_F_LEFT 0x0002
1732#define RTSTR_F_ZEROPAD 0x0004
1733#define RTSTR_F_SPECIAL 0x0008
1734#define RTSTR_F_VALSIGNED 0x0010
1735#define RTSTR_F_PLUS 0x0020
1736#define RTSTR_F_BLANK 0x0040
1737#define RTSTR_F_WIDTH 0x0080
1738#define RTSTR_F_PRECISION 0x0100
1739#define RTSTR_F_THOUSAND_SEP 0x0200
1740#define RTSTR_F_OBFUSCATE_PTR 0x0400
1741
1742#define RTSTR_F_BIT_MASK 0xf800
1743#define RTSTR_F_8BIT 0x0800
1744#define RTSTR_F_16BIT 0x1000
1745#define RTSTR_F_32BIT 0x2000
1746#define RTSTR_F_64BIT 0x4000
1747#define RTSTR_F_128BIT 0x8000
1748/** @} */
1749
1750/** @def RTSTR_GET_BIT_FLAG
1751 * Gets the bit flag for the specified type.
1752 */
1753#define RTSTR_GET_BIT_FLAG(type) \
1754 ( sizeof(type) * 8 == 32 ? RTSTR_F_32BIT \
1755 : sizeof(type) * 8 == 64 ? RTSTR_F_64BIT \
1756 : sizeof(type) * 8 == 16 ? RTSTR_F_16BIT \
1757 : sizeof(type) * 8 == 8 ? RTSTR_F_8BIT \
1758 : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
1759 : 0)
1760
1761
1762/**
1763 * Callback to format non-standard format specifiers.
1764 *
1765 * @returns The number of bytes formatted.
1766 * @param pvArg Formatter argument.
1767 * @param pfnOutput Pointer to output function.
1768 * @param pvArgOutput Argument for the output function.
1769 * @param ppszFormat Pointer to the format string pointer. Advance this till the char
1770 * after the format specifier.
1771 * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
1772 * @param cchWidth Format Width. -1 if not specified.
1773 * @param cchPrecision Format Precision. -1 if not specified.
1774 * @param fFlags Flags (RTSTR_NTFS_*).
1775 * @param chArgSize The argument size specifier, 'l' or 'L'.
1776 */
1777typedef DECLCALLBACKTYPE(size_t, FNSTRFORMAT,(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
1778 const char **ppszFormat, va_list *pArgs, int cchWidth,
1779 int cchPrecision, unsigned fFlags, char chArgSize));
1780/** Pointer to a FNSTRFORMAT() function. */
1781typedef FNSTRFORMAT *PFNSTRFORMAT;
1782
1783
1784/**
1785 * Partial implementation of a printf like formatter.
1786 * It doesn't do everything correct, and there is no floating point support.
1787 * However, it supports custom formats by the means of a format callback.
1788 *
1789 * @returns number of bytes formatted.
1790 * @param pfnOutput Output worker.
1791 * Called in two ways. Normally with a string and its length.
1792 * For termination, it's called with NULL for string, 0 for length.
1793 * @param pvArgOutput Argument to the output worker.
1794 * @param pfnFormat Custom format worker.
1795 * @param pvArgFormat Argument to the format worker.
1796 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1797 * @param InArgs Argument list.
1798 */
1799RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
1800 const char *pszFormat, va_list InArgs) RT_IPRT_FORMAT_ATTR(5, 0);
1801
1802/**
1803 * Partial implementation of a printf like formatter.
1804 *
1805 * It doesn't do everything correct, and there is no floating point support.
1806 * However, it supports custom formats by the means of a format callback.
1807 *
1808 * @returns number of bytes formatted.
1809 * @param pfnOutput Output worker.
1810 * Called in two ways. Normally with a string and its length.
1811 * For termination, it's called with NULL for string, 0 for length.
1812 * @param pvArgOutput Argument to the output worker.
1813 * @param pfnFormat Custom format worker.
1814 * @param pvArgFormat Argument to the format worker.
1815 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
1816 * @param ... Argument list.
1817 */
1818RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
1819 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
1820
1821/**
1822 * Formats an integer number according to the parameters.
1823 *
1824 * @returns Length of the formatted number.
1825 * @param psz Pointer to output string buffer of sufficient size.
1826 * @param u64Value Value to format.
1827 * @param uiBase Number representation base.
1828 * @param cchWidth Width.
1829 * @param cchPrecision Precision.
1830 * @param fFlags Flags, RTSTR_F_XXX.
1831 */
1832RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision,
1833 unsigned int fFlags);
1834
1835/**
1836 * Formats an unsigned 8-bit number.
1837 *
1838 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1839 * @param pszBuf The output buffer.
1840 * @param cbBuf The size of the output buffer.
1841 * @param u8Value The value to format.
1842 * @param uiBase Number representation base.
1843 * @param cchWidth Width.
1844 * @param cchPrecision Precision.
1845 * @param fFlags Flags, RTSTR_F_XXX.
1846 */
1847RTDECL(ssize_t) RTStrFormatU8(char *pszBuf, size_t cbBuf, uint8_t u8Value, unsigned int uiBase,
1848 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1849
1850/**
1851 * Formats an unsigned 16-bit number.
1852 *
1853 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1854 * @param pszBuf The output buffer.
1855 * @param cbBuf The size of the output buffer.
1856 * @param u16Value The value to format.
1857 * @param uiBase Number representation base.
1858 * @param cchWidth Width.
1859 * @param cchPrecision Precision.
1860 * @param fFlags Flags, RTSTR_F_XXX.
1861 */
1862RTDECL(ssize_t) RTStrFormatU16(char *pszBuf, size_t cbBuf, uint16_t u16Value, unsigned int uiBase,
1863 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1864
1865/**
1866 * Formats an unsigned 32-bit number.
1867 *
1868 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1869 * @param pszBuf The output buffer.
1870 * @param cbBuf The size of the output buffer.
1871 * @param u32Value The value to format.
1872 * @param uiBase Number representation base.
1873 * @param cchWidth Width.
1874 * @param cchPrecision Precision.
1875 * @param fFlags Flags, RTSTR_F_XXX.
1876 */
1877RTDECL(ssize_t) RTStrFormatU32(char *pszBuf, size_t cbBuf, uint32_t u32Value, unsigned int uiBase,
1878 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1879
1880/**
1881 * Formats an unsigned 64-bit number.
1882 *
1883 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1884 * @param pszBuf The output buffer.
1885 * @param cbBuf The size of the output buffer.
1886 * @param u64Value The value to format.
1887 * @param uiBase Number representation base.
1888 * @param cchWidth Width.
1889 * @param cchPrecision Precision.
1890 * @param fFlags Flags, RTSTR_F_XXX.
1891 */
1892RTDECL(ssize_t) RTStrFormatU64(char *pszBuf, size_t cbBuf, uint64_t u64Value, unsigned int uiBase,
1893 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1894
1895/**
1896 * Formats an unsigned 128-bit number.
1897 *
1898 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1899 * @param pszBuf The output buffer.
1900 * @param cbBuf The size of the output buffer.
1901 * @param pu128Value The value to format.
1902 * @param uiBase Number representation base.
1903 * @param cchWidth Width.
1904 * @param cchPrecision Precision.
1905 * @param fFlags Flags, RTSTR_F_XXX.
1906 * @remarks The current implementation is limited to base 16 and doesn't do
1907 * width or precision and probably ignores few flags too.
1908 */
1909RTDECL(ssize_t) RTStrFormatU128(char *pszBuf, size_t cbBuf, PCRTUINT128U pu128Value, unsigned int uiBase,
1910 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1911
1912/**
1913 * Formats an unsigned 256-bit number.
1914 *
1915 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1916 * @param pszBuf The output buffer.
1917 * @param cbBuf The size of the output buffer.
1918 * @param pu256Value The value to format.
1919 * @param uiBase Number representation base.
1920 * @param cchWidth Width.
1921 * @param cchPrecision Precision.
1922 * @param fFlags Flags, RTSTR_F_XXX.
1923 * @remarks The current implementation is limited to base 16 and doesn't do
1924 * width or precision and probably ignores few flags too.
1925 */
1926RTDECL(ssize_t) RTStrFormatU256(char *pszBuf, size_t cbBuf, PCRTUINT256U pu256Value, unsigned int uiBase,
1927 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1928
1929/**
1930 * Formats an unsigned 512-bit number.
1931 *
1932 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1933 * @param pszBuf The output buffer.
1934 * @param cbBuf The size of the output buffer.
1935 * @param pu512Value The value to format.
1936 * @param uiBase Number representation base.
1937 * @param cchWidth Width.
1938 * @param cchPrecision Precision.
1939 * @param fFlags Flags, RTSTR_F_XXX.
1940 * @remarks The current implementation is limited to base 16 and doesn't do
1941 * width or precision and probably ignores few flags too.
1942 */
1943RTDECL(ssize_t) RTStrFormatU512(char *pszBuf, size_t cbBuf, PCRTUINT512U pu512Value, unsigned int uiBase,
1944 signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1945
1946/**
1947 * Formats an 32-bit extended floating point number.
1948 *
1949 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1950 * @param pszBuf The output buffer.
1951 * @param cbBuf The size of the output buffer.
1952 * @param pr32Value The value to format.
1953 * @param cchWidth Width.
1954 * @param cchPrecision Precision.
1955 * @param fFlags Flags, RTSTR_F_XXX.
1956 */
1957RTDECL(ssize_t) RTStrFormatR32(char *pszBuf, size_t cbBuf, PCRTFLOAT32U pr32Value, signed int cchWidth,
1958 signed int cchPrecision, uint32_t fFlags);
1959
1960/**
1961 * Formats an 64-bit extended floating point number.
1962 *
1963 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1964 * @param pszBuf The output buffer.
1965 * @param cbBuf The size of the output buffer.
1966 * @param pr64Value The value to format.
1967 * @param cchWidth Width.
1968 * @param cchPrecision Precision.
1969 * @param fFlags Flags, RTSTR_F_XXX.
1970 */
1971RTDECL(ssize_t) RTStrFormatR64(char *pszBuf, size_t cbBuf, PCRTFLOAT64U pr64Value, signed int cchWidth,
1972 signed int cchPrecision, uint32_t fFlags);
1973
1974#if !defined(__IBMCPP__) && !defined(__IBMC__)
1975
1976/**
1977 * Formats an 80-bit extended floating point number.
1978 *
1979 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1980 * @param pszBuf The output buffer.
1981 * @param cbBuf The size of the output buffer.
1982 * @param pr80Value The value to format.
1983 * @param cchWidth Width.
1984 * @param cchPrecision Precision.
1985 * @param fFlags Flags, RTSTR_F_XXX.
1986 */
1987RTDECL(ssize_t) RTStrFormatR80(char *pszBuf, size_t cbBuf, PCRTFLOAT80U pr80Value, signed int cchWidth,
1988 signed int cchPrecision, uint32_t fFlags);
1989
1990/**
1991 * Formats an 80-bit extended floating point number, version 2.
1992 *
1993 * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
1994 * @param pszBuf The output buffer.
1995 * @param cbBuf The size of the output buffer.
1996 * @param pr80Value The value to format.
1997 * @param cchWidth Width.
1998 * @param cchPrecision Precision.
1999 * @param fFlags Flags, RTSTR_F_XXX.
2000 */
2001RTDECL(ssize_t) RTStrFormatR80u2(char *pszBuf, size_t cbBuf, PCRTFLOAT80U2 pr80Value, signed int cchWidth,
2002 signed int cchPrecision, uint32_t fFlags);
2003
2004#endif /* uint16_t bitfields doesn't work */
2005
2006
2007/**
2008 * Callback for formatting a type.
2009 *
2010 * This is registered using the RTStrFormatTypeRegister function and will
2011 * be called during string formatting to handle the specified %R[type].
2012 * The argument for this format type is assumed to be a pointer and it's
2013 * passed in the @a pvValue argument.
2014 *
2015 * @returns Length of the formatted output.
2016 * @param pfnOutput Output worker.
2017 * @param pvArgOutput Argument to the output worker.
2018 * @param pszType The type name.
2019 * @param pvValue The argument value.
2020 * @param cchWidth Width.
2021 * @param cchPrecision Precision.
2022 * @param fFlags Flags (NTFS_*).
2023 * @param pvUser The user argument.
2024 */
2025typedef DECLCALLBACKTYPE(size_t, FNRTSTRFORMATTYPE,(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
2026 const char *pszType, void const *pvValue,
2027 int cchWidth, int cchPrecision, unsigned fFlags,
2028 void *pvUser));
2029/** Pointer to a FNRTSTRFORMATTYPE. */
2030typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
2031
2032
2033/**
2034 * Register a format handler for a type.
2035 *
2036 * The format handler is used to handle '%R[type]' format types, where the argument
2037 * in the vector is a pointer value (a bit restrictive, but keeps it simple).
2038 *
2039 * The caller must ensure that no other thread will be making use of any of
2040 * the dynamic formatting type facilities simultaneously with this call.
2041 *
2042 * @returns IPRT status code.
2043 * @retval VINF_SUCCESS on success.
2044 * @retval VERR_ALREADY_EXISTS if the type has already been registered.
2045 * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
2046 *
2047 * @param pszType The type name.
2048 * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
2049 * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
2050 * for how to update this later.
2051 */
2052RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
2053
2054/**
2055 * Deregisters a format type.
2056 *
2057 * The caller must ensure that no other thread will be making use of any of
2058 * the dynamic formatting type facilities simultaneously with this call.
2059 *
2060 * @returns IPRT status code.
2061 * @retval VINF_SUCCESS on success.
2062 * @retval VERR_FILE_NOT_FOUND if not found.
2063 *
2064 * @param pszType The type to deregister.
2065 */
2066RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
2067
2068/**
2069 * Sets the user argument for a type.
2070 *
2071 * This can be used if a user argument needs relocating in GC.
2072 *
2073 * @returns IPRT status code.
2074 * @retval VINF_SUCCESS on success.
2075 * @retval VERR_FILE_NOT_FOUND if not found.
2076 *
2077 * @param pszType The type to update.
2078 * @param pvUser The new user argument value.
2079 */
2080RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
2081
2082
2083/**
2084 * String printf.
2085 *
2086 * @returns The length of the returned string (in pszBuffer) excluding the
2087 * terminator.
2088 * @param pszBuffer Output buffer.
2089 * @param cchBuffer Size of the output buffer.
2090 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2091 * @param args The format argument.
2092 *
2093 * @deprecated Use RTStrPrintf2V! Problematic return value on overflow.
2094 */
2095RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2096
2097/**
2098 * String printf.
2099 *
2100 * @returns The length of the returned string (in pszBuffer) excluding the
2101 * terminator.
2102 * @param pszBuffer Output buffer.
2103 * @param cchBuffer Size of the output buffer.
2104 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2105 * @param ... The format argument.
2106 *
2107 * @deprecated Use RTStrPrintf2! Problematic return value on overflow.
2108 */
2109RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
2110
2111/**
2112 * String printf with custom formatting.
2113 *
2114 * @returns The length of the returned string (in pszBuffer) excluding the
2115 * terminator.
2116 * @param pfnFormat Pointer to handler function for the custom formats.
2117 * @param pvArg Argument to the pfnFormat function.
2118 * @param pszBuffer Output buffer.
2119 * @param cchBuffer Size of the output buffer.
2120 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2121 * @param args The format argument.
2122 *
2123 * @deprecated Use RTStrPrintf2ExV! Problematic return value on overflow.
2124 */
2125RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
2126 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0);
2127
2128/**
2129 * String printf with custom formatting.
2130 *
2131 * @returns The length of the returned string (in pszBuffer) excluding the
2132 * terminator.
2133 * @param pfnFormat Pointer to handler function for the custom formats.
2134 * @param pvArg Argument to the pfnFormat function.
2135 * @param pszBuffer Output buffer.
2136 * @param cchBuffer Size of the output buffer.
2137 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2138 * @param ... The format argument.
2139 *
2140 * @deprecated Use RTStrPrintf2Ex! Problematic return value on overflow.
2141 */
2142RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
2143 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
2144
2145/**
2146 * String printf, version 2.
2147 *
2148 * @returns On success, positive count of formatted character excluding the
2149 * terminator. On buffer overflow, negative number giving the required
2150 * buffer size (including terminator char).
2151 *
2152 * @param pszBuffer Output buffer.
2153 * @param cbBuffer Size of the output buffer.
2154 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2155 * @param args The format argument.
2156 */
2157RTDECL(ssize_t) RTStrPrintf2V(char *pszBuffer, size_t cbBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
2158
2159/**
2160 * String printf, version 2.
2161 *
2162 * @returns On success, positive count of formatted character excluding the
2163 * terminator. On buffer overflow, negative number giving the required
2164 * buffer size (including terminator char).
2165 *
2166 * @param pszBuffer Output buffer.
2167 * @param cbBuffer Size of the output buffer.
2168 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2169 * @param ... The format argument.
2170 */
2171RTDECL(ssize_t) RTStrPrintf2(char *pszBuffer, size_t cbBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
2172
2173/**
2174 * String printf with custom formatting, version 2.
2175 *
2176 * @returns On success, positive count of formatted character excluding the
2177 * terminator. On buffer overflow, negative number giving the required
2178 * buffer size (including terminator char).
2179 *
2180 * @param pfnFormat Pointer to handler function for the custom formats.
2181 * @param pvArg Argument to the pfnFormat function.
2182 * @param pszBuffer Output buffer.
2183 * @param cbBuffer Size of the output buffer.
2184 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2185 * @param args The format argument.
2186 */
2187RTDECL(ssize_t) RTStrPrintf2ExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cbBuffer,
2188 const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0);
2189
2190/**
2191 * String printf with custom formatting, version 2.
2192 *
2193 * @returns On success, positive count of formatted character excluding the
2194 * terminator. On buffer overflow, negative number giving the required
2195 * buffer size (including terminator char).
2196 *
2197 * @param pfnFormat Pointer to handler function for the custom formats.
2198 * @param pvArg Argument to the pfnFormat function.
2199 * @param pszBuffer Output buffer.
2200 * @param cbBuffer Size of the output buffer.
2201 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2202 * @param ... The format argument.
2203 */
2204RTDECL(ssize_t) RTStrPrintf2Ex(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cbBuffer,
2205 const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
2206
2207/**
2208 * Allocating string printf (default tag).
2209 *
2210 * @returns The length of the string in the returned *ppszBuffer excluding the
2211 * terminator.
2212 * @returns -1 on failure.
2213 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
2214 * The buffer should be freed using RTStrFree().
2215 * On failure *ppszBuffer will be set to NULL.
2216 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2217 * @param args The format argument.
2218 */
2219#define RTStrAPrintfV(ppszBuffer, pszFormat, args) RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
2220
2221/**
2222 * Allocating string printf (custom tag).
2223 *
2224 * @returns The length of the string in the returned *ppszBuffer excluding the
2225 * terminator.
2226 * @returns -1 on failure.
2227 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
2228 * The buffer should be freed using RTStrFree().
2229 * On failure *ppszBuffer will be set to NULL.
2230 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2231 * @param args The format argument.
2232 * @param pszTag Allocation tag used for statistics and such.
2233 */
2234RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer, const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(2, 0);
2235
2236/**
2237 * Allocating string printf.
2238 *
2239 * @returns The length of the string in the returned *ppszBuffer excluding the
2240 * terminator.
2241 * @returns -1 on failure.
2242 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
2243 * The buffer should be freed using RTStrFree().
2244 * On failure *ppszBuffer will be set to NULL.
2245 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2246 * @param ... The format argument.
2247 */
2248DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...)
2249{
2250 int cbRet;
2251 va_list va;
2252 va_start(va, pszFormat);
2253 cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, RTSTR_TAG);
2254 va_end(va);
2255 return cbRet;
2256}
2257
2258/**
2259 * Allocating string printf (custom tag).
2260 *
2261 * @returns The length of the string in the returned *ppszBuffer excluding the
2262 * terminator.
2263 * @returns -1 on failure.
2264 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
2265 * The buffer should be freed using RTStrFree().
2266 * On failure *ppszBuffer will be set to NULL.
2267 * @param pszTag Allocation tag used for statistics and such.
2268 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2269 * @param ... The format argument.
2270 */
2271DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer, const char *pszTag, const char *pszFormat, ...)
2272{
2273 int cbRet;
2274 va_list va;
2275 va_start(va, pszFormat);
2276 cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, pszTag);
2277 va_end(va);
2278 return cbRet;
2279}
2280
2281/**
2282 * Allocating string printf, version 2.
2283 *
2284 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2285 * memory.
2286 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2287 * @param args The format argument.
2288 */
2289#define RTStrAPrintf2V(pszFormat, args) RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
2290
2291/**
2292 * Allocating string printf, version 2.
2293 *
2294 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2295 * memory.
2296 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2297 * @param args The format argument.
2298 * @param pszTag Allocation tag used for statistics and such.
2299 */
2300RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(1, 0);
2301
2302/**
2303 * Allocating string printf, version 2 (default tag).
2304 *
2305 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2306 * memory.
2307 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2308 * @param ... The format argument.
2309 */
2310DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat, ...)
2311{
2312 char *pszRet;
2313 va_list va;
2314 va_start(va, pszFormat);
2315 pszRet = RTStrAPrintf2VTag(pszFormat, va, RTSTR_TAG);
2316 va_end(va);
2317 return pszRet;
2318}
2319
2320/**
2321 * Allocating string printf, version 2 (custom tag).
2322 *
2323 * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
2324 * memory.
2325 * @param pszTag Allocation tag used for statistics and such.
2326 * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
2327 * @param ... The format argument.
2328 */
2329DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag, const char *pszFormat, ...)
2330{
2331 char *pszRet;
2332 va_list va;
2333 va_start(va, pszFormat);
2334 pszRet = RTStrAPrintf2VTag(pszFormat, va, pszTag);
2335 va_end(va);
2336 return pszRet;
2337}
2338
2339/**
2340 * Strips blankspaces from both ends of the string.
2341 *
2342 * @returns Pointer to first non-blank char in the string.
2343 * @param psz The string to strip.
2344 */
2345RTDECL(char *) RTStrStrip(char *psz);
2346
2347/**
2348 * Strips blankspaces from the start of the string.
2349 *
2350 * @returns Pointer to first non-blank char in the string.
2351 * @param psz The string to strip.
2352 */
2353RTDECL(char *) RTStrStripL(const char *psz);
2354
2355/**
2356 * Strips blankspaces from the end of the string.
2357 *
2358 * @returns psz.
2359 * @param psz The string to strip.
2360 */
2361RTDECL(char *) RTStrStripR(char *psz);
2362
2363/**
2364 * String copy with overflow handling.
2365 *
2366 * @retval VINF_SUCCESS on success.
2367 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2368 * buffer will contain as much of the string as it can hold, fully
2369 * terminated.
2370 *
2371 * @param pszDst The destination buffer.
2372 * @param cbDst The size of the destination buffer (in bytes).
2373 * @param pszSrc The source string. NULL is not OK.
2374 */
2375RTDECL(int) RTStrCopy(char *pszDst, size_t cbDst, const char *pszSrc);
2376
2377/**
2378 * String copy with overflow handling.
2379 *
2380 * @retval VINF_SUCCESS on success.
2381 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2382 * buffer will contain as much of the string as it can hold, fully
2383 * terminated.
2384 *
2385 * @param pszDst The destination buffer.
2386 * @param cbDst The size of the destination buffer (in bytes).
2387 * @param pszSrc The source string. NULL is not OK.
2388 * @param cchSrcMax The maximum number of chars (not code points) to
2389 * copy from the source string, not counting the
2390 * terminator as usual.
2391 */
2392RTDECL(int) RTStrCopyEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
2393
2394/**
2395 * String copy with overflow handling and buffer advancing.
2396 *
2397 * @retval VINF_SUCCESS on success.
2398 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2399 * buffer will contain as much of the string as it can hold, fully
2400 * terminated.
2401 *
2402 * @param ppszDst Pointer to the destination buffer pointer.
2403 * This will be advanced to the end of the copied
2404 * bytes (points at the terminator). This is also
2405 * updated on overflow.
2406 * @param pcbDst Pointer to the destination buffer size
2407 * variable. This will be updated in accord with
2408 * the buffer pointer.
2409 * @param pszSrc The source string. NULL is not OK.
2410 */
2411RTDECL(int) RTStrCopyP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
2412
2413/**
2414 * String copy with overflow handling.
2415 *
2416 * @retval VINF_SUCCESS on success.
2417 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2418 * buffer will contain as much of the string as it can hold, fully
2419 * terminated.
2420 *
2421 * @param ppszDst Pointer to the destination buffer pointer.
2422 * This will be advanced to the end of the copied
2423 * bytes (points at the terminator). This is also
2424 * updated on overflow.
2425 * @param pcbDst Pointer to the destination buffer size
2426 * variable. This will be updated in accord with
2427 * the buffer pointer.
2428 * @param pszSrc The source string. NULL is not OK.
2429 * @param cchSrcMax The maximum number of chars (not code points) to
2430 * copy from the source string, not counting the
2431 * terminator as usual.
2432 */
2433RTDECL(int) RTStrCopyPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
2434
2435/**
2436 * String concatenation with overflow handling.
2437 *
2438 * @retval VINF_SUCCESS on success.
2439 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2440 * buffer will contain as much of the string as it can hold, fully
2441 * terminated.
2442 *
2443 * @param pszDst The destination buffer.
2444 * @param cbDst The size of the destination buffer (in bytes).
2445 * @param pszSrc The source string. NULL is not OK.
2446 */
2447RTDECL(int) RTStrCat(char *pszDst, size_t cbDst, const char *pszSrc);
2448
2449/**
2450 * String concatenation with overflow handling.
2451 *
2452 * @retval VINF_SUCCESS on success.
2453 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2454 * buffer will contain as much of the string as it can hold, fully
2455 * terminated.
2456 *
2457 * @param pszDst The destination buffer.
2458 * @param cbDst The size of the destination buffer (in bytes).
2459 * @param pszSrc The source string. NULL is not OK.
2460 * @param cchSrcMax The maximum number of chars (not code points) to
2461 * copy from the source string, not counting the
2462 * terminator as usual.
2463 */
2464RTDECL(int) RTStrCatEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
2465
2466/**
2467 * String concatenation with overflow handling.
2468 *
2469 * @retval VINF_SUCCESS on success.
2470 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2471 * buffer will contain as much of the string as it can hold, fully
2472 * terminated.
2473 *
2474 * @param ppszDst Pointer to the destination buffer pointer.
2475 * This will be advanced to the end of the copied
2476 * bytes (points at the terminator). This is also
2477 * updated on overflow.
2478 * @param pcbDst Pointer to the destination buffer size
2479 * variable. This will be updated in accord with
2480 * the buffer pointer.
2481 * @param pszSrc The source string. NULL is not OK.
2482 */
2483RTDECL(int) RTStrCatP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
2484
2485/**
2486 * String concatenation with overflow handling and buffer advancing.
2487 *
2488 * @retval VINF_SUCCESS on success.
2489 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
2490 * buffer will contain as much of the string as it can hold, fully
2491 * terminated.
2492 *
2493 * @param ppszDst Pointer to the destination buffer pointer.
2494 * This will be advanced to the end of the copied
2495 * bytes (points at the terminator). This is also
2496 * updated on overflow.
2497 * @param pcbDst Pointer to the destination buffer size
2498 * variable. This will be updated in accord with
2499 * the buffer pointer.
2500 * @param pszSrc The source string. NULL is not OK.
2501 * @param cchSrcMax The maximum number of chars (not code points) to
2502 * copy from the source string, not counting the
2503 * terminator as usual.
2504 */
2505RTDECL(int) RTStrCatPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
2506
2507/**
2508 * Performs a case sensitive string compare between two UTF-8 strings.
2509 *
2510 * Encoding errors are ignored by the current implementation. So, the only
2511 * difference between this and the CRT strcmp function is the handling of
2512 * NULL arguments.
2513 *
2514 * @returns < 0 if the first string less than the second string.
2515 * @returns 0 if the first string identical to the second string.
2516 * @returns > 0 if the first string greater than the second string.
2517 * @param psz1 First UTF-8 string. Null is allowed.
2518 * @param psz2 Second UTF-8 string. Null is allowed.
2519 */
2520RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
2521
2522/**
2523 * Performs a case sensitive string compare between two UTF-8 strings, given
2524 * a maximum string length.
2525 *
2526 * Encoding errors are ignored by the current implementation. So, the only
2527 * difference between this and the CRT strncmp function is the handling of
2528 * NULL arguments.
2529 *
2530 * @returns < 0 if the first string less than the second string.
2531 * @returns 0 if the first string identical to the second string.
2532 * @returns > 0 if the first string greater than the second string.
2533 * @param psz1 First UTF-8 string. Null is allowed.
2534 * @param psz2 Second UTF-8 string. Null is allowed.
2535 * @param cchMax The maximum string length
2536 */
2537RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
2538
2539/**
2540 * Performs a case insensitive string compare between two UTF-8 strings.
2541 *
2542 * This is a simplified compare, as only the simplified lower/upper case folding
2543 * specified by the unicode specs are used. It does not consider character pairs
2544 * as they are used in some languages, just simple upper & lower case compares.
2545 *
2546 * The result is the difference between the mismatching codepoints after they
2547 * both have been lower cased.
2548 *
2549 * If the string encoding is invalid the function will assert (strict builds)
2550 * and use RTStrCmp for the remainder of the string.
2551 *
2552 * @returns < 0 if the first string less than the second string.
2553 * @returns 0 if the first string identical to the second string.
2554 * @returns > 0 if the first string greater than the second string.
2555 * @param psz1 First UTF-8 string. Null is allowed.
2556 * @param psz2 Second UTF-8 string. Null is allowed.
2557 */
2558RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
2559
2560/**
2561 * Performs a case insensitive string compare between two UTF-8 strings, given a
2562 * maximum string length.
2563 *
2564 * This is a simplified compare, as only the simplified lower/upper case folding
2565 * specified by the unicode specs are used. It does not consider character pairs
2566 * as they are used in some languages, just simple upper & lower case compares.
2567 *
2568 * The result is the difference between the mismatching codepoints after they
2569 * both have been lower cased.
2570 *
2571 * If the string encoding is invalid the function will assert (strict builds)
2572 * and use RTStrNCmp for the remainder of the string.
2573 *
2574 * @returns < 0 if the first string less than the second string.
2575 * @returns 0 if the first string identical to the second string.
2576 * @returns > 0 if the first string greater than the second string.
2577 * @param psz1 First UTF-8 string. Null is allowed.
2578 * @param psz2 Second UTF-8 string. Null is allowed.
2579 * @param cchMax Maximum string length
2580 */
2581RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
2582
2583/**
2584 * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
2585 * ASCII string.
2586 *
2587 * This is potentially faster than RTStrICmp and drags in less dependencies. It
2588 * is really handy for hardcoded inputs.
2589 *
2590 * If the string encoding is invalid the function will assert (strict builds)
2591 * and use RTStrCmp for the remainder of the string.
2592 *
2593 * @returns < 0 if the first string less than the second string.
2594 * @returns 0 if the first string identical to the second string.
2595 * @returns > 0 if the first string greater than the second string.
2596 * @param psz1 First UTF-8 string. Null is allowed.
2597 * @param psz2 Second string, 7-bit ASCII. Null is allowed.
2598 * @sa RTStrICmp, RTUtf16ICmpAscii
2599 */
2600RTDECL(int) RTStrICmpAscii(const char *psz1, const char *psz2);
2601
2602/**
2603 * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
2604 * ASCII string, given a maximum string length.
2605 *
2606 * This is potentially faster than RTStrNICmp and drags in less dependencies.
2607 * It is really handy for hardcoded inputs.
2608 *
2609 * If the string encoding is invalid the function will assert (strict builds)
2610 * and use RTStrNCmp for the remainder of the string.
2611 *
2612 * @returns < 0 if the first string less than the second string.
2613 * @returns 0 if the first string identical to the second string.
2614 * @returns > 0 if the first string greater than the second string.
2615 * @param psz1 First UTF-8 string. Null is allowed.
2616 * @param psz2 Second string, 7-bit ASCII. Null is allowed.
2617 * @param cchMax Maximum string length
2618 * @sa RTStrNICmp, RTUtf16NICmpAscii
2619 */
2620RTDECL(int) RTStrNICmpAscii(const char *psz1, const char *psz2, size_t cchMax);
2621
2622/**
2623 * Checks whether @a pszString starts with @a pszStart.
2624 *
2625 * @returns true / false.
2626 * @param pszString The string to check.
2627 * @param pszStart The start string to check for.
2628 */
2629RTDECL(bool) RTStrStartsWith(const char *pszString, const char *pszStart);
2630
2631/**
2632 * Checks whether @a pszString starts with @a pszStart, case insensitive.
2633 *
2634 * @returns true / false.
2635 * @param pszString The string to check.
2636 * @param pszStart The start string to check for.
2637 */
2638RTDECL(bool) RTStrIStartsWith(const char *pszString, const char *pszStart);
2639
2640/**
2641 * Splits a string buffer with a given separator into separate strings.
2642 * If no separators are found, no strings are returned. Consequtive separators will be skipped.
2643 *
2644 * @returns iprt status code.
2645 * @param pcszStrings String buffer to split.
2646 * @param cbStrings Size (in bytes) of string buffer to split, including terminator.
2647 * @param pcszSeparator Separator to use / find for splitting strings.
2648 * @param ppapszStrings Where to return the allocated string array on success. Needs to be free'd by the caller.
2649 * @param pcStrings Where to return the number of split strings in \a ppapszStrings.
2650 */
2651RTDECL(int) RTStrSplit(const char *pcszStrings, size_t cbStrings,
2652 const char *pcszSeparator, char ***ppapszStrings, size_t *pcStrings);
2653
2654/**
2655 * Locates a case sensitive substring.
2656 *
2657 * If any of the two strings are NULL, then NULL is returned. If the needle is
2658 * an empty string, then the haystack is returned (i.e. matches anything).
2659 *
2660 * @returns Pointer to the first occurrence of the substring if found, NULL if
2661 * not.
2662 *
2663 * @param pszHaystack The string to search.
2664 * @param pszNeedle The substring to search for.
2665 *
2666 * @remarks The difference between this and strstr is the handling of NULL
2667 * pointers.
2668 */
2669RTDECL(char *) RTStrStr(const char *pszHaystack, const char *pszNeedle);
2670
2671/**
2672 * Locates a case insensitive substring.
2673 *
2674 * If any of the two strings are NULL, then NULL is returned. If the needle is
2675 * an empty string, then the haystack is returned (i.e. matches anything).
2676 *
2677 * @returns Pointer to the first occurrence of the substring if found, NULL if
2678 * not.
2679 *
2680 * @param pszHaystack The string to search.
2681 * @param pszNeedle The substring to search for.
2682 *
2683 */
2684RTDECL(char *) RTStrIStr(const char *pszHaystack, const char *pszNeedle);
2685
2686/**
2687 * Converts the string to lower case.
2688 *
2689 * @returns Pointer to the converted string.
2690 * @param psz The string to convert.
2691 */
2692RTDECL(char *) RTStrToLower(char *psz);
2693
2694/**
2695 * Converts the string to upper case.
2696 *
2697 * @returns Pointer to the converted string.
2698 * @param psz The string to convert.
2699 */
2700RTDECL(char *) RTStrToUpper(char *psz);
2701
2702/**
2703 * Checks if the string is case foldable, i.e. whether it would change if
2704 * subject to RTStrToLower or RTStrToUpper.
2705 *
2706 * @returns true / false
2707 * @param psz The string in question.
2708 */
2709RTDECL(bool) RTStrIsCaseFoldable(const char *psz);
2710
2711/**
2712 * Checks if the string is upper cased (no lower case chars in it).
2713 *
2714 * @returns true / false
2715 * @param psz The string in question.
2716 */
2717RTDECL(bool) RTStrIsUpperCased(const char *psz);
2718
2719/**
2720 * Checks if the string is lower cased (no upper case chars in it).
2721 *
2722 * @returns true / false
2723 * @param psz The string in question.
2724 */
2725RTDECL(bool) RTStrIsLowerCased(const char *psz);
2726
2727/**
2728 * Find the length of a zero-terminated byte string, given
2729 * a max string length.
2730 *
2731 * See also RTStrNLenEx.
2732 *
2733 * @returns The string length or cbMax. The returned length does not include
2734 * the zero terminator if it was found.
2735 *
2736 * @param pszString The string.
2737 * @param cchMax The max string length.
2738 */
2739RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
2740
2741/**
2742 * Find the length of a zero-terminated byte string, given
2743 * a max string length.
2744 *
2745 * See also RTStrNLen.
2746 *
2747 * @returns IPRT status code.
2748 * @retval VINF_SUCCESS if the string has a length less than cchMax.
2749 * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
2750 * before cchMax was reached.
2751 *
2752 * @param pszString The string.
2753 * @param cchMax The max string length.
2754 * @param pcch Where to store the string length excluding the
2755 * terminator. This is set to cchMax if the terminator
2756 * isn't found.
2757 */
2758RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
2759
2760/** The maximum size argument of a memchr call. */
2761#define RTSTR_MEMCHR_MAX ((~(size_t)0 >> 1) - 15)
2762
2763/**
2764 * Find the zero terminator in a string with a limited length.
2765 *
2766 * @returns Pointer to the zero terminator.
2767 * @returns NULL if the zero terminator was not found.
2768 *
2769 * @param pszString The string.
2770 * @param cchMax The max string length. RTSTR_MAX is fine.
2771 */
2772RTDECL(char *) RTStrEnd(char const *pszString, size_t cchMax);
2773
2774/**
2775 * Finds the offset at which a simple character first occurs in a string.
2776 *
2777 * @returns The offset of the first occurence or the terminator offset.
2778 * @param pszHaystack The string to search.
2779 * @param chNeedle The character to search for.
2780 */
2781DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack, char chNeedle)
2782{
2783 const char *psz = pszHaystack;
2784 char ch;
2785 while ( (ch = *psz) != chNeedle
2786 && ch != '\0')
2787 psz++;
2788 return (size_t)(psz - pszHaystack);
2789}
2790
2791/**
2792 * Matches a simple string pattern.
2793 *
2794 * @returns true if the string matches the pattern, otherwise false.
2795 *
2796 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2797 * asterisk matches zero or more characters and question
2798 * mark matches exactly one character.
2799 * @param pszString The string to match against the pattern.
2800 */
2801RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
2802
2803/**
2804 * Matches a simple string pattern, neither which needs to be zero terminated.
2805 *
2806 * This is identical to RTStrSimplePatternMatch except that you can optionally
2807 * specify the length of both the pattern and the string. The function will
2808 * stop when it hits a string terminator or either of the lengths.
2809 *
2810 * @returns true if the string matches the pattern, otherwise false.
2811 *
2812 * @param pszPattern The pattern. Special chars are '*' and '?', where the
2813 * asterisk matches zero or more characters and question
2814 * mark matches exactly one character.
2815 * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
2816 * length and wish to stop at the string terminator.
2817 * @param pszString The string to match against the pattern.
2818 * @param cchString The string length. Pass RTSTR_MAX if you don't know the
2819 * length and wish to match up to the string terminator.
2820 */
2821RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
2822 const char *pszString, size_t cchString);
2823
2824/**
2825 * Matches multiple patterns against a string.
2826 *
2827 * The patterns are separated by the pipe character (|).
2828 *
2829 * @returns true if the string matches the pattern, otherwise false.
2830 *
2831 * @param pszPatterns The patterns.
2832 * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
2833 * stop at the terminator.
2834 * @param pszString The string to match against the pattern.
2835 * @param cchString The string length. Pass RTSTR_MAX stop stop at the
2836 * terminator.
2837 * @param poffPattern Offset into the patterns string of the patttern that
2838 * matched. If no match, this will be set to RTSTR_MAX.
2839 * This is optional, NULL is fine.
2840 */
2841RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
2842 const char *pszString, size_t cchString,
2843 size_t *poffPattern);
2844
2845/**
2846 * Compares two version strings RTStrICmp fashion.
2847 *
2848 * The version string is split up into sections at punctuation, spaces,
2849 * underscores, dashes and plus signs. The sections are then split up into
2850 * numeric and string sub-sections. Finally, the sub-sections are compared
2851 * in a numeric or case insesntivie fashion depending on what they are.
2852 *
2853 * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
2854 * "1". These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
2855 *
2856 * @returns < 0 if the first string less than the second string.
2857 * @returns 0 if the first string identical to the second string.
2858 * @returns > 0 if the first string greater than the second string.
2859 *
2860 * @param pszVer1 First version string to compare.
2861 * @param pszVer2 Second version string to compare first version with.
2862 */
2863RTDECL(int) RTStrVersionCompare(const char *pszVer1, const char *pszVer2);
2864
2865
2866/** @defgroup rt_str_conv String To/From Number Conversions
2867 * @{ */
2868
2869/**
2870 * Converts a string representation of a number to a 64-bit unsigned number.
2871 *
2872 * @returns iprt status code.
2873 * Warnings are used to indicate conversion problems.
2874 * @retval VWRN_NUMBER_TOO_BIG
2875 * @retval VWRN_NEGATIVE_UNSIGNED
2876 * @retval VWRN_TRAILING_CHARS
2877 * @retval VWRN_TRAILING_SPACES
2878 * @retval VINF_SUCCESS
2879 * @retval VERR_NO_DIGITS
2880 *
2881 * @param pszValue Pointer to the string value.
2882 * @param ppszNext Where to store the pointer to the first char
2883 * following the number. (Optional)
2884 * @param uBaseAndMaxLen The low byte is the base of the representation, the
2885 * upper 24 bits are the max length to parse. If the base
2886 * is zero the function will look for known prefixes before
2887 * defaulting to 10. A max length of zero means no length
2888 * restriction.
2889 * @param pu64 Where to store the converted number. (optional)
2890 */
2891RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint64_t *pu64);
2892
2893/**
2894 * Converts a string representation of a number to a 64-bit unsigned number,
2895 * making sure the full string is converted.
2896 *
2897 * @returns iprt status code.
2898 * Warnings are used to indicate conversion problems.
2899 * @retval VWRN_NUMBER_TOO_BIG
2900 * @retval VWRN_NEGATIVE_UNSIGNED
2901 * @retval VINF_SUCCESS
2902 * @retval VERR_NO_DIGITS
2903 * @retval VERR_TRAILING_SPACES
2904 * @retval VERR_TRAILING_CHARS
2905 *
2906 * @param pszValue Pointer to the string value.
2907 * @param uBaseAndMaxLen The low byte is the base of the representation, the
2908 * upper 24 bits are the max length to parse. If the base
2909 * is zero the function will look for known prefixes before
2910 * defaulting to 10. A max length of zero means no length
2911 * restriction.
2912 * @param pu64 Where to store the converted number. (optional)
2913 */
2914RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, uint64_t *pu64);
2915
2916/**
2917 * Converts a string representation of a number to a 64-bit unsigned number.
2918 * The base is guessed.
2919 *
2920 * @returns 64-bit unsigned number on success.
2921 * @returns 0 on failure.
2922 * @param pszValue Pointer to the string value.
2923 */
2924RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
2925
2926/**
2927 * Converts a string representation of a number to a 32-bit unsigned number.
2928 *
2929 * @returns iprt status code.
2930 * Warnings are used to indicate conversion problems.
2931 * @retval VWRN_NUMBER_TOO_BIG
2932 * @retval VWRN_NEGATIVE_UNSIGNED
2933 * @retval VWRN_TRAILING_CHARS
2934 * @retval VWRN_TRAILING_SPACES
2935 * @retval VINF_SUCCESS
2936 * @retval VERR_NO_DIGITS
2937 *
2938 * @param pszValue Pointer to the string value.
2939 * @param ppszNext Where to store the pointer to the first char
2940 * following the number. (Optional)
2941 * @param uBaseAndMaxLen The low byte is the base of the representation, the
2942 * upper 24 bits are the max length to parse. If the base
2943 * is zero the function will look for known prefixes before
2944 * defaulting to 10. A max length of zero means no length
2945 * restriction.
2946 * @param pu32 Where to store the converted number. (optional)
2947 */
2948RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint32_t *pu32);
2949
2950/**
2951 * Converts a string representation of a number to a 32-bit unsigned number,
2952 * making sure the full string is converted.
2953 *
2954 * @returns iprt status code.
2955 * Warnings are used to indicate conversion problems.
2956 * @retval VWRN_NUMBER_TOO_BIG
2957 * @retval VWRN_NEGATIVE_UNSIGNED
2958 * @retval VINF_SUCCESS
2959 * @retval VERR_NO_DIGITS
2960 * @retval VERR_TRAILING_SPACES
2961 * @retval VERR_TRAILING_CHARS
2962 *
2963 * @param pszValue Pointer to the string value.
2964 * @param uBaseAndMaxLen The low byte is the base of the representation, the
2965 * upper 24 bits are the max length to parse. If the base
2966 * is zero the function will look for known prefixes before
2967 * defaulting to 10. A max length of zero means no length
2968 * restriction.
2969 * @param pu32 Where to store the converted number. (optional)
2970 */
2971RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, uint32_t *pu32);
2972
2973/**
2974 * Converts a string representation of a number to a 32-bit unsigned number.
2975 * The base is guessed.
2976 *
2977 * @returns 32-bit unsigned number on success.
2978 * @returns 0 on failure.
2979 * @param pszValue Pointer to the string value.
2980 */
2981RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
2982
2983/**
2984 * Converts a string representation of a number to a 16-bit unsigned number.
2985 *
2986 * @returns iprt status code.
2987 * Warnings are used to indicate conversion problems.
2988 * @retval VWRN_NUMBER_TOO_BIG
2989 * @retval VWRN_NEGATIVE_UNSIGNED
2990 * @retval VWRN_TRAILING_CHARS
2991 * @retval VWRN_TRAILING_SPACES
2992 * @retval VINF_SUCCESS
2993 * @retval VERR_NO_DIGITS
2994 *
2995 * @param pszValue Pointer to the string value.
2996 * @param ppszNext Where to store the pointer to the first char
2997 * following the number. (Optional)
2998 * @param uBaseAndMaxLen The low byte is the base of the representation, the
2999 * upper 24 bits are the max length to parse. If the base
3000 * is zero the function will look for known prefixes before
3001 * defaulting to 10. A max length of zero means no length
3002 * restriction.
3003 * @param pu16 Where to store the converted number. (optional)
3004 */
3005RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint16_t *pu16);
3006
3007/**
3008 * Converts a string representation of a number to a 16-bit unsigned number,
3009 * making sure the full string is converted.
3010 *
3011 * @returns iprt status code.
3012 * Warnings are used to indicate conversion problems.
3013 * @retval VWRN_NUMBER_TOO_BIG
3014 * @retval VWRN_NEGATIVE_UNSIGNED
3015 * @retval VINF_SUCCESS
3016 * @retval VERR_NO_DIGITS
3017 * @retval VERR_TRAILING_SPACES
3018 * @retval VERR_TRAILING_CHARS
3019 *
3020 * @param pszValue Pointer to the string value.
3021 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3022 * upper 24 bits are the max length to parse. If the base
3023 * is zero the function will look for known prefixes before
3024 * defaulting to 10. A max length of zero means no length
3025 * restriction.
3026 * @param pu16 Where to store the converted number. (optional)
3027 */
3028RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, uint16_t *pu16);
3029
3030/**
3031 * Converts a string representation of a number to a 16-bit unsigned number.
3032 * The base is guessed.
3033 *
3034 * @returns 16-bit unsigned number on success.
3035 * @returns 0 on failure.
3036 * @param pszValue Pointer to the string value.
3037 */
3038RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
3039
3040/**
3041 * Converts a string representation of a number to a 8-bit unsigned number.
3042 *
3043 * @returns iprt status code.
3044 * Warnings are used to indicate conversion problems.
3045 * @retval VWRN_NUMBER_TOO_BIG
3046 * @retval VWRN_NEGATIVE_UNSIGNED
3047 * @retval VWRN_TRAILING_CHARS
3048 * @retval VWRN_TRAILING_SPACES
3049 * @retval VINF_SUCCESS
3050 * @retval VERR_NO_DIGITS
3051 *
3052 * @param pszValue Pointer to the string value.
3053 * @param ppszNext Where to store the pointer to the first char
3054 * following the number. (Optional)
3055 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3056 * upper 24 bits are the max length to parse. If the base
3057 * is zero the function will look for known prefixes before
3058 * defaulting to 10. A max length of zero means no length
3059 * restriction.
3060 * @param pu8 Where to store the converted number. (optional)
3061 */
3062RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint8_t *pu8);
3063
3064/**
3065 * Converts a string representation of a number to a 8-bit unsigned number,
3066 * making sure the full string is converted.
3067 *
3068 * @returns iprt status code.
3069 * Warnings are used to indicate conversion problems.
3070 * @retval VWRN_NUMBER_TOO_BIG
3071 * @retval VWRN_NEGATIVE_UNSIGNED
3072 * @retval VINF_SUCCESS
3073 * @retval VERR_NO_DIGITS
3074 * @retval VERR_TRAILING_SPACES
3075 * @retval VERR_TRAILING_CHARS
3076 *
3077 * @param pszValue Pointer to the string value.
3078 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3079 * upper 24 bits are the max length to parse. If the base
3080 * is zero the function will look for known prefixes before
3081 * defaulting to 10. A max length of zero means no length
3082 * restriction.
3083 * @param pu8 Where to store the converted number. (optional)
3084 */
3085RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, uint8_t *pu8);
3086
3087/**
3088 * Converts a string representation of a number to a 8-bit unsigned number.
3089 * The base is guessed.
3090 *
3091 * @returns 8-bit unsigned number on success.
3092 * @returns 0 on failure.
3093 * @param pszValue Pointer to the string value.
3094 */
3095RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
3096
3097/**
3098 * Converts a string representation of a number to a 64-bit signed number.
3099 *
3100 * @returns iprt status code.
3101 * Warnings are used to indicate conversion problems.
3102 * @retval VWRN_NUMBER_TOO_BIG
3103 * @retval VWRN_TRAILING_CHARS
3104 * @retval VWRN_TRAILING_SPACES
3105 * @retval VINF_SUCCESS
3106 * @retval VERR_NO_DIGITS
3107 *
3108 * @param pszValue Pointer to the string value.
3109 * @param ppszNext Where to store the pointer to the first char
3110 * following the number. (Optional)
3111 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3112 * upper 24 bits are the max length to parse. If the base
3113 * is zero the function will look for known prefixes before
3114 * defaulting to 10. A max length of zero means no length
3115 * restriction.
3116 * @param pi64 Where to store the converted number. (optional)
3117 */
3118RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int64_t *pi64);
3119
3120/**
3121 * Converts a string representation of a number to a 64-bit signed number,
3122 * making sure the full string is converted.
3123 *
3124 * @returns iprt status code.
3125 * Warnings are used to indicate conversion problems.
3126 * @retval VWRN_NUMBER_TOO_BIG
3127 * @retval VINF_SUCCESS
3128 * @retval VERR_TRAILING_CHARS
3129 * @retval VERR_TRAILING_SPACES
3130 * @retval VERR_NO_DIGITS
3131 *
3132 * @param pszValue Pointer to the string value.
3133 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3134 * upper 24 bits are the max length to parse. If the base
3135 * is zero the function will look for known prefixes before
3136 * defaulting to 10. A max length of zero means no length
3137 * restriction.
3138 * @param pi64 Where to store the converted number. (optional)
3139 */
3140RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, int64_t *pi64);
3141
3142/**
3143 * Converts a string representation of a number to a 64-bit signed number.
3144 * The base is guessed.
3145 *
3146 * @returns 64-bit signed number on success.
3147 * @returns 0 on failure.
3148 * @param pszValue Pointer to the string value.
3149 */
3150RTDECL(int64_t) RTStrToInt64(const char *pszValue);
3151
3152/**
3153 * Converts a string representation of a number to a 32-bit signed number.
3154 *
3155 * @returns iprt status code.
3156 * Warnings are used to indicate conversion problems.
3157 * @retval VWRN_NUMBER_TOO_BIG
3158 * @retval VWRN_TRAILING_CHARS
3159 * @retval VWRN_TRAILING_SPACES
3160 * @retval VINF_SUCCESS
3161 * @retval VERR_NO_DIGITS
3162 *
3163 * @param pszValue Pointer to the string value.
3164 * @param ppszNext Where to store the pointer to the first char
3165 * following the number. (Optional)
3166 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3167 * upper 24 bits are the max length to parse. If the base
3168 * is zero the function will look for known prefixes before
3169 * defaulting to 10. A max length of zero means no length
3170 * restriction.
3171 * @param pi32 Where to store the converted number. (optional)
3172 */
3173RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int32_t *pi32);
3174
3175/**
3176 * Converts a string representation of a number to a 32-bit signed number,
3177 * making sure the full string is converted.
3178 *
3179 * @returns iprt status code.
3180 * Warnings are used to indicate conversion problems.
3181 * @retval VWRN_NUMBER_TOO_BIG
3182 * @retval VINF_SUCCESS
3183 * @retval VERR_TRAILING_CHARS
3184 * @retval VERR_TRAILING_SPACES
3185 * @retval VERR_NO_DIGITS
3186 *
3187 * @param pszValue Pointer to the string value.
3188 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3189 * upper 24 bits are the max length to parse. If the base
3190 * is zero the function will look for known prefixes before
3191 * defaulting to 10. A max length of zero means no length
3192 * restriction.
3193 * @param pi32 Where to store the converted number. (optional)
3194 */
3195RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, int32_t *pi32);
3196
3197/**
3198 * Converts a string representation of a number to a 32-bit signed number.
3199 * The base is guessed.
3200 *
3201 * @returns 32-bit signed number on success.
3202 * @returns 0 on failure.
3203 * @param pszValue Pointer to the string value.
3204 */
3205RTDECL(int32_t) RTStrToInt32(const char *pszValue);
3206
3207/**
3208 * Converts a string representation of a number to a 16-bit signed number.
3209 *
3210 * @returns iprt status code.
3211 * Warnings are used to indicate conversion problems.
3212 * @retval VWRN_NUMBER_TOO_BIG
3213 * @retval VWRN_TRAILING_CHARS
3214 * @retval VWRN_TRAILING_SPACES
3215 * @retval VINF_SUCCESS
3216 * @retval VERR_NO_DIGITS
3217 *
3218 * @param pszValue Pointer to the string value.
3219 * @param ppszNext Where to store the pointer to the first char
3220 * following the number. (Optional)
3221 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3222 * upper 24 bits are the max length to parse. If the base
3223 * is zero the function will look for known prefixes before
3224 * defaulting to 10. A max length of zero means no length
3225 * restriction.
3226 * @param pi16 Where to store the converted number. (optional)
3227 */
3228RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int16_t *pi16);
3229
3230/**
3231 * Converts a string representation of a number to a 16-bit signed number,
3232 * making sure the full string is converted.
3233 *
3234 * @returns iprt status code.
3235 * Warnings are used to indicate conversion problems.
3236 * @retval VWRN_NUMBER_TOO_BIG
3237 * @retval VINF_SUCCESS
3238 * @retval VERR_TRAILING_CHARS
3239 * @retval VERR_TRAILING_SPACES
3240 * @retval VERR_NO_DIGITS
3241 *
3242 * @param pszValue Pointer to the string value.
3243 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3244 * upper 24 bits are the max length to parse. If the base
3245 * is zero the function will look for known prefixes before
3246 * defaulting to 10. A max length of zero means no length
3247 * restriction.
3248 * @param pi16 Where to store the converted number. (optional)
3249 */
3250RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, int16_t *pi16);
3251
3252/**
3253 * Converts a string representation of a number to a 16-bit signed number.
3254 * The base is guessed.
3255 *
3256 * @returns 16-bit signed number on success.
3257 * @returns 0 on failure.
3258 * @param pszValue Pointer to the string value.
3259 */
3260RTDECL(int16_t) RTStrToInt16(const char *pszValue);
3261
3262/**
3263 * Converts a string representation of a number to a 8-bit signed number.
3264 *
3265 * @returns iprt status code.
3266 * Warnings are used to indicate conversion problems.
3267 * @retval VWRN_NUMBER_TOO_BIG
3268 * @retval VWRN_TRAILING_CHARS
3269 * @retval VWRN_TRAILING_SPACES
3270 * @retval VINF_SUCCESS
3271 * @retval VERR_NO_DIGITS
3272 *
3273 * @param pszValue Pointer to the string value.
3274 * @param ppszNext Where to store the pointer to the first char
3275 * following the number. (Optional)
3276 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3277 * upper 24 bits are the max length to parse. If the base
3278 * is zero the function will look for known prefixes before
3279 * defaulting to 10. A max length of zero means no length
3280 * restriction.
3281 * @param pi8 Where to store the converted number. (optional)
3282 */
3283RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int8_t *pi8);
3284
3285/**
3286 * Converts a string representation of a number to a 8-bit signed number,
3287 * making sure the full string is converted.
3288 *
3289 * @returns iprt status code.
3290 * Warnings are used to indicate conversion problems.
3291 * @retval VWRN_NUMBER_TOO_BIG
3292 * @retval VINF_SUCCESS
3293 * @retval VERR_TRAILING_CHARS
3294 * @retval VERR_TRAILING_SPACES
3295 * @retval VERR_NO_DIGITS
3296 *
3297 * @param pszValue Pointer to the string value.
3298 * @param uBaseAndMaxLen The low byte is the base of the representation, the
3299 * upper 24 bits are the max length to parse. If the base
3300 * is zero the function will look for known prefixes before
3301 * defaulting to 10. A max length of zero means no length
3302 * restriction.
3303 * @param pi8 Where to store the converted number. (optional)
3304 */
3305RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, int8_t *pi8);
3306
3307/**
3308 * Converts a string representation of a number to a 8-bit signed number.
3309 * The base is guessed.
3310 *
3311 * @returns 8-bit signed number on success.
3312 * @returns 0 on failure.
3313 * @param pszValue Pointer to the string value.
3314 */
3315RTDECL(int8_t) RTStrToInt8(const char *pszValue);
3316
3317
3318/**
3319 * Converts a string to long double floating point, extended edition.
3320 *
3321 * Please note that long double can be double precision, extended precision, or
3322 * quad precision floating point depending on the platform and architecture. See
3323 * RT_COMPILER_WITH_128BIT_LONG_DOUBLE and RT_COMPILER_WITH_80BIT_LONG_DOUBLE.
3324 *
3325 * @returns IPRT status code.
3326 * @retval VERR_NO_DIGITS if no valid digits found.
3327 * @retval VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
3328 * value
3329 * @retval VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
3330 * @retval VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
3331 * @retval VWRN_TRAILING_CHARS
3332 * @retval VWRN_TRAILING_SPACES
3333 *
3334 * @param pszValue The string to parse.
3335 * @param ppszNext Where to store the pointer to the first char following
3336 * the number. Optional.
3337 * @param cchMax Max number of character to parse. Zero means unlimited.
3338 * @param plrd Where to return the number. Optional.
3339 *
3340 * @note This code isn't entirely perfect yet. It could exhibit rounding
3341 * differences compared to strtold & the compiler, and extreme value
3342 * may overflow/underflow prematurely depending on the build config.
3343 */
3344RTDECL(int) RTStrToLongDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, long double *plrd);
3345
3346/**
3347 * Converts a string to double precision floating point, extended edition.
3348 *
3349 * @returns IPRT status code.
3350 * @retval VERR_NO_DIGITS if no valid digits found.
3351 * @retval VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
3352 * value
3353 * @retval VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
3354 * @retval VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
3355 * @retval VWRN_TRAILING_CHARS
3356 * @retval VWRN_TRAILING_SPACES
3357 *
3358 * @param pszValue The string to parse.
3359 * @param ppszNext Where to store the pointer to the first char following
3360 * the number. Optional.
3361 * @param cchMax Max number of character to parse. Zero means unlimited.
3362 * @param prd Where to return the number. Optional.
3363 *
3364 * @note This code isn't entirely perfect yet. It could exhibit rounding
3365 * differences compared to strtold & the compiler, and extreme value
3366 * may overflow/underflow prematurely depending on the build config.
3367 */
3368RTDECL(int) RTStrToDoubleEx(const char *pszValue, char **ppszNext, size_t cchMax, double *prd);
3369
3370/**
3371 * Converts a string to single precision floating point, extended edition.
3372 *
3373 * @returns IPRT status code.
3374 * @retval VERR_NO_DIGITS if no valid digits found.
3375 * @retval VWRN_FLOAT_UNDERFLOW on underflow with denormal/subnormal return
3376 * value
3377 * @retval VERR_FLOAT_UNDERFLOW on underflow, value set to +/- zero.
3378 * @retval VERR_FLOAT_OVERFLOW on overflow, value set to +/- infinity.
3379 * @retval VWRN_TRAILING_CHARS
3380 * @retval VWRN_TRAILING_SPACES
3381 *
3382 * @param pszValue The string to parse.
3383 * @param ppszNext Where to store the pointer to the first char following
3384 * the number. Optional.
3385 * @param cchMax Max number of character to parse. Zero means unlimited.
3386 * @param pr Where to return the number. Optional.
3387 *
3388 * @note This code isn't entirely perfect yet. It could exhibit rounding
3389 * differences compared to strtold & the compiler, and extreme value
3390 * may overflow/underflow prematurely depending on the build config.
3391 */
3392RTDECL(int) RTStrToFloatEx(const char *pszValue, char **ppszNext, size_t cchMax, float *pr);
3393
3394
3395/**
3396 * Gets a long double NaN.
3397 *
3398 * @returns NaN value.
3399 * @param pszTag Optional NaN tag for modifying the NaN value. We
3400 * recognizes a string of hex digits for inserting into the
3401 * fraction part. This may be followed 'quiet' or
3402 * 'signaling', ignoring case and requiring at only the
3403 * first character. The two components may be separated by
3404 * zero or more '_' characters. Any other stuff in the tag
3405 * will be ignored.
3406 *
3407 * If the tag is empty or we cannot grok any of it, we'll
3408 * return a default quiet NaN.
3409 * @param fPositive Whether the NaN value should be positive or negative
3410 * (for what that's worth).
3411 */
3412RTDECL(long double) RTStrNanLongDouble(const char *pszTag, bool fPositive);
3413
3414/**
3415 * Gets a double NaN.
3416 *
3417 * @returns NaN value.
3418 * @param pszTag Optional NaN tag for modifying the NaN value. We
3419 * recognizes a string of hex digits for inserting into the
3420 * fraction part. This may be followed 'quiet' or
3421 * 'signaling', ignoring case and requiring at only the
3422 * first character. The two components may be separated by
3423 * zero or more '_' characters. Any other stuff in the tag
3424 * will be ignored.
3425 *
3426 * If the tag is empty or we cannot grok any of it, we'll
3427 * return a default quiet NaN.
3428 * @param fPositive Whether the NaN value should be positive or negative
3429 * (for what that's worth).
3430 */
3431RTDECL(double) RTStrNanDouble(const char *pszTag, bool fPositive);
3432
3433/**
3434 * Gets a float NaN.
3435 *
3436 * @returns NaN value.
3437 * @param pszTag Optional NaN tag for modifying the NaN value. We
3438 * recognizes a string of hex digits for inserting into the
3439 * fraction part. This may be followed 'quiet' or
3440 * 'signaling', ignoring case and requiring at only the
3441 * first character. The two components may be separated by
3442 * zero or more '_' characters. Any other stuff in the tag
3443 * will be ignored.
3444 *
3445 * If the tag is empty or we cannot grok any of it, we'll
3446 * return a default quiet NaN.
3447 * @param fPositive Whether the NaN value should be positive or negative
3448 * (for what that's worth).
3449 */
3450RTDECL(float) RTStrNanFloat(const char *pszTag, bool fPositive);
3451
3452/**
3453 * Formats a buffer stream as hex bytes.
3454 *
3455 * The default is no separating spaces or line breaks or anything.
3456 *
3457 * @returns IPRT status code.
3458 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
3459 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
3460 *
3461 * @param pszBuf Output string buffer.
3462 * @param cbBuf The size of the output buffer.
3463 * @param pv Pointer to the bytes to stringify.
3464 * @param cb The number of bytes to stringify.
3465 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
3466 * @sa RTUtf16PrintHexBytes.
3467 */
3468RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cbBuf, void const *pv, size_t cb, uint32_t fFlags);
3469/** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
3470 * @{ */
3471/** Upper case hex digits, the default is lower case. */
3472#define RTSTRPRINTHEXBYTES_F_UPPER RT_BIT(0)
3473/** Add a space between each group. */
3474#define RTSTRPRINTHEXBYTES_F_SEP_SPACE RT_BIT(1)
3475/** Add a colon between each group. */
3476#define RTSTRPRINTHEXBYTES_F_SEP_COLON RT_BIT(2)
3477/** @} */
3478
3479/**
3480 * Converts a string of hex bytes back into binary data.
3481 *
3482 * @returns IPRT status code.
3483 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
3484 * @retval VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
3485 * @retval VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
3486 * the output buffer.
3487 * @retval VERR_UNEVEN_INPUT if the input contains a half byte.
3488 * @retval VERR_NO_DIGITS
3489 * @retval VWRN_TRAILING_CHARS
3490 * @retval VWRN_TRAILING_SPACES
3491 *
3492 * @param pszHex The string containing the hex bytes.
3493 * @param pv Output buffer.
3494 * @param cb The size of the output buffer.
3495 * @param fFlags RTSTRCONVERTHEXBYTES_F_XXX.
3496 */
3497RTDECL(int) RTStrConvertHexBytes(char const *pszHex, void *pv, size_t cb, uint32_t fFlags);
3498
3499/** @name RTSTRCONVERTHEXBYTES_F_XXX - Flags for RTStrConvertHexBytes() and RTStrConvertHexBytesEx().
3500 * @{ */
3501/** Accept colon as a byte separator. */
3502#define RTSTRCONVERTHEXBYTES_F_SEP_COLON RT_BIT(0)
3503/** @} */
3504
3505/**
3506 * Converts a string of hex bytes back into binary data, extended version.
3507 *
3508 * @returns IPRT status code.
3509 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
3510 * @retval VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
3511 * @retval VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
3512 * the output buffer and *pcbReturned is NULL.
3513 * @retval VINF_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
3514 * the output buffer and *pcbReturned is not NULL, *pcbReturned holds
3515 * the actual number of bytes.
3516 * @retval VERR_UNEVEN_INPUT if the input contains a half byte.
3517 * @retval VERR_NO_DIGITS
3518 * @retval VWRN_TRAILING_CHARS
3519 * @retval VWRN_TRAILING_SPACES
3520 *
3521 * @param pszHex The string containing the hex bytes.
3522 * @param pv Output buffer.
3523 * @param cb The size of the output buffer.
3524 * @param fFlags RTSTRCONVERTHEXBYTES_F_XXX.
3525 * @param ppszNext Set to point at where we stopped decoding hex bytes.
3526 * Optional.
3527 * @param pcbReturned Where to return the number of bytes found. Optional.
3528 */
3529RTDECL(int) RTStrConvertHexBytesEx(char const *pszHex, void *pv, size_t cb, uint32_t fFlags,
3530 const char **ppszNext, size_t *pcbReturned);
3531
3532/** @} */
3533
3534
3535/** @defgroup rt_str_space Unique String Space
3536 * @{
3537 */
3538
3539/** Pointer to a string name space container node core. */
3540typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
3541/** Pointer to a pointer to a string name space container node core. */
3542typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
3543
3544/**
3545 * String name space container node core.
3546 */
3547typedef struct RTSTRSPACECORE
3548{
3549 /** Pointer to the left leaf node. Don't touch. */
3550 PRTSTRSPACECORE pLeft;
3551 /** Pointer to the left right node. Don't touch. */
3552 PRTSTRSPACECORE pRight;
3553 /** Pointer to the list of string with the same hash key value. Don't touch. */
3554 PRTSTRSPACECORE pList;
3555 /** Hash key. Don't touch. */
3556 uint32_t Key;
3557 /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
3558 unsigned char uchHeight;
3559 /** The string length. Read only! */
3560 size_t cchString;
3561 /** Pointer to the string. Read only! */
3562 const char *pszString;
3563} RTSTRSPACECORE;
3564
3565/** String space. (Initialize with NULL.) */
3566typedef PRTSTRSPACECORE RTSTRSPACE;
3567/** Pointer to a string space. */
3568typedef PPRTSTRSPACECORE PRTSTRSPACE;
3569
3570
3571/**
3572 * Inserts a string into a unique string space.
3573 *
3574 * @returns true on success.
3575 * @returns false if the string collided with an existing string.
3576 * @param pStrSpace The space to insert it into.
3577 * @param pStr The string node.
3578 */
3579RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
3580
3581/**
3582 * Removes a string from a unique string space.
3583 *
3584 * @returns Pointer to the removed string node.
3585 * @returns NULL if the string was not found in the string space.
3586 * @param pStrSpace The space to remove it from.
3587 * @param pszString The string to remove.
3588 */
3589RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
3590
3591/**
3592 * Gets a string from a unique string space.
3593 *
3594 * @returns Pointer to the string node.
3595 * @returns NULL if the string was not found in the string space.
3596 * @param pStrSpace The space to get it from.
3597 * @param pszString The string to get.
3598 */
3599RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
3600
3601/**
3602 * Gets a string from a unique string space.
3603 *
3604 * @returns Pointer to the string node.
3605 * @returns NULL if the string was not found in the string space.
3606 * @param pStrSpace The space to get it from.
3607 * @param pszString The string to get.
3608 * @param cchMax The max string length to evaluate. Passing
3609 * RTSTR_MAX is ok and makes it behave just like
3610 * RTStrSpaceGet.
3611 */
3612RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax);
3613
3614/**
3615 * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
3616 *
3617 * @returns 0 on continue.
3618 * @returns Non-zero to aborts the operation.
3619 * @param pStr The string node
3620 * @param pvUser The user specified argument.
3621 */
3622typedef DECLCALLBACKTYPE(int, FNRTSTRSPACECALLBACK,(PRTSTRSPACECORE pStr, void *pvUser));
3623/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
3624typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
3625
3626/**
3627 * Destroys the string space.
3628 *
3629 * The caller supplies a callback which will be called for each of the string
3630 * nodes in for freeing their memory and other resources.
3631 *
3632 * @returns 0 or what ever non-zero return value pfnCallback returned
3633 * when aborting the destruction.
3634 * @param pStrSpace The space to destroy.
3635 * @param pfnCallback The callback.
3636 * @param pvUser The user argument.
3637 */
3638RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
3639
3640/**
3641 * Enumerates the string space.
3642 * The caller supplies a callback which will be called for each of
3643 * the string nodes.
3644 *
3645 * @returns 0 or what ever non-zero return value pfnCallback returned
3646 * when aborting the destruction.
3647 * @param pStrSpace The space to enumerate.
3648 * @param pfnCallback The callback.
3649 * @param pvUser The user argument.
3650 */
3651RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
3652
3653/** @} */
3654
3655
3656/** @defgroup rt_str_hash Sting hashing
3657 * @{ */
3658
3659/**
3660 * Hashes the given string using algorithm \#1.
3661 *
3662 * @returns String hash.
3663 * @param pszString The string to hash.
3664 */
3665RTDECL(uint32_t) RTStrHash1(const char *pszString);
3666
3667/**
3668 * Hashes the given string using algorithm \#1.
3669 *
3670 * @returns String hash.
3671 * @param pszString The string to hash.
3672 * @param cchString The max length to hash. Hashing will stop if the
3673 * terminator character is encountered first. Passing
3674 * RTSTR_MAX is fine.
3675 */
3676RTDECL(uint32_t) RTStrHash1N(const char *pszString, size_t cchString);
3677
3678/**
3679 * Hashes the given strings as if they were concatenated using algorithm \#1.
3680 *
3681 * @returns String hash.
3682 * @param cPairs The number of string / length pairs in the
3683 * ellipsis.
3684 * @param ... List of string (const char *) and length
3685 * (size_t) pairs. Passing RTSTR_MAX as the size is
3686 * fine.
3687 */
3688RTDECL(uint32_t) RTStrHash1ExN(size_t cPairs, ...);
3689
3690/**
3691 * Hashes the given strings as if they were concatenated using algorithm \#1.
3692 *
3693 * @returns String hash.
3694 * @param cPairs The number of string / length pairs in the @a va.
3695 * @param va List of string (const char *) and length
3696 * (size_t) pairs. Passing RTSTR_MAX as the size is
3697 * fine.
3698 */
3699RTDECL(uint32_t) RTStrHash1ExNV(size_t cPairs, va_list va);
3700
3701/** @} */
3702
3703
3704/** @defgroup rt_str_mem Raw memory operations.
3705 *
3706 * @note Following the memchr/memcpy/memcmp/memset tradition and putting these
3707 * in the string.h header rather than in the mem.h one.
3708 *
3709 * @{ */
3710
3711/**
3712 * Searches @a pvHaystack for a 16-bit sized and aligned @a uNeedle.
3713 *
3714 * @returns Pointer to the first hit if found, NULL if not found.
3715 * @param pvHaystack The memory to search.
3716 * @param uNeedle The 16-bit value to find.
3717 * @param cbHaystack Size of the memory to search.
3718 * @sa memchr, RTStrMemFind32, RTStrMemFind64
3719 */
3720RTDECL(uint16_t *) RTStrMemFind16(const void *pvHaystack, uint16_t uNeedle, size_t cbHaystack);
3721
3722/**
3723 * Searches @a pvHaystack for a 32-bit sized and aligned @a uNeedle.
3724 *
3725 * @returns Pointer to the first hit if found, NULL if not found.
3726 * @param pvHaystack The memory to search.
3727 * @param uNeedle The 32-bit value to find.
3728 * @param cbHaystack Size of the memory to search.
3729 * @sa memchr, RTStrMemFind16, RTStrMemFind64
3730 */
3731RTDECL(uint32_t *) RTStrMemFind32(const void *pvHaystack, uint32_t uNeedle, size_t cbHaystack);
3732
3733/**
3734 * Searches @a pvHaystack for a 64-bit sized and aligned @a uNeedle.
3735 *
3736 * @returns Pointer to the first hit if found, NULL if not found.
3737 * @param pvHaystack The memory to search.
3738 * @param uNeedle The 64-bit value to find.
3739 * @param cbHaystack Size of the memory to search.
3740 * @sa memchr, RTStrMemFind16, RTStrMemFind32
3741 */
3742RTDECL(uint64_t *) RTStrMemFind64(const void *pvHaystack, uint64_t uNeedle, size_t cbHaystack);
3743
3744/** @} */
3745
3746
3747/** @} */
3748
3749RT_C_DECLS_END
3750
3751#endif /* !IPRT_INCLUDED_string_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette