VirtualBox

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

Last change on this file since 88128 was 88128, checked in by vboxsync, 4 years ago

include/iprt/string.h, src/VBox/Devices/Network/slirp/slirp_config.h: Adjustments for building on Solaris 11.4.

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

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