VirtualBox

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

Last change on this file since 18544 was 18544, checked in by vboxsync, 16 years ago

RTStrToUpper/Lower: Document assumtions & todos properly, added missing spaces.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 68.1 KB
Line 
1/** @file
2 * IPRT - String Manipluation.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_string_h
31#define ___iprt_string_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35#include <iprt/stdarg.h>
36#include <iprt/err.h> /* for VINF_SUCCESS */
37#if defined(RT_OS_LINUX) && defined(__KERNEL__)
38# include <linux/string.h>
39#elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
40 /*
41 * Kludge for the FreeBSD kernel:
42 * Some of the string.h stuff clashes with sys/libkern.h, so just wrap
43 * it up while including string.h to keep things quiet. It's nothing
44 * important that's clashing, after all.
45 */
46# define strdup strdup_string_h
47# include <string.h>
48# undef strdup
49#elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
50 /*
51 * Same case as with FreeBSD kernel:
52 * The string.h stuff clashes with sys/system.h
53 * ffs = find first set bit.
54 */
55# define ffs ffs_string_h
56# include <string.h>
57# undef ffs
58# undef strpbrk
59#else
60# include <string.h>
61#endif
62
63/*
64 * Supply prototypes for standard string functions provided by
65 * IPRT instead of the operating environment.
66 */
67#if defined(RT_OS_DARWIN) && defined(KERNEL)
68__BEGIN_DECLS
69void *memchr(const void *pv, int ch, size_t cb);
70char *strpbrk(const char *pszStr, const char *pszChars);
71__END_DECLS
72#endif
73
74/**
75 * Byte zero the specified object.
76 *
77 * This will use sizeof(Obj) to figure the size and will call memset, bzero
78 * or some compiler intrinsic to perform the actual zeroing.
79 *
80 * @param Obj The object to zero. Make sure to dereference pointers.
81 *
82 * @remarks Because the macro may use memset it has been placed in string.h
83 * instead of cdefs.h to avoid build issues because someone forgot
84 * to include this header.
85 *
86 * @ingroup grp_rt_cdefs
87 */
88#define RT_ZERO(Obj) RT_BZERO(&(Obj), sizeof(Obj))
89
90/**
91 * Byte zero the specified memory area.
92 *
93 * This will call memset, bzero or some compiler intrinsic to clear the
94 * specified bytes of memory.
95 *
96 * @param pv Pointer to the memory.
97 * @param cb The number of bytes to clear. Please, don't pass 0.
98 *
99 * @remarks Because the macro may use memset it has been placed in string.h
100 * instead of cdefs.h to avoid build issues because someone forgot
101 * to include this header.
102 *
103 * @ingroup grp_rt_cdefs
104 */
105#define RT_BZERO(pv, cb) do { memset((pv), 0, cb); } while (0)
106
107
108/** @defgroup grp_rt_str RTStr - String Manipulation
109 * Mostly UTF-8 related helpers where the standard string functions won't do.
110 * @ingroup grp_rt
111 * @{
112 */
113
114__BEGIN_DECLS
115
116
117/**
118 * The maximum string length.
119 */
120#define RTSTR_MAX (~(size_t)0)
121
122
123#ifdef IN_RING3
124
125/**
126 * Allocates tmp buffer, translates pszString from UTF8 to current codepage.
127 *
128 * @returns iprt status code.
129 * @param ppszString Receives pointer of allocated native CP string.
130 * The returned pointer must be freed using RTStrFree().
131 * @param pszString UTF-8 string to convert.
132 */
133RTR3DECL(int) RTStrUtf8ToCurrentCP(char **ppszString, const char *pszString);
134
135/**
136 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
137 *
138 * @returns iprt status code.
139 * @param ppszString Receives pointer of allocated UTF-8 string.
140 * The returned pointer must be freed using RTStrFree().
141 * @param pszString Native string to convert.
142 */
143RTR3DECL(int) RTStrCurrentCPToUtf8(char **ppszString, const char *pszString);
144
145#endif
146
147/**
148 * Free string allocated by any of the non-UCS-2 string functions.
149 *
150 * @returns iprt status code.
151 * @param pszString Pointer to buffer with string to free.
152 * NULL is accepted.
153 */
154RTDECL(void) RTStrFree(char *pszString);
155
156/**
157 * Allocates a new copy of the given UTF-8 string.
158 *
159 * @returns Pointer to the allocated UTF-8 string.
160 * @param pszString UTF-8 string to duplicate.
161 */
162RTDECL(char *) RTStrDup(const char *pszString);
163
164/**
165 * Allocates a new copy of the given UTF-8 string.
166 *
167 * @returns iprt status code.
168 * @param ppszString Receives pointer of the allocated UTF-8 string.
169 * The returned pointer must be freed using RTStrFree().
170 * @param pszString UTF-8 string to duplicate.
171 */
172RTDECL(int) RTStrDupEx(char **ppszString, const char *pszString);
173
174/**
175 * Validates the UTF-8 encoding of the string.
176 *
177 * @returns iprt status code.
178 * @param psz The string.
179 */
180RTDECL(int) RTStrValidateEncoding(const char *psz);
181
182/** @name Flags for RTStrValidateEncodingEx
183 */
184/** Check that the string is zero terminated within the given size.
185 * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
186#define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED RT_BIT_32(0)
187/** @} */
188
189/**
190 * Validates the UTF-8 encoding of the string.
191 *
192 * @returns iprt status code.
193 * @param psz The string.
194 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
195 * @param fFlags Reserved for future. Pass 0.
196 */
197RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
198
199/**
200 * Checks if the UTF-8 encoding is valid.
201 *
202 * @returns true / false.
203 * @param psz The string.
204 */
205RTDECL(bool) RTStrIsValidEncoding(const char *psz);
206
207/**
208 * Gets the number of code points the string is made up of, excluding
209 * the terminator.
210 *
211 *
212 * @returns Number of code points (RTUNICP).
213 * @returns 0 if the string was incorrectly encoded.
214 * @param psz The string.
215 */
216RTDECL(size_t) RTStrUniLen(const char *psz);
217
218/**
219 * Gets the number of code points the string is made up of, excluding
220 * the terminator.
221 *
222 * This function will validate the string, and incorrectly encoded UTF-8
223 * strings will be rejected.
224 *
225 * @returns iprt status code.
226 * @param psz The string.
227 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
228 * @param pcuc Where to store the code point count.
229 * This is undefined on failure.
230 */
231RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
232
233/**
234 * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
235 *
236 * @returns iprt status code.
237 * @param pszString UTF-8 string to convert.
238 * @param ppUniString Receives pointer to the allocated unicode string.
239 * The returned string must be freed using RTUniFree().
240 */
241RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
242
243/**
244 * Translates pszString from UTF-8 to an array of code points, allocating the result
245 * array if requested.
246 *
247 * @returns iprt status code.
248 * @param pszString UTF-8 string to convert.
249 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
250 * when it reaches cchString or the string terminator ('\\0').
251 * Use RTSTR_MAX to translate the entire string.
252 * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
253 * a buffer of the specified size, or pointer to a NULL pointer.
254 * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
255 * will be allocated to hold the translated string.
256 * If a buffer was requested it must be freed using RTUtf16Free().
257 * @param cCps The number of code points in the unicode string. This includes the terminator.
258 * @param pcCps Where to store the length of the translated string. (Optional)
259 * This field will be updated even on failure, however the value is only
260 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
261 * and VERR_NO_STR_MEMORY it contains the required buffer space.
262 */
263RTDECL(int) RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
264
265/**
266 * Calculates the length of the string in RTUTF16 items.
267 *
268 * This function will validate the string, and incorrectly encoded UTF-8
269 * strings will be rejected. The primary purpose of this function is to
270 * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
271 * other purposes RTStrCalcUtf16LenEx() should be used.
272 *
273 * @returns Number of RTUTF16 items.
274 * @returns 0 if the string was incorrectly encoded.
275 * @param psz The string.
276 */
277RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
278
279/**
280 * Calculates the length of the string in RTUTF16 items.
281 *
282 * This function will validate the string, and incorrectly encoded UTF-8
283 * strings will be rejected.
284 *
285 * @returns iprt status code.
286 * @param psz The string.
287 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
288 * @param pcwc Where to store the string length. Optional.
289 * This is undefined on failure.
290 */
291RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
292
293/**
294 * Translate a UTF-8 string into a UTF-16 allocating the result buffer.
295 *
296 * @returns iprt status code.
297 * @param pszString UTF-8 string to convert.
298 * @param ppwszString Receives pointer to the allocated UTF-16 string.
299 * The returned string must be freed using RTUtf16Free().
300 */
301RTDECL(int) RTStrToUtf16(const char *pszString, PRTUTF16 *ppwszString);
302
303/**
304 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
305 *
306 * @returns iprt status code.
307 * @param pszString UTF-8 string to convert.
308 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
309 * when it reaches cchString or the string terminator ('\\0').
310 * Use RTSTR_MAX to translate the entire string.
311 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
312 * a buffer of the specified size, or pointer to a NULL pointer.
313 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
314 * will be allocated to hold the translated string.
315 * If a buffer was requested it must be freed using RTUtf16Free().
316 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
317 * @param pcwc Where to store the length of the translated string. (Optional)
318 * This field will be updated even on failure, however the value is only
319 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
320 * and VERR_NO_STR_MEMORY it contains the required buffer space.
321 */
322RTDECL(int) RTStrToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
323
324
325/**
326 * Get the unicode code point at the given string position.
327 *
328 * @returns unicode code point.
329 * @returns RTUNICP_INVALID if the encoding is invalid.
330 * @param psz The string.
331 */
332RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
333
334/**
335 * Get the unicode code point at the given string position.
336 *
337 * @returns iprt status code
338 * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
339 * @param ppsz The string.
340 * @param pCp Where to store the unicode code point.
341 * Stores RTUNICP_INVALID if the encoding is invalid.
342 */
343RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
344
345/**
346 * Get the unicode code point at the given string position for a string of a
347 * given length.
348 *
349 * @returns iprt status code
350 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
351 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
352 *
353 * @param ppsz The string.
354 * @param pcch Pointer to the length of the string. This will be
355 * decremented by the size of the code point.
356 * @param pCp Where to store the unicode code point.
357 * Stores RTUNICP_INVALID if the encoding is invalid.
358 */
359RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
360
361/**
362 * Put the unicode code point at the given string position
363 * and return the pointer to the char following it.
364 *
365 * This function will not consider anything at or following the
366 * buffer area pointed to by psz. It is therefore not suitable for
367 * inserting code points into a string, only appending/overwriting.
368 *
369 * @returns pointer to the char following the written code point.
370 * @param psz The string.
371 * @param CodePoint The code point to write.
372 * This should not be RTUNICP_INVALID or any other
373 * character out of the UTF-8 range.
374 *
375 * @remark This is a worker function for RTStrPutCp().
376 *
377 */
378RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
379
380/**
381 * Get the unicode code point at the given string position.
382 *
383 * @returns unicode code point.
384 * @returns RTUNICP_INVALID if the encoding is invalid.
385 * @param psz The string.
386 *
387 * @remark We optimize this operation by using an inline function for
388 * the most frequent and simplest sequence, the rest is
389 * handled by RTStrGetCpInternal().
390 */
391DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
392{
393 const unsigned char uch = *(const unsigned char *)psz;
394 if (!(uch & RT_BIT(7)))
395 return uch;
396 return RTStrGetCpInternal(psz);
397}
398
399/**
400 * Get the unicode code point at the given string position.
401 *
402 * @returns iprt status code.
403 * @param ppsz Pointer to the string pointer. This will be updated to
404 * point to the char following the current code point.
405 * @param pCp Where to store the code point.
406 * RTUNICP_INVALID is stored here on failure.
407 *
408 * @remark We optimize this operation by using an inline function for
409 * the most frequent and simplest sequence, the rest is
410 * handled by RTStrGetCpExInternal().
411 */
412DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
413{
414 const unsigned char uch = **(const unsigned char **)ppsz;
415 if (!(uch & RT_BIT(7)))
416 {
417 (*ppsz)++;
418 *pCp = uch;
419 return VINF_SUCCESS;
420 }
421 return RTStrGetCpExInternal(ppsz, pCp);
422}
423
424/**
425 * Get the unicode code point at the given string position for a string of a
426 * given maximum length.
427 *
428 * @returns iprt status code.
429 * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
430 * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
431 *
432 * @param ppsz Pointer to the string pointer. This will be updated to
433 * point to the char following the current code point.
434 * @param pcch Pointer to the maximum string length. This will be
435 * decremented by the size of the code point found.
436 * @param pCp Where to store the code point.
437 * RTUNICP_INVALID is stored here on failure.
438 *
439 * @remark We optimize this operation by using an inline function for
440 * the most frequent and simplest sequence, the rest is
441 * handled by RTStrGetCpNExInternal().
442 */
443DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
444{
445 if (RT_LIKELY(*pcch != 0))
446 {
447 const unsigned char uch = **(const unsigned char **)ppsz;
448 if (!(uch & RT_BIT(7)))
449 {
450 (*ppsz)++;
451 (*pcch)--;
452 *pCp = uch;
453 return VINF_SUCCESS;
454 }
455 }
456 return RTStrGetCpNExInternal(ppsz, pcch, pCp);
457}
458
459/**
460 * Put the unicode code point at the given string position
461 * and return the pointer to the char following it.
462 *
463 * This function will not consider anything at or following the
464 * buffer area pointed to by psz. It is therefore not suitable for
465 * inserting code points into a string, only appending/overwriting.
466 *
467 * @returns pointer to the char following the written code point.
468 * @param psz The string.
469 * @param CodePoint The code point to write.
470 * This should not be RTUNICP_INVALID or any other
471 * character out of the UTF-8 range.
472 *
473 * @remark We optimize this operation by using an inline function for
474 * the most frequent and simplest sequence, the rest is
475 * handled by RTStrPutCpInternal().
476 */
477DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
478{
479 if (CodePoint < 0x80)
480 {
481 *psz++ = (unsigned char)CodePoint;
482 return psz;
483 }
484 return RTStrPutCpInternal(psz, CodePoint);
485}
486
487/**
488 * Skips ahead, past the current code point.
489 *
490 * @returns Pointer to the char after the current code point.
491 * @param psz Pointer to the current code point.
492 * @remark This will not move the next valid code point, only past the current one.
493 */
494DECLINLINE(char *) RTStrNextCp(const char *psz)
495{
496 RTUNICP Cp;
497 RTStrGetCpEx(&psz, &Cp);
498 return (char *)psz;
499}
500
501/**
502 * Skips back to the previous code point.
503 *
504 * @returns Pointer to the char before the current code point.
505 * @returns pszStart on failure.
506 * @param pszStart Pointer to the start of the string.
507 * @param psz Pointer to the current code point.
508 */
509RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
510
511
512
513#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
514#define DECLARED_FNRTSTROUTPUT
515/**
516 * Output callback.
517 *
518 * @returns number of bytes written.
519 * @param pvArg User argument.
520 * @param pachChars Pointer to an array of utf-8 characters.
521 * @param cbChars Number of bytes in the character array pointed to by pachChars.
522 */
523typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
524/** Pointer to callback function. */
525typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
526#endif
527
528/** Format flag.
529 * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
530 * that not all flags makes sense to both of the functions.
531 * @{ */
532#define RTSTR_F_CAPITAL 0x0001
533#define RTSTR_F_LEFT 0x0002
534#define RTSTR_F_ZEROPAD 0x0004
535#define RTSTR_F_SPECIAL 0x0008
536#define RTSTR_F_VALSIGNED 0x0010
537#define RTSTR_F_PLUS 0x0020
538#define RTSTR_F_BLANK 0x0040
539#define RTSTR_F_WIDTH 0x0080
540#define RTSTR_F_PRECISION 0x0100
541
542#define RTSTR_F_BIT_MASK 0xf800
543#define RTSTR_F_8BIT 0x0800
544#define RTSTR_F_16BIT 0x1000
545#define RTSTR_F_32BIT 0x2000
546#define RTSTR_F_64BIT 0x4000
547#define RTSTR_F_128BIT 0x8000
548/** @} */
549
550/** @def RTSTR_GET_BIT_FLAG
551 * Gets the bit flag for the specified type.
552 */
553#define RTSTR_GET_BIT_FLAG(type) \
554 ( sizeof(type) == 32 ? RTSTR_F_32BIT \
555 : sizeof(type) == 64 ? RTSTR_F_64BIT \
556 : sizeof(type) == 16 ? RTSTR_F_16BIT \
557 : sizeof(type) == 8 ? RTSTR_F_8BIT \
558 : sizeof(type) == 128? RTSTR_F_128BIT \
559 : 0)
560
561
562/**
563 * Callback to format non-standard format specifiers.
564 *
565 * @returns The number of bytes formatted.
566 * @param pvArg Formatter argument.
567 * @param pfnOutput Pointer to output function.
568 * @param pvArgOutput Argument for the output function.
569 * @param ppszFormat Pointer to the format string pointer. Advance this till the char
570 * after the format specifier.
571 * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
572 * @param cchWidth Format Width. -1 if not specified.
573 * @param cchPrecision Format Precision. -1 if not specified.
574 * @param fFlags Flags (RTSTR_NTFS_*).
575 * @param chArgSize The argument size specifier, 'l' or 'L'.
576 */
577typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
578 const char **ppszFormat, va_list *pArgs, int cchWidth,
579 int cchPrecision, unsigned fFlags, char chArgSize);
580/** Pointer to a FNSTRFORMAT() function. */
581typedef FNSTRFORMAT *PFNSTRFORMAT;
582
583
584/**
585 * Partial implementation of a printf like formatter.
586 * It doesn't do everything correct, and there is no floating point support.
587 * However, it supports custom formats by the means of a format callback.
588 *
589 * @returns number of bytes formatted.
590 * @param pfnOutput Output worker.
591 * Called in two ways. Normally with a string and its length.
592 * For termination, it's called with NULL for string, 0 for length.
593 * @param pvArgOutput Argument to the output worker.
594 * @param pfnFormat Custom format worker.
595 * @param pvArgFormat Argument to the format worker.
596 * @param pszFormat Format string pointer.
597 * @param InArgs Argument list.
598 */
599RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *pszFormat, va_list InArgs);
600
601/**
602 * Partial implementation of a printf like formatter.
603 * It doesn't do everything correct, and there is no floating point support.
604 * However, it supports custom formats by the means of a format callback.
605 *
606 * @returns number of bytes formatted.
607 * @param pfnOutput Output worker.
608 * Called in two ways. Normally with a string and its length.
609 * For termination, it's called with NULL for string, 0 for length.
610 * @param pvArgOutput Argument to the output worker.
611 * @param pfnFormat Custom format worker.
612 * @param pvArgFormat Argument to the format worker.
613 * @param pszFormat Format string.
614 * @param ... Argument list.
615 */
616RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *pszFormat, ...);
617
618/**
619 * Formats an integer number according to the parameters.
620 *
621 * @returns Length of the formatted number.
622 * @param psz Pointer to output string buffer of sufficient size.
623 * @param u64Value Value to format.
624 * @param uiBase Number representation base.
625 * @param cchWidth Width.
626 * @param cchPrecision Precision.
627 * @param fFlags Flags (NTFS_*).
628 */
629RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision, unsigned int fFlags);
630
631
632/**
633 * Callback for formatting a type.
634 *
635 * This is registered using the RTStrFormatTypeRegister function and will
636 * be called during string formatting to handle the specified %R[type].
637 * The argument for this format type is assumed to be a pointer and it's
638 * passed in the @a pvValue argument.
639 *
640 * @returns Length of the formatted output.
641 * @param pfnOutput Output worker.
642 * @param pvArgOutput Argument to the output worker.
643 * @param pszType The type name.
644 * @param pvValue The argument value.
645 * @param cchWidth Width.
646 * @param cchPrecision Precision.
647 * @param fFlags Flags (NTFS_*).
648 * @param pvUser The user argument.
649 */
650typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
651 const char *pszType, void const *pvValue,
652 int cchWidth, int cchPrecision, unsigned fFlags,
653 void *pvUser);
654/** Pointer to a FNRTSTRFORMATTYPE. */
655typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
656
657
658/**
659 * Register a format handler for a type.
660 *
661 * The format handler is used to handle '%R[type]' format types, where the argument
662 * in the vector is a pointer value (a bit restrictive, but keeps it simple).
663 *
664 * The caller must ensure that no other thread will be making use of any of
665 * the dynamic formatting type facilities simultaneously with this call.
666 *
667 * @returns IPRT status code.
668 * @retval VINF_SUCCESS on success.
669 * @retval VERR_ALREADY_EXISTS if the type has already been registered.
670 * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
671 *
672 * @param pszType The type name.
673 * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
674 * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
675 * for how to update this later.
676 */
677RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
678
679/**
680 * Deregisters a format type.
681 *
682 * The caller must ensure that no other thread will be making use of any of
683 * the dynamic formatting type facilities simultaneously with this call.
684 *
685 * @returns IPRT status code.
686 * @retval VINF_SUCCESS on success.
687 * @retval VERR_FILE_NOT_FOUND if not found.
688 *
689 * @param pszType The type to deregister.
690 */
691RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
692
693/**
694 * Sets the user argument for a type.
695 *
696 * This can be used if a user argument needs relocating in GC.
697 *
698 * @returns IPRT status code.
699 * @retval VINF_SUCCESS on success.
700 * @retval VERR_FILE_NOT_FOUND if not found.
701 *
702 * @param pszType The type to update.
703 * @param pvUser The new user argument value.
704 */
705RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
706
707
708/**
709 * String printf.
710 *
711 * @returns The length of the returned string (in pszBuffer).
712 * @param pszBuffer Output buffer.
713 * @param cchBuffer Size of the output buffer.
714 * @param pszFormat The format string.
715 * @param args The format argument.
716 */
717RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
718
719/**
720 * String printf.
721 *
722 * @returns The length of the returned string (in pszBuffer).
723 * @param pszBuffer Output buffer.
724 * @param cchBuffer Size of the output buffer.
725 * @param pszFormat The format string.
726 * @param ... The format argument.
727 */
728RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
729
730
731/**
732 * String printf with custom formatting.
733 *
734 * @returns The length of the returned string (in pszBuffer).
735 * @param pfnFormat Pointer to handler function for the custom formats.
736 * @param pvArg Argument to the pfnFormat function.
737 * @param pszBuffer Output buffer.
738 * @param cchBuffer Size of the output buffer.
739 * @param pszFormat The format string.
740 * @param args The format argument.
741 */
742RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
743
744/**
745 * String printf with custom formatting.
746 *
747 * @returns The length of the returned string (in pszBuffer).
748 * @param pfnFormat Pointer to handler function for the custom formats.
749 * @param pvArg Argument to the pfnFormat function.
750 * @param pszBuffer Output buffer.
751 * @param cchBuffer Size of the output buffer.
752 * @param pszFormat The format string.
753 * @param ... The format argument.
754 */
755RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
756
757
758/**
759 * Allocating string printf.
760 *
761 * @returns The length of the string in the returned *ppszBuffer.
762 * @returns -1 on failure.
763 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
764 * The buffer should be freed using RTStrFree().
765 * On failure *ppszBuffer will be set to NULL.
766 * @param pszFormat The format string.
767 * @param args The format argument.
768 */
769RTDECL(int) RTStrAPrintfV(char **ppszBuffer, const char *pszFormat, va_list args);
770
771/**
772 * Allocating string printf.
773 *
774 * @returns The length of the string in the returned *ppszBuffer.
775 * @returns -1 on failure.
776 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
777 * The buffer should be freed using RTStrFree().
778 * On failure *ppszBuffer will be set to NULL.
779 * @param pszFormat The format string.
780 * @param ... The format argument.
781 */
782RTDECL(int) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...);
783
784
785/**
786 * Strips blankspaces from both ends of the string.
787 *
788 * @returns Pointer to first non-blank char in the string.
789 * @param psz The string to strip.
790 */
791RTDECL(char *) RTStrStrip(char *psz);
792
793/**
794 * Strips blankspaces from the start of the string.
795 *
796 * @returns Pointer to first non-blank char in the string.
797 * @param psz The string to strip.
798 */
799RTDECL(char *) RTStrStripL(const char *psz);
800
801/**
802 * Strips blankspaces from the end of the string.
803 *
804 * @returns psz.
805 * @param psz The string to strip.
806 */
807RTDECL(char *) RTStrStripR(char *psz);
808
809/**
810 * Performs a case sensitive string compare between two UTF-8 strings.
811 *
812 * Encoding errors are ignored by the current implementation. So, the only
813 * difference between this and the CRT strcmp function is the handling of
814 * NULL arguments.
815 *
816 * @returns < 0 if the first string less than the second string.
817 * @returns 0 if the first string identical to the second string.
818 * @returns > 0 if the first string greater than the second string.
819 * @param psz1 First UTF-8 string. Null is allowed.
820 * @param psz2 Second UTF-8 string. Null is allowed.
821 */
822RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
823
824/**
825 * Performs a case sensitive string compare between two UTF-8 strings, given
826 * a maximum string length.
827 *
828 * Encoding errors are ignored by the current implementation. So, the only
829 * difference between this and the CRT strncmp function is the handling of
830 * NULL arguments.
831 *
832 * @returns < 0 if the first string less than the second string.
833 * @returns 0 if the first string identical to the second string.
834 * @returns > 0 if the first string greater than the second string.
835 * @param psz1 First UTF-8 string. Null is allowed.
836 * @param psz2 Second UTF-8 string. Null is allowed.
837 * @param cchMax The maximum string length
838 */
839RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
840
841/**
842 * Performs a case insensitive string compare between two UTF-8 strings.
843 *
844 * This is a simplified compare, as only the simplified lower/upper case folding
845 * specified by the unicode specs are used. It does not consider character pairs
846 * as they are used in some languages, just simple upper & lower case compares.
847 *
848 * The result is the difference between the mismatching codepoints after they
849 * both have been lower cased.
850 *
851 * If the string encoding is invalid the function will assert (strict builds)
852 * and use RTStrCmp for the remainder of the string.
853 *
854 * @returns < 0 if the first string less than the second string.
855 * @returns 0 if the first string identical to the second string.
856 * @returns > 0 if the first string greater than the second string.
857 * @param psz1 First UTF-8 string. Null is allowed.
858 * @param psz2 Second UTF-8 string. Null is allowed.
859 */
860RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
861
862/**
863 * Performs a case insensitive string compare between two UTF-8 strings, given a
864 * maximum string length.
865 *
866 * This is a simplified compare, as only the simplified lower/upper case folding
867 * specified by the unicode specs are used. It does not consider character pairs
868 * as they are used in some languages, just simple upper & lower case compares.
869 *
870 * The result is the difference between the mismatching codepoints after they
871 * both have been lower cased.
872 *
873 * If the string encoding is invalid the function will assert (strict builds)
874 * and use RTStrCmp for the remainder of the string.
875 *
876 * @returns < 0 if the first string less than the second string.
877 * @returns 0 if the first string identical to the second string.
878 * @returns > 0 if the first string greater than the second string.
879 * @param psz1 First UTF-8 string. Null is allowed.
880 * @param psz2 Second UTF-8 string. Null is allowed.
881 * @param cchMax Maximum string length
882 */
883RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
884
885/**
886 * Find the length of a zero-terminated byte string, given
887 * a max string length.
888 *
889 * See also RTStrNLenEx.
890 *
891 * @returns The string length or cbMax. The returned length does not include
892 * the zero terminator if it was found.
893 *
894 * @param pszString The string.
895 * @param cchMax The max string length.
896 */
897RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
898
899/**
900 * Find the length of a zero-terminated byte string, given
901 * a max string length.
902 *
903 * See also RTStrNLen.
904 *
905 * @returns IPRT status code.
906 * @retval VINF_SUCCESS if the string has a length less than cchMax.
907 * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
908 * before cchMax was reached.
909 *
910 * @param pszString The string.
911 * @param cchMax The max string length.
912 * @param pcch Where to store the string length excluding the
913 * terminator. This is set to cchMax if the terminator
914 * isn't found.
915 */
916RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
917
918/**
919 * Matches a simple string pattern.
920 *
921 * @returns true if the string matches the pattern, otherwise false.
922 *
923 * @param pszPattern The pattern. Special chars are '*' and '?', where the
924 * asterisk matches zero or more characters and question
925 * mark matches exactly one character.
926 * @param pszString The string to match against the pattern.
927 */
928RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
929
930/**
931 * Matches a simple string pattern, neither which needs to be zero terminated.
932 *
933 * This is identical to RTStrSimplePatternMatch except that you can optionally
934 * specify the length of both the pattern and the string. The function will
935 * stop when it hits a string terminator or either of the lengths.
936 *
937 * @returns true if the string matches the pattern, otherwise false.
938 *
939 * @param pszPattern The pattern. Special chars are '*' and '?', where the
940 * asterisk matches zero or more characters and question
941 * mark matches exactly one character.
942 * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
943 * length and wish to stop at the string terminator.
944 * @param pszString The string to match against the pattern.
945 * @param cchString The string length. Pass RTSTR_MAX if you don't know the
946 * length and wish to match up to the string terminator.
947 */
948RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
949 const char *pszString, size_t cchString);
950
951/**
952 * Matches multiple patterns against a string.
953 *
954 * The patterns are separated by the pipe character (|).
955 *
956 * @returns true if the string matches the pattern, otherwise false.
957 *
958 * @param pszPatterns The patterns.
959 * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
960 * stop at the terminator.
961 * @param pszString The string to match against the pattern.
962 * @param cchString The string length. Pass RTSTR_MAX stop stop at the
963 * terminator.
964 * @param poffPattern Offset into the patterns string of the patttern that
965 * matched. If no match, this will be set to RTSTR_MAX.
966 * This is optional, NULL is fine.
967 */
968RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
969 const char *pszString, size_t cchString,
970 size_t *poffPattern);
971
972/**
973 * Converts the string to lower case.
974 *
975 * @returns Pointer to the converted string.
976 * @param psz The string to convert.
977 */
978RTDECL(char *) RTStrToLower(char *psz);
979
980/**
981 * Converts the string to upper case.
982 *
983 * @returns Pointer to the converted string.
984 * @param psz The string to convert.
985 */
986RTDECL(char *) RTStrToUpper(char *psz);
987
988
989/** @defgroup rt_str_conv String To/From Number Conversions
990 * @ingroup grp_rt_str
991 * @{ */
992
993/**
994 * Converts a string representation of a number to a 64-bit unsigned number.
995 *
996 * @returns iprt status code.
997 * Warnings are used to indicate conversion problems.
998 * @retval VWRN_NUMBER_TOO_BIG
999 * @retval VWRN_NEGATIVE_UNSIGNED
1000 * @retval VWRN_TRAILING_CHARS
1001 * @retval VWRN_TRAILING_SPACES
1002 * @retval VINF_SUCCESS
1003 * @retval VERR_NO_DIGITS
1004 *
1005 * @param pszValue Pointer to the string value.
1006 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1007 * @param uBase The base of the representation used.
1008 * If 0 the function will look for known prefixes before defaulting to 10.
1009 * @param pu64 Where to store the converted number. (optional)
1010 */
1011RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
1012
1013/**
1014 * Converts a string representation of a number to a 64-bit unsigned number,
1015 * making sure the full string is converted.
1016 *
1017 * @returns iprt status code.
1018 * Warnings are used to indicate conversion problems.
1019 * @retval VWRN_NUMBER_TOO_BIG
1020 * @retval VWRN_NEGATIVE_UNSIGNED
1021 * @retval VINF_SUCCESS
1022 * @retval VERR_NO_DIGITS
1023 * @retval VERR_TRAILING_SPACES
1024 * @retval VERR_TRAILING_CHARS
1025 *
1026 * @param pszValue Pointer to the string value.
1027 * @param uBase The base of the representation used.
1028 * If 0 the function will look for known prefixes before defaulting to 10.
1029 * @param pu64 Where to store the converted number. (optional)
1030 */
1031RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
1032
1033/**
1034 * Converts a string representation of a number to a 64-bit unsigned number.
1035 * The base is guessed.
1036 *
1037 * @returns 64-bit unsigned number on success.
1038 * @returns 0 on failure.
1039 * @param pszValue Pointer to the string value.
1040 */
1041RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
1042
1043/**
1044 * Converts a string representation of a number to a 32-bit unsigned number.
1045 *
1046 * @returns iprt status code.
1047 * Warnings are used to indicate conversion problems.
1048 * @retval VWRN_NUMBER_TOO_BIG
1049 * @retval VWRN_NEGATIVE_UNSIGNED
1050 * @retval VWRN_TRAILING_CHARS
1051 * @retval VWRN_TRAILING_SPACES
1052 * @retval VINF_SUCCESS
1053 * @retval VERR_NO_DIGITS
1054 *
1055 * @param pszValue Pointer to the string value.
1056 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1057 * @param uBase The base of the representation used.
1058 * If 0 the function will look for known prefixes before defaulting to 10.
1059 * @param pu32 Where to store the converted number. (optional)
1060 */
1061RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
1062
1063/**
1064 * Converts a string representation of a number to a 32-bit unsigned number,
1065 * making sure the full string is converted.
1066 *
1067 * @returns iprt status code.
1068 * Warnings are used to indicate conversion problems.
1069 * @retval VWRN_NUMBER_TOO_BIG
1070 * @retval VWRN_NEGATIVE_UNSIGNED
1071 * @retval VINF_SUCCESS
1072 * @retval VERR_NO_DIGITS
1073 * @retval VERR_TRAILING_SPACES
1074 * @retval VERR_TRAILING_CHARS
1075 *
1076 * @param pszValue Pointer to the string value.
1077 * @param uBase The base of the representation used.
1078 * If 0 the function will look for known prefixes before defaulting to 10.
1079 * @param pu32 Where to store the converted number. (optional)
1080 */
1081RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
1082
1083/**
1084 * Converts a string representation of a number to a 64-bit unsigned number.
1085 * The base is guessed.
1086 *
1087 * @returns 32-bit unsigned number on success.
1088 * @returns 0 on failure.
1089 * @param pszValue Pointer to the string value.
1090 */
1091RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
1092
1093/**
1094 * Converts a string representation of a number to a 16-bit unsigned number.
1095 *
1096 * @returns iprt status code.
1097 * Warnings are used to indicate conversion problems.
1098 * @retval VWRN_NUMBER_TOO_BIG
1099 * @retval VWRN_NEGATIVE_UNSIGNED
1100 * @retval VWRN_TRAILING_CHARS
1101 * @retval VWRN_TRAILING_SPACES
1102 * @retval VINF_SUCCESS
1103 * @retval VERR_NO_DIGITS
1104 *
1105 * @param pszValue Pointer to the string value.
1106 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1107 * @param uBase The base of the representation used.
1108 * If 0 the function will look for known prefixes before defaulting to 10.
1109 * @param pu16 Where to store the converted number. (optional)
1110 */
1111RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
1112
1113/**
1114 * Converts a string representation of a number to a 16-bit unsigned number,
1115 * making sure the full string is converted.
1116 *
1117 * @returns iprt status code.
1118 * Warnings are used to indicate conversion problems.
1119 * @retval VWRN_NUMBER_TOO_BIG
1120 * @retval VWRN_NEGATIVE_UNSIGNED
1121 * @retval VINF_SUCCESS
1122 * @retval VERR_NO_DIGITS
1123 * @retval VERR_TRAILING_SPACES
1124 * @retval VERR_TRAILING_CHARS
1125 *
1126 * @param pszValue Pointer to the string value.
1127 * @param uBase The base of the representation used.
1128 * If 0 the function will look for known prefixes before defaulting to 10.
1129 * @param pu16 Where to store the converted number. (optional)
1130 */
1131RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
1132
1133/**
1134 * Converts a string representation of a number to a 16-bit unsigned number.
1135 * The base is guessed.
1136 *
1137 * @returns 16-bit unsigned number on success.
1138 * @returns 0 on failure.
1139 * @param pszValue Pointer to the string value.
1140 */
1141RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
1142
1143/**
1144 * Converts a string representation of a number to a 8-bit unsigned number.
1145 *
1146 * @returns iprt status code.
1147 * Warnings are used to indicate conversion problems.
1148 * @retval VWRN_NUMBER_TOO_BIG
1149 * @retval VWRN_NEGATIVE_UNSIGNED
1150 * @retval VWRN_TRAILING_CHARS
1151 * @retval VWRN_TRAILING_SPACES
1152 * @retval VINF_SUCCESS
1153 * @retval VERR_NO_DIGITS
1154 *
1155 * @param pszValue Pointer to the string value.
1156 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1157 * @param uBase The base of the representation used.
1158 * If 0 the function will look for known prefixes before defaulting to 10.
1159 * @param pu8 Where to store the converted number. (optional)
1160 */
1161RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
1162
1163/**
1164 * Converts a string representation of a number to a 8-bit unsigned number,
1165 * making sure the full string is converted.
1166 *
1167 * @returns iprt status code.
1168 * Warnings are used to indicate conversion problems.
1169 * @retval VWRN_NUMBER_TOO_BIG
1170 * @retval VWRN_NEGATIVE_UNSIGNED
1171 * @retval VINF_SUCCESS
1172 * @retval VERR_NO_DIGITS
1173 * @retval VERR_TRAILING_SPACES
1174 * @retval VERR_TRAILING_CHARS
1175 *
1176 * @param pszValue Pointer to the string value.
1177 * @param uBase The base of the representation used.
1178 * If 0 the function will look for known prefixes before defaulting to 10.
1179 * @param pu8 Where to store the converted number. (optional)
1180 */
1181RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
1182
1183/**
1184 * Converts a string representation of a number to a 8-bit unsigned number.
1185 * The base is guessed.
1186 *
1187 * @returns 8-bit unsigned number on success.
1188 * @returns 0 on failure.
1189 * @param pszValue Pointer to the string value.
1190 */
1191RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
1192
1193/**
1194 * Converts a string representation of a number to a 64-bit signed number.
1195 *
1196 * @returns iprt status code.
1197 * Warnings are used to indicate conversion problems.
1198 * @retval VWRN_NUMBER_TOO_BIG
1199 * @retval VWRN_TRAILING_CHARS
1200 * @retval VWRN_TRAILING_SPACES
1201 * @retval VINF_SUCCESS
1202 * @retval VERR_NO_DIGITS
1203 *
1204 * @param pszValue Pointer to the string value.
1205 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1206 * @param uBase The base of the representation used.
1207 * If 0 the function will look for known prefixes before defaulting to 10.
1208 * @param pi64 Where to store the converted number. (optional)
1209 */
1210RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
1211
1212/**
1213 * Converts a string representation of a number to a 64-bit signed number,
1214 * making sure the full string is converted.
1215 *
1216 * @returns iprt status code.
1217 * Warnings are used to indicate conversion problems.
1218 * @retval VWRN_NUMBER_TOO_BIG
1219 * @retval VINF_SUCCESS
1220 * @retval VERR_TRAILING_CHARS
1221 * @retval VERR_TRAILING_SPACES
1222 * @retval VERR_NO_DIGITS
1223 *
1224 * @param pszValue Pointer to the string value.
1225 * @param uBase The base of the representation used.
1226 * If 0 the function will look for known prefixes before defaulting to 10.
1227 * @param pi64 Where to store the converted number. (optional)
1228 */
1229RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
1230
1231/**
1232 * Converts a string representation of a number to a 64-bit signed number.
1233 * The base is guessed.
1234 *
1235 * @returns 64-bit signed number on success.
1236 * @returns 0 on failure.
1237 * @param pszValue Pointer to the string value.
1238 */
1239RTDECL(int64_t) RTStrToInt64(const char *pszValue);
1240
1241/**
1242 * Converts a string representation of a number to a 32-bit signed number.
1243 *
1244 * @returns iprt status code.
1245 * Warnings are used to indicate conversion problems.
1246 * @retval VWRN_NUMBER_TOO_BIG
1247 * @retval VWRN_TRAILING_CHARS
1248 * @retval VWRN_TRAILING_SPACES
1249 * @retval VINF_SUCCESS
1250 * @retval VERR_NO_DIGITS
1251 *
1252 * @param pszValue Pointer to the string value.
1253 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1254 * @param uBase The base of the representation used.
1255 * If 0 the function will look for known prefixes before defaulting to 10.
1256 * @param pi32 Where to store the converted number. (optional)
1257 */
1258RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
1259
1260/**
1261 * Converts a string representation of a number to a 32-bit signed number,
1262 * making sure the full string is converted.
1263 *
1264 * @returns iprt status code.
1265 * Warnings are used to indicate conversion problems.
1266 * @retval VWRN_NUMBER_TOO_BIG
1267 * @retval VINF_SUCCESS
1268 * @retval VERR_TRAILING_CHARS
1269 * @retval VERR_TRAILING_SPACES
1270 * @retval VERR_NO_DIGITS
1271 *
1272 * @param pszValue Pointer to the string value.
1273 * @param uBase The base of the representation used.
1274 * If 0 the function will look for known prefixes before defaulting to 10.
1275 * @param pi32 Where to store the converted number. (optional)
1276 */
1277RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
1278
1279/**
1280 * Converts a string representation of a number to a 32-bit signed number.
1281 * The base is guessed.
1282 *
1283 * @returns 32-bit signed number on success.
1284 * @returns 0 on failure.
1285 * @param pszValue Pointer to the string value.
1286 */
1287RTDECL(int32_t) RTStrToInt32(const char *pszValue);
1288
1289/**
1290 * Converts a string representation of a number to a 16-bit signed number.
1291 *
1292 * @returns iprt status code.
1293 * Warnings are used to indicate conversion problems.
1294 * @retval VWRN_NUMBER_TOO_BIG
1295 * @retval VWRN_TRAILING_CHARS
1296 * @retval VWRN_TRAILING_SPACES
1297 * @retval VINF_SUCCESS
1298 * @retval VERR_NO_DIGITS
1299 *
1300 * @param pszValue Pointer to the string value.
1301 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1302 * @param uBase The base of the representation used.
1303 * If 0 the function will look for known prefixes before defaulting to 10.
1304 * @param pi16 Where to store the converted number. (optional)
1305 */
1306RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
1307
1308/**
1309 * Converts a string representation of a number to a 16-bit signed number,
1310 * making sure the full string is converted.
1311 *
1312 * @returns iprt status code.
1313 * Warnings are used to indicate conversion problems.
1314 * @retval VWRN_NUMBER_TOO_BIG
1315 * @retval VINF_SUCCESS
1316 * @retval VERR_TRAILING_CHARS
1317 * @retval VERR_TRAILING_SPACES
1318 * @retval VERR_NO_DIGITS
1319 *
1320 * @param pszValue Pointer to the string value.
1321 * @param uBase The base of the representation used.
1322 * If 0 the function will look for known prefixes before defaulting to 10.
1323 * @param pi16 Where to store the converted number. (optional)
1324 */
1325RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
1326
1327/**
1328 * Converts a string representation of a number to a 16-bit signed number.
1329 * The base is guessed.
1330 *
1331 * @returns 16-bit signed number on success.
1332 * @returns 0 on failure.
1333 * @param pszValue Pointer to the string value.
1334 */
1335RTDECL(int16_t) RTStrToInt16(const char *pszValue);
1336
1337/**
1338 * Converts a string representation of a number to a 8-bit signed number.
1339 *
1340 * @returns iprt status code.
1341 * Warnings are used to indicate conversion problems.
1342 * @retval VWRN_NUMBER_TOO_BIG
1343 * @retval VWRN_TRAILING_CHARS
1344 * @retval VWRN_TRAILING_SPACES
1345 * @retval VINF_SUCCESS
1346 * @retval VERR_NO_DIGITS
1347 *
1348 * @param pszValue Pointer to the string value.
1349 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
1350 * @param uBase The base of the representation used.
1351 * If 0 the function will look for known prefixes before defaulting to 10.
1352 * @param pi8 Where to store the converted number. (optional)
1353 */
1354RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
1355
1356/**
1357 * Converts a string representation of a number to a 8-bit signed number,
1358 * making sure the full string is converted.
1359 *
1360 * @returns iprt status code.
1361 * Warnings are used to indicate conversion problems.
1362 * @retval VWRN_NUMBER_TOO_BIG
1363 * @retval VINF_SUCCESS
1364 * @retval VERR_TRAILING_CHARS
1365 * @retval VERR_TRAILING_SPACES
1366 * @retval VERR_NO_DIGITS
1367 *
1368 * @param pszValue Pointer to the string value.
1369 * @param uBase The base of the representation used.
1370 * If 0 the function will look for known prefixes before defaulting to 10.
1371 * @param pi8 Where to store the converted number. (optional)
1372 */
1373RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
1374
1375/**
1376 * Converts a string representation of a number to a 8-bit signed number.
1377 * The base is guessed.
1378 *
1379 * @returns 8-bit signed number on success.
1380 * @returns 0 on failure.
1381 * @param pszValue Pointer to the string value.
1382 */
1383RTDECL(int8_t) RTStrToInt8(const char *pszValue);
1384
1385/** @} */
1386
1387
1388/** @defgroup rt_str_space Unique String Space
1389 * @ingroup grp_rt_str
1390 * @{
1391 */
1392
1393/** Pointer to a string name space container node core. */
1394typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
1395/** Pointer to a pointer to a string name space container node core. */
1396typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
1397
1398/**
1399 * String name space container node core.
1400 */
1401typedef struct RTSTRSPACECORE
1402{
1403 /** Hash key. Don't touch. */
1404 uint32_t Key;
1405 /** Pointer to the left leaf node. Don't touch. */
1406 PRTSTRSPACECORE pLeft;
1407 /** Pointer to the left rigth node. Don't touch. */
1408 PRTSTRSPACECORE pRight;
1409 /** Pointer to the list of string with the same key. Don't touch. */
1410 PRTSTRSPACECORE pList;
1411 /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
1412 unsigned char uchHeight;
1413 /** The string length. Read only! */
1414 size_t cchString;
1415 /** Pointer to the string. Read only! */
1416 const char * pszString;
1417} RTSTRSPACECORE;
1418
1419/** String space. (Initialize with NULL.) */
1420typedef PRTSTRSPACECORE RTSTRSPACE;
1421/** Pointer to a string space. */
1422typedef PPRTSTRSPACECORE PRTSTRSPACE;
1423
1424
1425/**
1426 * Inserts a string into a unique string space.
1427 *
1428 * @returns true on success.
1429 * @returns false if the string collided with an existing string.
1430 * @param pStrSpace The space to insert it into.
1431 * @param pStr The string node.
1432 */
1433RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
1434
1435/**
1436 * Removes a string from a unique string space.
1437 *
1438 * @returns Pointer to the removed string node.
1439 * @returns NULL if the string was not found in the string space.
1440 * @param pStrSpace The space to insert it into.
1441 * @param pszString The string to remove.
1442 */
1443RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
1444
1445/**
1446 * Gets a string from a unique string space.
1447 *
1448 * @returns Pointer to the string node.
1449 * @returns NULL if the string was not found in the string space.
1450 * @param pStrSpace The space to insert it into.
1451 * @param pszString The string to get.
1452 */
1453RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
1454
1455/**
1456 * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
1457 *
1458 * @returns 0 on continue.
1459 * @returns Non-zero to aborts the operation.
1460 * @param pStr The string node
1461 * @param pvUser The user specified argument.
1462 */
1463typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
1464/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
1465typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
1466
1467/**
1468 * Destroys the string space.
1469 * The caller supplies a callback which will be called for each of
1470 * the string nodes in for freeing their memory and other resources.
1471 *
1472 * @returns 0 or what ever non-zero return value pfnCallback returned
1473 * when aborting the destruction.
1474 * @param pStrSpace The space to insert it into.
1475 * @param pfnCallback The callback.
1476 * @param pvUser The user argument.
1477 */
1478RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
1479
1480/**
1481 * Enumerates the string space.
1482 * The caller supplies a callback which will be called for each of
1483 * the string nodes.
1484 *
1485 * @returns 0 or what ever non-zero return value pfnCallback returned
1486 * when aborting the destruction.
1487 * @param pStrSpace The space to insert it into.
1488 * @param pfnCallback The callback.
1489 * @param pvUser The user argument.
1490 */
1491RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
1492
1493/** @} */
1494
1495
1496/** @defgroup rt_str_utf16 UTF-16 String Manipulation
1497 * @ingroup grp_rt_str
1498 * @{
1499 */
1500
1501/**
1502 * Free a UTF-16 string allocated by RTStrUtf8ToUtf16(), RTStrUtf8ToUtf16Ex(),
1503 * RTUtf16Dup() or RTUtf16DupEx().
1504 *
1505 * @returns iprt status code.
1506 * @param pwszString The UTF-16 string to free. NULL is accepted.
1507 */
1508RTDECL(void) RTUtf16Free(PRTUTF16 pwszString);
1509
1510/**
1511 * Allocates a new copy of the specified UTF-16 string.
1512 *
1513 * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
1514 * @returns NULL when out of memory.
1515 * @param pwszString UTF-16 string to duplicate.
1516 * @remark This function will not make any attempt to validate the encoding.
1517 */
1518RTDECL(PRTUTF16) RTUtf16Dup(PCRTUTF16 pwszString);
1519
1520/**
1521 * Allocates a new copy of the specified UTF-16 string.
1522 *
1523 * @returns iprt status code.
1524 * @param ppwszString Receives pointer of the allocated UTF-16 string.
1525 * The returned pointer must be freed using RTUtf16Free().
1526 * @param pwszString UTF-16 string to duplicate.
1527 * @param cwcExtra Number of extra RTUTF16 items to allocate.
1528 * @remark This function will not make any attempt to validate the encoding.
1529 */
1530RTDECL(int) RTUtf16DupEx(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra);
1531
1532/**
1533 * Returns the length of a UTF-16 string in UTF-16 characters
1534 * without trailing '\\0'.
1535 *
1536 * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
1537 * to get the exact number of code points in the string.
1538 *
1539 * @returns The number of RTUTF16 items in the string.
1540 * @param pwszString Pointer the UTF-16 string.
1541 * @remark This function will not make any attempt to validate the encoding.
1542 */
1543RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
1544
1545/**
1546 * Performs a case sensitive string compare between two UTF-16 strings.
1547 *
1548 * @returns < 0 if the first string less than the second string.s
1549 * @returns 0 if the first string identical to the second string.
1550 * @returns > 0 if the first string greater than the second string.
1551 * @param pwsz1 First UTF-16 string. Null is allowed.
1552 * @param pwsz2 Second UTF-16 string. Null is allowed.
1553 * @remark This function will not make any attempt to validate the encoding.
1554 */
1555RTDECL(int) RTUtf16Cmp(register PCRTUTF16 pwsz1, register PCRTUTF16 pwsz2);
1556
1557/**
1558 * Performs a case insensitive string compare between two UTF-16 strings.
1559 *
1560 * This is a simplified compare, as only the simplified lower/upper case folding
1561 * specified by the unicode specs are used. It does not consider character pairs
1562 * as they are used in some languages, just simple upper & lower case compares.
1563 *
1564 * @returns < 0 if the first string less than the second string.
1565 * @returns 0 if the first string identical to the second string.
1566 * @returns > 0 if the first string greater than the second string.
1567 * @param pwsz1 First UTF-16 string. Null is allowed.
1568 * @param pwsz2 Second UTF-16 string. Null is allowed.
1569 */
1570RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
1571
1572/**
1573 * Performs a case insensitive string compare between two UTF-16 strings
1574 * using the current locale of the process (if applicable).
1575 *
1576 * This differs from RTUtf16ICmp() in that it will try, if a locale with the
1577 * required data is available, to do a correct case-insensitive compare. It
1578 * follows that it is more complex and thereby likely to be more expensive.
1579 *
1580 * @returns < 0 if the first string less than the second string.
1581 * @returns 0 if the first string identical to the second string.
1582 * @returns > 0 if the first string greater than the second string.
1583 * @param pwsz1 First UTF-16 string. Null is allowed.
1584 * @param pwsz2 Second UTF-16 string. Null is allowed.
1585 */
1586RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
1587
1588/**
1589 * Folds a UTF-16 string to lowercase.
1590 *
1591 * This is a very simple folding; is uses the simple lowercase
1592 * code point, it is not related to any locale just the most common
1593 * lowercase codepoint setup by the unicode specs, and it will not
1594 * create new surrogate pairs or remove existing ones.
1595 *
1596 * @returns Pointer to the passed in string.
1597 * @param pwsz The string to fold.
1598 */
1599RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
1600
1601/**
1602 * Folds a UTF-16 string to uppercase.
1603 *
1604 * This is a very simple folding; is uses the simple uppercase
1605 * code point, it is not related to any locale just the most common
1606 * uppercase codepoint setup by the unicode specs, and it will not
1607 * create new surrogate pairs or remove existing ones.
1608 *
1609 * @returns Pointer to the passed in string.
1610 * @param pwsz The string to fold.
1611 */
1612RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
1613
1614/**
1615 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
1616 *
1617 * @returns iprt status code.
1618 * @param pwszString UTF-16 string to convert.
1619 * @param ppszString Receives pointer of allocated UTF-8 string on
1620 * success, and is always set to NULL on failure.
1621 * The returned pointer must be freed using RTStrFree().
1622 */
1623RTDECL(int) RTUtf16ToUtf8(PCRTUTF16 pwszString, char **ppszString);
1624
1625/**
1626 * Translates UTF-16 to UTF-8 using buffer provided by the caller or
1627 * a fittingly sized buffer allocated by the function.
1628 *
1629 * @returns iprt status code.
1630 * @param pwszString The UTF-16 string to convert.
1631 * @param cwcString The number of RTUTF16 items to translate from pwszString.
1632 * The translation will stop when reaching cwcString or the terminator ('\\0').
1633 * Use RTSTR_MAX to translate the entire string.
1634 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
1635 * a buffer of the specified size, or pointer to a NULL pointer.
1636 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
1637 * will be allocated to hold the translated string.
1638 * If a buffer was requested it must be freed using RTUtf16Free().
1639 * @param cch The buffer size in chars (the type). This includes the terminator.
1640 * @param pcch Where to store the length of the translated string. (Optional)
1641 * This field will be updated even on failure, however the value is only
1642 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
1643 * and VERR_NO_STR_MEMORY it contains the required buffer space.
1644 */
1645RTDECL(int) RTUtf16ToUtf8Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
1646
1647/**
1648 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
1649 *
1650 * This function will validate the string, and incorrectly encoded UTF-16
1651 * strings will be rejected. The primary purpose of this function is to
1652 * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
1653 * other purposes RTUtf16ToUtf8Ex() should be used.
1654 *
1655 * @returns Number of char (bytes).
1656 * @returns 0 if the string was incorrectly encoded.
1657 * @param pwsz The UTF-16 string.
1658 */
1659RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
1660
1661/**
1662 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
1663 *
1664 * This function will validate the string, and incorrectly encoded UTF-16
1665 * strings will be rejected.
1666 *
1667 * @returns iprt status code.
1668 * @param pwsz The string.
1669 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
1670 * @param pcch Where to store the string length (in bytes). Optional.
1671 * This is undefined on failure.
1672 */
1673RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
1674
1675/**
1676 * Get the unicode code point at the given string position.
1677 *
1678 * @returns unicode code point.
1679 * @returns RTUNICP_INVALID if the encoding is invalid.
1680 * @param pwsz The string.
1681 *
1682 * @remark This is an internal worker for RTUtf16GetCp().
1683 */
1684RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
1685
1686/**
1687 * Get the unicode code point at the given string position.
1688 *
1689 * @returns iprt status code.
1690 * @param ppwsz Pointer to the string pointer. This will be updated to
1691 * point to the char following the current code point.
1692 * @param pCp Where to store the code point.
1693 * RTUNICP_INVALID is stored here on failure.
1694 *
1695 * @remark This is an internal worker for RTUtf16GetCpEx().
1696 */
1697RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1698
1699/**
1700 * Put the unicode code point at the given string position
1701 * and return the pointer to the char following it.
1702 *
1703 * This function will not consider anything at or following the
1704 * buffer area pointed to by pwsz. It is therefore not suitable for
1705 * inserting code points into a string, only appending/overwriting.
1706 *
1707 * @returns pointer to the char following the written code point.
1708 * @param pwsz The string.
1709 * @param CodePoint The code point to write.
1710 * This should not be RTUNICP_INVALID or any other
1711 * character out of the UTF-16 range.
1712 *
1713 * @remark This is an internal worker for RTUtf16GetCpEx().
1714 */
1715RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
1716
1717/**
1718 * Get the unicode code point at the given string position.
1719 *
1720 * @returns unicode code point.
1721 * @returns RTUNICP_INVALID if the encoding is invalid.
1722 * @param pwsz The string.
1723 *
1724 * @remark We optimize this operation by using an inline function for
1725 * everything which isn't a surrogate pair or an endian indicator.
1726 */
1727DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
1728{
1729 const RTUTF16 wc = *pwsz;
1730 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1731 return wc;
1732 return RTUtf16GetCpInternal(pwsz);
1733}
1734
1735/**
1736 * Get the unicode code point at the given string position.
1737 *
1738 * @returns iprt status code.
1739 * @param ppwsz Pointer to the string pointer. This will be updated to
1740 * point to the char following the current code point.
1741 * @param pCp Where to store the code point.
1742 * RTUNICP_INVALID is stored here on failure.
1743 *
1744 * @remark We optimize this operation by using an inline function for
1745 * everything which isn't a surrogate pair or and endian indicator.
1746 */
1747DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1748{
1749 const RTUTF16 wc = **ppwsz;
1750 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1751 {
1752 (*ppwsz)++;
1753 *pCp = wc;
1754 return VINF_SUCCESS;
1755 }
1756 return RTUtf16GetCpExInternal(ppwsz, pCp);
1757}
1758
1759/**
1760 * Put the unicode code point at the given string position
1761 * and return the pointer to the char following it.
1762 *
1763 * This function will not consider anything at or following the
1764 * buffer area pointed to by pwsz. It is therefore not suitable for
1765 * inserting code points into a string, only appending/overwriting.
1766 *
1767 * @returns pointer to the char following the written code point.
1768 * @param pwsz The string.
1769 * @param CodePoint The code point to write.
1770 * This should not be RTUNICP_INVALID or any other
1771 * character out of the UTF-16 range.
1772 *
1773 * @remark We optimize this operation by using an inline function for
1774 * everything which isn't a surrogate pair or and endian indicator.
1775 */
1776DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
1777{
1778 if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
1779 {
1780 *pwsz++ = (RTUTF16)CodePoint;
1781 return pwsz;
1782 }
1783 return RTUtf16PutCpInternal(pwsz, CodePoint);
1784}
1785
1786/**
1787 * Skips ahead, past the current code point.
1788 *
1789 * @returns Pointer to the char after the current code point.
1790 * @param pwsz Pointer to the current code point.
1791 * @remark This will not move the next valid code point, only past the current one.
1792 */
1793DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
1794{
1795 RTUNICP Cp;
1796 RTUtf16GetCpEx(&pwsz, &Cp);
1797 return (PRTUTF16)pwsz;
1798}
1799
1800/**
1801 * Skips backwards, to the previous code point.
1802 *
1803 * @returns Pointer to the char after the current code point.
1804 * @param pwszStart Pointer to the start of the string.
1805 * @param pwsz Pointer to the current code point.
1806 */
1807RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
1808
1809
1810/**
1811 * Checks if the UTF-16 char is the high surrogate char (i.e.
1812 * the 1st char in the pair).
1813 *
1814 * @returns true if it is.
1815 * @returns false if it isn't.
1816 * @param wc The character to investigate.
1817 */
1818DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
1819{
1820 return wc >= 0xd800 && wc <= 0xdbff;
1821}
1822
1823/**
1824 * Checks if the UTF-16 char is the low surrogate char (i.e.
1825 * the 2nd char in the pair).
1826 *
1827 * @returns true if it is.
1828 * @returns false if it isn't.
1829 * @param wc The character to investigate.
1830 */
1831DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
1832{
1833 return wc >= 0xdc00 && wc <= 0xdfff;
1834}
1835
1836
1837/**
1838 * Checks if the two UTF-16 chars form a valid surrogate pair.
1839 *
1840 * @returns true if they do.
1841 * @returns false if they doesn't.
1842 * @param wcHigh The high (1st) character.
1843 * @param wcLow The low (2nd) character.
1844 */
1845DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
1846{
1847 return RTUtf16IsHighSurrogate(wcHigh)
1848 && RTUtf16IsLowSurrogate(wcLow);
1849}
1850
1851/** @} */
1852
1853__END_DECLS
1854
1855/** @} */
1856
1857#endif
1858
Note: See TracBrowser for help on using the repository browser.

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