string.h@ 58803

Last change on this file since 58803 was 57941, checked in by vboxsync, 9 years ago
iprt/string.h: split out the UTF-16 and Latin-1 parts.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 121.2 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: