VirtualBox

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

Last change on this file since 73886 was 73801, checked in by vboxsync, 6 years ago

IPRT/strformatter: Added %RJs for formatting JSON quoted strings. bugref:9167

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