VirtualBox

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

Last change on this file since 289 was 204, checked in by vboxsync, 18 years ago

runtime.h now includes everything. Created a new header, initterm.h, which includes the RT*Init/Term() prototypes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 49.1 KB
Line 
1/** @file
2 * InnoTek Portable Runtime - String Manipluation.
3 */
4
5/*
6 * Copyright (C) 2006 InnoTek Systemberatung GmbH
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 as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21
22#ifndef __iprt_string_h__
23#define __iprt_string_h__
24
25#include <iprt/cdefs.h>
26#include <iprt/types.h>
27#include <iprt/stdarg.h>
28#include <iprt/err.h> /* for VINF_SUCCESS */
29#if defined(__LINUX__) && defined(__KERNEL__)
30# ifndef bool /* Linux 2.6.19 C++ nightmare */
31# define bool bool_type
32# define true true_type
33# define false false_type
34# define _Bool int
35# define bool_type_iprt_string_h__
36# endif
37# include <linux/string.h>
38# ifdef bool_type_iprt_string_h__
39# undef bool
40# undef true
41# undef false
42# undef _Bool
43# undef bool_type_iprt_string_h__
44# endif
45#else
46# include <string.h>
47#endif
48
49/*
50 * Supply prototypes for standard string functions provided by
51 * IPRT instead of the operating environment.
52 */
53#if defined(__DARWIN__) && defined(KERNEL)
54__BEGIN_DECLS
55void *memchr(const void *pv, int ch, size_t cb);
56char *strpbrk(const char *pszStr, const char *pszChars);
57__END_DECLS
58#endif
59
60
61/** @defgroup grp_rt_str RTStr - String Manipulation
62 * Mostly UTF-8 related helpers where the standard string functions won't do.
63 * @ingroup grp_rt
64 * @{
65 */
66
67__BEGIN_DECLS
68
69
70/**
71 * The maximum string length.
72 */
73#define RTSTR_MAX (~(size_t)0)
74
75
76#ifdef IN_RING3
77
78/**
79 * Allocates tmp buffer, translates pszString from UTF8 to current codepage.
80 *
81 * @returns iprt status code.
82 * @param ppszString Receives pointer of allocated native CP string.
83 * The returned pointer must be freed using RTStrFree().
84 * @param pszString UTF-8 string to convert.
85 */
86RTR3DECL(int) RTStrUtf8ToCurrentCP(char **ppszString, const char *pszString);
87
88/**
89 * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
90 *
91 * @returns iprt status code.
92 * @param ppszString Receives pointer of allocated UTF-8 string.
93 * The returned pointer must be freed using RTStrFree().
94 * @param pszString Native string to convert.
95 */
96RTR3DECL(int) RTStrCurrentCPToUtf8(char **ppszString, const char *pszString);
97
98#endif
99
100/**
101 * Free string allocated by any of the non-UCS-2 string functions.
102 *
103 * @returns iprt status code.
104 * @param pszString Pointer to buffer with string to free.
105 * NULL is accepted.
106 */
107RTDECL(void) RTStrFree(char *pszString);
108
109/**
110 * Allocates a new copy of the given UTF-8 string.
111 *
112 * @returns Pointer to the allocated UTF-8 string.
113 * @param pszString UTF-8 string to duplicate.
114 */
115RTDECL(char *) RTStrDup(const char *pszString);
116
117/**
118 * Allocates a new copy of the given UTF-8 string.
119 *
120 * @returns iprt status code.
121 * @param ppszString Receives pointer of the allocated UTF-8 string.
122 * The returned pointer must be freed using RTStrFree().
123 * @param pszString UTF-8 string to duplicate.
124 */
125RTDECL(int) RTStrDupEx(char **ppszString, const char *pszString);
126
127/**
128 * Gets the number of code points the string is made up of, excluding
129 * the terminator.
130 *
131 *
132 * @returns Number of code points (RTUNICP).
133 * @returns 0 if the string was incorrectly encoded.
134 * @param psz The string.
135 */
136RTDECL(size_t) RTStrUniLen(const char *psz);
137
138/**
139 * Gets the number of code points the string is made up of, excluding
140 * the terminator.
141 *
142 * This function will validate the string, and incorrectly encoded UTF-8
143 * strings will be rejected.
144 *
145 * @returns iprt status code.
146 * @param psz The string.
147 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
148 * @param pcuc Where to store the code point count.
149 * This is undefined on failure.
150 */
151RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
152
153/**
154 * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
155 *
156 * @returns iprt status code.
157 * @param pszString UTF-8 string to convert.
158 * @param ppUniString Receives pointer to the allocated unicode string.
159 * The returned string must be freed using RTUniFree().
160 */
161RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
162
163/**
164 * Translates pszString from UTF-8 to an array of code points, allocating the result
165 * array if requested.
166 *
167 * @returns iprt status code.
168 * @param pszString UTF-8 string to convert.
169 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
170 * when it reaches cchString or the string terminator ('\\0').
171 * Use RTSTR_MAX to translate the entire string.
172 * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
173 * a buffer of the specified size, or pointer to a NULL pointer.
174 * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
175 * will be allocated to hold the translated string.
176 * If a buffer was requirest it must be freed using RTUtf16Free().
177 * @param cCps The number of code points in the unicode string. This includes the terminator.
178 * @param pcCps Where to store the length of the translated string. (Optional)
179 * This field will be updated even on failure, however the value is only
180 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
181 * and VERR_NO_STR_MEMORY it contains the required buffer space.
182 */
183RTDECL(int) RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
184
185/**
186 * Calculates the length of the string in RTUTF16 items.
187 *
188 * This function will validate the string, and incorrectly encoded UTF-8
189 * strings will be rejected. The primary purpose of this function is to
190 * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
191 * other puroses RTStrCalcUtf16LenEx() should be used.
192 *
193 * @returns Number of RTUTF16 items.
194 * @returns 0 if the string was incorrectly encoded.
195 * @param psz The string.
196 */
197RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
198
199/**
200 * Calculates the length of the string in RTUTF16 items.
201 *
202 * This function will validate the string, and incorrectly encoded UTF-8
203 * strings will be rejected.
204 *
205 * @returns iprt status code.
206 * @param psz The string.
207 * @param cch The max string length. Use RTSTR_MAX to process the entire string.
208 * @param pcwc Where to store the string length. Optional.
209 * This is undefined on failure.
210 */
211RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
212
213/**
214 * Translate a UTF-8 string into a UTF-16 allocating the result buffer.
215 *
216 * @returns iprt status code.
217 * @param pszString UTF-8 string to convert.
218 * @param ppwszString Receives pointer to the allocated UTF-16 string.
219 * The returned string must be freed using RTUtf16Free().
220 */
221RTDECL(int) RTStrToUtf16(const char *pszString, PRTUTF16 *ppwszString);
222
223/**
224 * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
225 *
226 * @returns iprt status code.
227 * @param pszString UTF-8 string to convert.
228 * @param cchString The maximum size in chars (the type) to convert. The conversion stop
229 * when it reaches cchString or the string terminator ('\\0').
230 * Use RTSTR_MAX to translate the entire string.
231 * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
232 * a buffer of the specified size, or pointer to a NULL pointer.
233 * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
234 * will be allocated to hold the translated string.
235 * If a buffer was requirest it must be freed using RTUtf16Free().
236 * @param cwc The buffer size in RTUTF16s. This includes the terminator.
237 * @param pcwc Where to store the length of the translated string. (Optional)
238 * This field will be updated even on failure, however the value is only
239 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
240 * and VERR_NO_STR_MEMORY it contains the required buffer space.
241 */
242RTDECL(int) RTStrToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
243
244/**
245 * Allocates tmp buffer, translates pszString from UTF8 to UCS-2.
246 *
247 * @returns iprt status code.
248 * @param ppwszString Receives pointer of allocated UCS-2 string.
249 * The returned pointer must be freed using RTStrUcs2Free().
250 * @param pszString UTF-8 string to convert.
251 * @deprecated Use RTStrToUtf16().
252 */
253DECLINLINE(int) RTStrUtf8ToUcs2(PRTUCS2 *ppwszString, const char *pszString)
254{
255 return RTStrToUtf16(pszString, ppwszString);
256}
257
258/**
259 * Translates pszString from UTF8 to backwater UCS-2, can allocate a temp buffer.
260 *
261 * @returns iprt status code.
262 * @param ppwszString Receives pointer of allocated UCS-2 string.
263 * The returned pointer must be freed using RTStrUcs2Free().
264 * @param cwc Length of target buffer in RTUCS2s including the trailing '\\0'.
265 * If 0 a temporary buffer is allocated.
266 * @param pszString UTF-8 string to convert.
267 * @deprecated Use RTStrToUtf16Ex().
268 */
269DECLINLINE(int) RTStrUtf8ToUcs2Ex(PRTUCS2 *ppwszString, unsigned cwc, const char *pszString)
270{
271 return RTStrToUtf16Ex(pszString, RTSTR_MAX, ppwszString, cwc, NULL);
272}
273
274
275/**
276 * Get the unicode code point at the given string position.
277 *
278 * @returns unicode code point.
279 * @returns RTUNICP_INVALID if the encoding is invalid.
280 * @param psz The string.
281 */
282RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
283
284/**
285 * Get the unicode code point at the given string position.
286 *
287 * @returns unicode code point.
288 * @returns RTUNICP_INVALID if the encoding is invalid.
289 * @param ppsz The string.
290 * @param pCp Where to store the unicode code point.
291 */
292RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
293
294/**
295 * Put the unicode code point at the given string position
296 * and return the pointer to the char following it.
297 *
298 * This function will not consider anything at or following the the
299 * buffer area pointed to by psz. It is therefore not suitable for
300 * inserting code points into a string, only appending/overwriting.
301 *
302 * @returns pointer to the char following the written code point.
303 * @param psz The string.
304 * @param CodePoint The code point to write.
305 * This sould not be RTUNICP_INVALID or any other charater
306 * out of the UTF-8 range.
307 *
308 * @remark This is a worker function for RTStrPutCp().
309 *
310 */
311RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
312
313/**
314 * Get the unicode code point at the given string position.
315 *
316 * @returns unicode code point.
317 * @returns RTUNICP_INVALID if the encoding is invalid.
318 * @param psz The string.
319 *
320 * @remark We optimize this operation by using an inline function for
321 * the most frequent and simplest sequence, the rest is
322 * handled by RTStrGetCpInternal().
323 */
324DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
325{
326 const unsigned char uch = *(const unsigned char *)psz;
327 if (!(uch & BIT(7)))
328 return uch;
329 return RTStrGetCpInternal(psz);
330}
331
332/**
333 * Get the unicode code point at the given string position.
334 *
335 * @returns iprt status code.
336 * @param ppsz Pointer to the string pointer. This will be updated to
337 * point to the char following the current code point.
338 * @param pCp Where to store the code point.
339 * RTUNICP_INVALID is stored here on failure.
340 *
341 * @remark We optimize this operation by using an inline function for
342 * the most frequent and simplest sequence, the rest is
343 * handled by RTStrGetCpExInternal().
344 */
345DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
346{
347 const unsigned char uch = **(const unsigned char **)ppsz;
348 if (!(uch & BIT(7)))
349 {
350 (*ppsz)++;
351 *pCp = uch;
352 return VINF_SUCCESS;
353 }
354 return RTStrGetCpExInternal(ppsz, pCp);
355}
356
357/**
358 * Put the unicode code point at the given string position
359 * and return the pointer to the char following it.
360 *
361 * This function will not consider anything at or following the the
362 * buffer area pointed to by psz. It is therefore not suitable for
363 * inserting code points into a string, only appending/overwriting.
364 *
365 * @returns pointer to the char following the written code point.
366 * @param psz The string.
367 * @param CodePoint The code point to write.
368 * This sould not be RTUNICP_INVALID or any other charater
369 * out of the UTF-8 range.
370 *
371 * @remark We optimize this operation by using an inline function for
372 * the most frequent and simplest sequence, the rest is
373 * handled by RTStrPutCpInternal().
374 */
375DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
376{
377 if (CodePoint < 0x80)
378 {
379 *psz++ = (unsigned char)CodePoint;
380 return psz;
381 }
382 return RTStrPutCpInternal(psz, CodePoint);
383}
384
385/**
386 * Skips ahead, past the current code point.
387 *
388 * @returns Pointer to the char after the current code point.
389 * @param psz Pointer to the current code point.
390 * @remark This will not move the next valid code point, only past the current one.
391 */
392DECLINLINE(char *) RTStrNextCp(const char *psz)
393{
394 RTUNICP Cp;
395 RTStrGetCpEx(&psz, &Cp);
396 return (char *)psz;
397}
398
399/**
400 * Skips back to the previous code point.
401 *
402 * @returns Pointer to the char before the current code point.
403 * @returns pszStart on failure.
404 * @param pszStart Pointer to the start of the string.
405 * @param psz Pointer to the current code point.
406 */
407RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
408
409
410
411#ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
412#define DECLARED_FNRTSTROUTPUT
413/**
414 * Output callback.
415 *
416 * @returns number of bytes written.
417 * @param pvArg User argument.
418 * @param pachChars Pointer to an array of utf-8 characters.
419 * @param cbChars Number of bytes in the character array pointed to by pachChars.
420 */
421typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
422/** Pointer to callback function. */
423typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
424#endif
425
426/** Format flag.
427 * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
428 * that not all flags makes sense to both of the functions.
429 * @{ */
430#define RTSTR_F_CAPITAL 0x0001
431#define RTSTR_F_LEFT 0x0002
432#define RTSTR_F_ZEROPAD 0x0004
433#define RTSTR_F_SPECIAL 0x0008
434#define RTSTR_F_VALSIGNED 0x0010
435#define RTSTR_F_PLUS 0x0020
436#define RTSTR_F_BLANK 0x0040
437#define RTSTR_F_WIDTH 0x0080
438#define RTSTR_F_PRECISION 0x0100
439
440#define RTSTR_F_BIT_MASK 0xf800
441#define RTSTR_F_8BIT 0x0800
442#define RTSTR_F_16BIT 0x1000
443#define RTSTR_F_32BIT 0x2000
444#define RTSTR_F_64BIT 0x4000
445#define RTSTR_F_128BIT 0x8000
446/** @} */
447
448/** @def RTSTR_GET_BIT_FLAG
449 * Gets the bit flag for the specified type.
450 */
451#define RTSTR_GET_BIT_FLAG(type) \
452 ( sizeof(type) == 32 ? RTSTR_F_32BIT \
453 : sizeof(type) == 64 ? RTSTR_F_64BIT \
454 : sizeof(type) == 16 ? RTSTR_F_16BIT \
455 : sizeof(type) == 8 ? RTSTR_F_8BIT \
456 : sizeof(type) == 128? RTSTR_F_128BIT \
457 : 0)
458
459
460/**
461 * Callback to format non-standard format specifiers.
462 *
463 * @returns The number of bytes formatted.
464 * @param pvArg Formatter argument.
465 * @param pfnOutput Pointer to output function.
466 * @param pvArgOutput Argument for the output function.
467 * @param ppszFormat Pointer to the format string pointer. Advance this till the char
468 * after the format specifier.
469 * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
470 * @param cchWidth Format Width. -1 if not specified.
471 * @param cchPrecision Format Precision. -1 if not specified.
472 * @param fFlags Flags (RTSTR_NTFS_*).
473 * @param chArgSize The argument size specifier, 'l' or 'L'.
474 */
475typedef DECLCALLBACK(int) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
476 const char **ppszFormat, va_list *pArgs, int cchWidth, int cchPrecision, unsigned fFlags, char chArgSize);
477/** Pointer to a FNSTRFORMAT() function. */
478typedef FNSTRFORMAT *PFNSTRFORMAT;
479
480
481/**
482 * Partial implementation of a printf like formatter.
483 * It doesn't do everything correct, and there is no floating point support.
484 * However, it supports custom formats by the means of a format callback.
485 *
486 * @returns number of bytes formatted.
487 * @param pfnOutput Output worker.
488 * Called in two ways. Normally with a string and its length.
489 * For termination, it's called with NULL for string, 0 for length.
490 * @param pvArgOutput Argument to the output worker.
491 * @param pfnFormat Custom format worker.
492 * @param pvArgFormat Argument to the format worker.
493 * @param ppszFormat Format string pointer.
494 * @param args Argument list.
495 */
496RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *ppszFormat, va_list args);
497
498/**
499 * Partial implementation of a printf like formatter.
500 * It doesn't do everything correct, and there is no floating point support.
501 * However, it supports custom formats by the means of a format callback.
502 *
503 * @returns number of bytes formatted.
504 * @param pfnOutput Output worker.
505 * Called in two ways. Normally with a string and its length.
506 * For termination, it's called with NULL for string, 0 for length.
507 * @param pvArgOutput Argument to the output worker.
508 * @param pfnFormat Custom format worker.
509 * @param pvArgFormat Argument to the format worker.
510 * @param pszFormat Format string.
511 * @param ... Argument list.
512 */
513RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *pszFormat, ...);
514
515/**
516 * Formats an integer number according to the parameters.
517 *
518 * @returns Length of the formatted number.
519 * @param psz Pointer to output string buffer of sufficient size.
520 * @param u64Value Value to format.
521 * @param uiBase Number representation base.
522 * @param cchWidth Width.
523 * @param cchPrecision Precision.
524 * @param fFlags Flags (NTFS_*).
525 */
526RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision, unsigned int fFlags);
527
528/**
529 * String printf.
530 *
531 * @returns The length of the returned string (in pszBuffer).
532 * @param pszBuffer Output buffer.
533 * @param cchBuffer Size of the output buffer.
534 * @param pszFormat The format string.
535 * @param args The format argument.
536 */
537RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
538
539/**
540 * String printf.
541 *
542 * @returns The length of the returned string (in pszBuffer).
543 * @param pszBuffer Output buffer.
544 * @param cchBuffer Size of the output buffer.
545 * @param pszFormat The format string.
546 * @param ... The format argument.
547 */
548RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
549
550
551/**
552 * String printf with custom formatting.
553 *
554 * @returns The length of the returned string (in pszBuffer).
555 * @param pfnFormat Pointer to handler function for the custom formats.
556 * @param pvArg Argument to the pfnFormat function.
557 * @param pszBuffer Output buffer.
558 * @param cchBuffer Size of the output buffer.
559 * @param pszFormat The format string.
560 * @param args The format argument.
561 */
562RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
563
564/**
565 * String printf with custom formatting.
566 *
567 * @returns The length of the returned string (in pszBuffer).
568 * @param pfnFormat Pointer to handler function for the custom formats.
569 * @param pvArg Argument to the pfnFormat function.
570 * @param pszBuffer Output buffer.
571 * @param cchBuffer Size of the output buffer.
572 * @param pszFormat The format string.
573 * @param ... The format argument.
574 */
575RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
576
577
578/**
579 * Allocating string printf.
580 *
581 * @returns The length of the string in the returned *ppszBuffer.
582 * @returns -1 on failure.
583 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
584 * The buffer should be freed using RTStrFree().
585 * On failure *ppszBuffer will be set to NULL.
586 * @param pszFormat The format string.
587 * @param args The format argument.
588 */
589RTDECL(int) RTStrAPrintfV(char **ppszBuffer, const char *pszFormat, va_list args);
590
591/**
592 * Allocating string printf.
593 *
594 * @returns The length of the string in the returned *ppszBuffer.
595 * @returns -1 on failure.
596 * @param ppszBuffer Where to store the pointer to the allocated output buffer.
597 * The buffer should be freed using RTStrFree().
598 * On failure *ppszBuffer will be set to NULL.
599 * @param pszFormat The format string.
600 * @param ... The format argument.
601 */
602RTDECL(int) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...);
603
604
605/**
606 * Strips blankspaces from both ends of the string.
607 *
608 * @returns Pointer to first non-blank char in the string.
609 * @param psz The string to strip.
610 */
611RTDECL(char *) RTStrStrip(char *psz);
612
613/**
614 * Strips blankspaces from the start of the string.
615 *
616 * @returns Pointer to first non-blank char in the string.
617 * @param psz The string to strip.
618 */
619RTDECL(char *) RTStrStripL(const char *psz);
620
621/**
622 * Strips blankspaces from the end of the string.
623 *
624 * @returns psz.
625 * @param psz The string to strip.
626 */
627RTDECL(char *) RTStrStripR(char *psz);
628
629
630/** @defgroup rt_str_conv String To/From Number Convertions
631 * @ingroup grp_rt_str
632 * @{ */
633
634/**
635 * Converts a string representation of a number to a 64-bit unsigned number.
636 *
637 * @returns iprt status code.
638 * Warnings are used to indicate convertion problems.
639 * @param pszValue Pointer to the string value.
640 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
641 * @param uBase The base of the representation used.
642 * If the function will look for known prefixes before defaulting to 10.
643 * @param pu64 Where to store the converted number. (optional)
644 */
645RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
646
647/**
648 * Converts a string representation of a number to a 64-bit unsigned number.
649 * The base is guessed.
650 *
651 * @returns 64-bit unsigned number on success.
652 * @returns 0 on failure.
653 * @param pszValue Pointer to the string value.
654 */
655RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
656
657/**
658 * Converts a string representation of a number to a 32-bit unsigned number.
659 *
660 * @returns iprt status code.
661 * Warnings are used to indicate convertion problems.
662 * @param pszValue Pointer to the string value.
663 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
664 * @param uBase The base of the representation used.
665 * If the function will look for known prefixes before defaulting to 10.
666 * @param pu32 Where to store the converted number. (optional)
667 */
668RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
669
670/**
671 * Converts a string representation of a number to a 64-bit unsigned number.
672 * The base is guessed.
673 *
674 * @returns 32-bit unsigned number on success.
675 * @returns 0 on failure.
676 * @param pszValue Pointer to the string value.
677 */
678RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
679
680/**
681 * Converts a string representation of a number to a 16-bit unsigned number.
682 *
683 * @returns iprt status code.
684 * Warnings are used to indicate convertion problems.
685 * @param pszValue Pointer to the string value.
686 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
687 * @param uBase The base of the representation used.
688 * If the function will look for known prefixes before defaulting to 10.
689 * @param pu16 Where to store the converted number. (optional)
690 */
691RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
692
693/**
694 * Converts a string representation of a number to a 16-bit unsigned number.
695 * The base is guessed.
696 *
697 * @returns 16-bit unsigned number on success.
698 * @returns 0 on failure.
699 * @param pszValue Pointer to the string value.
700 */
701RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
702
703/**
704 * Converts a string representation of a number to a 8-bit unsigned number.
705 *
706 * @returns iprt status code.
707 * Warnings are used to indicate convertion problems.
708 * @param pszValue Pointer to the string value.
709 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
710 * @param uBase The base of the representation used.
711 * If the function will look for known prefixes before defaulting to 10.
712 * @param pu8 Where to store the converted number. (optional)
713 */
714RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
715
716/**
717 * Converts a string representation of a number to a 8-bit unsigned number.
718 * The base is guessed.
719 *
720 * @returns 8-bit unsigned number on success.
721 * @returns 0 on failure.
722 * @param pszValue Pointer to the string value.
723 */
724RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
725
726/**
727 * Converts a string representation of a number to a 64-bit signed number.
728 *
729 * @returns iprt status code.
730 * Warnings are used to indicate convertion problems.
731 * @param pszValue Pointer to the string value.
732 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
733 * @param uBase The base of the representation used.
734 * If the function will look for known prefixes before defaulting to 10.
735 * @param pi64 Where to store the converted number. (optional)
736 */
737RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
738
739/**
740 * Converts a string representation of a number to a 64-bit signed number.
741 * The base is guessed.
742 *
743 * @returns 64-bit signed number on success.
744 * @returns 0 on failure.
745 * @param pszValue Pointer to the string value.
746 */
747RTDECL(int64_t) RTStrToInt64(const char *pszValue);
748
749/**
750 * Converts a string representation of a number to a 32-bit signed number.
751 *
752 * @returns iprt status code.
753 * Warnings are used to indicate convertion problems.
754 * @param pszValue Pointer to the string value.
755 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
756 * @param uBase The base of the representation used.
757 * If the function will look for known prefixes before defaulting to 10.
758 * @param pi32 Where to store the converted number. (optional)
759 */
760RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
761
762/**
763 * Converts a string representation of a number to a 32-bit signed number.
764 * The base is guessed.
765 *
766 * @returns 32-bit signed number on success.
767 * @returns 0 on failure.
768 * @param pszValue Pointer to the string value.
769 */
770RTDECL(int32_t) RTStrToInt32(const char *pszValue);
771
772/**
773 * Converts a string representation of a number to a 16-bit signed number.
774 *
775 * @returns iprt status code.
776 * Warnings are used to indicate convertion problems.
777 * @param pszValue Pointer to the string value.
778 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
779 * @param uBase The base of the representation used.
780 * If the function will look for known prefixes before defaulting to 10.
781 * @param pi16 Where to store the converted number. (optional)
782 */
783RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
784
785/**
786 * Converts a string representation of a number to a 16-bit signed number.
787 * The base is guessed.
788 *
789 * @returns 16-bit signed number on success.
790 * @returns 0 on failure.
791 * @param pszValue Pointer to the string value.
792 */
793RTDECL(int16_t) RTStrToInt16(const char *pszValue);
794
795/**
796 * Converts a string representation of a number to a 8-bit signed number.
797 *
798 * @returns iprt status code.
799 * Warnings are used to indicate convertion problems.
800 * @param pszValue Pointer to the string value.
801 * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
802 * @param uBase The base of the representation used.
803 * If the function will look for known prefixes before defaulting to 10.
804 * @param pi8 Where to store the converted number. (optional)
805 */
806RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
807
808/**
809 * Converts a string representation of a number to a 8-bit signed number.
810 * The base is guessed.
811 *
812 * @returns 8-bit signed number on success.
813 * @returns 0 on failure.
814 * @param pszValue Pointer to the string value.
815 */
816RTDECL(int8_t) RTStrToInt8(const char *pszValue);
817
818/** @} */
819
820
821/** @defgroup rt_str_space Unique String Space
822 * @ingroup grp_rt_str
823 * @{
824 */
825
826/** Pointer to a string name space container node core. */
827typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
828/** Pointer to a pointer to a string name space container node core. */
829typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
830
831/**
832 * String name space container node core.
833 */
834typedef struct RTSTRSPACECORE
835{
836 /** Hash key. Don't touch. */
837 uint32_t Key;
838 /** Pointer to the left leaf node. Don't touch. */
839 PRTSTRSPACECORE pLeft;
840 /** Pointer to the left rigth node. Don't touch. */
841 PRTSTRSPACECORE pRight;
842 /** Pointer to the list of string with the same key. Don't touch. */
843 PRTSTRSPACECORE pList;
844 /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
845 unsigned char uchHeight;
846 /** The string length. Read only! */
847 size_t cchString;
848 /** Pointer to the string. Read only! */
849 const char * pszString;
850} RTSTRSPACECORE;
851
852/** String space. (Initialize with NULL.) */
853typedef PRTSTRSPACECORE RTSTRSPACE;
854/** Pointer to a string space. */
855typedef PPRTSTRSPACECORE PRTSTRSPACE;
856
857
858/**
859 * Inserts a string into a unique string space.
860 *
861 * @returns true on success.
862 * @returns false if the string collieded with an existing string.
863 * @param pStrSpace The space to insert it into.
864 * @param pStr The string node.
865 */
866RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
867
868/**
869 * Removes a string from a unique string space.
870 *
871 * @returns Pointer to the removed string node.
872 * @returns NULL if the string was not found in the string space.
873 * @param pStrSpace The space to insert it into.
874 * @param pszString The string to remove.
875 */
876RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
877
878/**
879 * Gets a string from a unique string space.
880 *
881 * @returns Pointer to the string node.
882 * @returns NULL if the string was not found in the string space.
883 * @param pStrSpace The space to insert it into.
884 * @param pszString The string to get.
885 */
886RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
887
888/**
889 * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
890 *
891 * @returns 0 on continue.
892 * @returns Non-zero to aborts the operation.
893 * @param pStr The string node
894 * @param pvUser The user specified argument.
895 */
896typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
897/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
898typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
899
900/**
901 * Destroys the string space.
902 * The caller supplies a callback which will be called for each of
903 * the string nodes in for freeing their memory and other resources.
904 *
905 * @returns 0 or what ever non-zero return value pfnCallback returned
906 * when aborting the destruction.
907 * @param pStrSpace The space to insert it into.
908 * @param pfnCallback The callback.
909 * @param pvUser The user argument.
910 */
911RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
912
913/**
914 * Enumerates the string space.
915 * The caller supplies a callback which will be called for each of
916 * the string nodes.
917 *
918 * @returns 0 or what ever non-zero return value pfnCallback returned
919 * when aborting the destruction.
920 * @param pStrSpace The space to insert it into.
921 * @param pfnCallback The callback.
922 * @param pvUser The user argument.
923 */
924RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
925
926/** @} */
927
928
929/** @defgroup rt_str_utf16 UTF-16 String Manipulation
930 * @ingroup grp_rt_str
931 * @{
932 */
933
934/**
935 * Free a UTF-16 string allocated by RTStrUtf8ToUtf16(), RTStrUtf8ToUtf16Ex(),
936 * RTUtf16Dup() or RTUtf16DupEx().
937 *
938 * @returns iprt status code.
939 * @param pwszString The UTF-16 string to free. NULL is accepted.
940 */
941RTDECL(void) RTUtf16Free(PRTUTF16 pwszString);
942
943/**
944 * Allocates a new copy of the specified UTF-16 string.
945 *
946 * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
947 * @returns NULL when out of memory.
948 * @param pwszString UTF-16 string to duplicate.
949 * @remark This function will not make any attempt to validate the encoding.
950 */
951RTDECL(PRTUTF16) RTUtf16Dup(PCRTUTF16 pwszString);
952
953/**
954 * Allocates a new copy of the specified UTF-16 string.
955 *
956 * @returns iprt status code.
957 * @param ppwszString Receives pointer of the allocated UTF-16 string.
958 * The returned pointer must be freed using RTUtf16Free().
959 * @param pwszString UTF-16 string to duplicate.
960 * @param cwcExtra Number of extra RTUTF16 items to allocate.
961 * @remark This function will not make any attempt to validate the encoding.
962 */
963RTDECL(int) RTUtf16DupEx(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra);
964
965/**
966 * Returns the length of a UTF-16 string in UTF-16 characters
967 * without trailing '\\0'.
968 *
969 * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
970 * to get the exact number of code points in the string.
971 *
972 * @returns The number of RTUTF16 items in the string.
973 * @param pwszString Pointer the UTF-16 string.
974 * @remark This function will not make any attempt to validate the encoding.
975 */
976RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
977
978/**
979 * Performs a case sensitive string compare between two UTF-16 strings.
980 *
981 * @returns < 0 if the first string less than the second string.s
982 * @returns 0 if the first string identical to the second string.
983 * @returns > 0 if the first string greater than the second string.
984 * @param pwsz1 First UTF-16 string.
985 * @param pwsz2 Second UTF-16 string.
986 * @remark This function will not make any attempt to validate the encoding.
987 */
988RTDECL(int) RTUtf16Cmp(register PCRTUTF16 pwsz1, register PCRTUTF16 pwsz2);
989
990/**
991 * Performs a case insensitive string compare between two UTF-16 strings.
992 *
993 * This is a simplified compare, as only the simplified lower/upper case folding
994 * specified by the unicode specs are used. It does not consider character pairs
995 * as they are used in some languages, just simple upper & lower case compares.
996 *
997 * @returns < 0 if the first string less than the second string.
998 * @returns 0 if the first string identical to the second string.
999 * @returns > 0 if the first string greater than the second string.
1000 * @param pwsz1 First UTF-16 string.
1001 * @param pwsz2 Second UTF-16 string.
1002 */
1003RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
1004
1005/**
1006 * Performs a case insensitive string compare between two UTF-16 strings
1007 * using the current locale of the process (if applicable).
1008 *
1009 * This differs from RTUtf16ICmp() in that it will try, if a locale with the
1010 * required data is available, to do a correct case-insensitive compare. It
1011 * follows that it is more complex and thereby likely to be more expensive.
1012 *
1013 * @returns < 0 if the first string less than the second string.
1014 * @returns 0 if the first string identical to the second string.
1015 * @returns > 0 if the first string greater than the second string.
1016 * @param pwsz1 First UTF-16 string.
1017 * @param pwsz2 Second UTF-16 string.
1018 */
1019RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
1020
1021/**
1022 * Folds a UTF-16 string to lowercase.
1023 *
1024 * This is a very simple folding; is uses the simple lowercase
1025 * code point, it is not related to any locale just the most common
1026 * lowercase codepoint setup by the unicode specs, and it will not
1027 * create new surrogate pairs or remove existing ones.
1028 *
1029 * @returns Pointer to the passed in string.
1030 * @param pwsz The string to fold.
1031 */
1032RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
1033
1034/**
1035 * Folds a UTF-16 string to uppercase.
1036 *
1037 * This is a very simple folding; is uses the simple uppercase
1038 * code point, it is not related to any locale just the most common
1039 * uppercase codepoint setup by the unicode specs, and it will not
1040 * create new surrogate pairs or remove existing ones.
1041 *
1042 * @returns Pointer to the passed in string.
1043 * @param pwsz The string to fold.
1044 */
1045RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
1046
1047/**
1048 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
1049 *
1050 * @returns iprt status code.
1051 * @param pwszString UTF-16 string to convert.
1052 * @param ppszString Receives pointer of allocated UTF-8 string.
1053 * The returned pointer must be freed using RTStrFree().
1054 */
1055RTDECL(int) RTUtf16ToUtf8(PCRTUTF16 pwszString, char **ppszString);
1056
1057/**
1058 * Translates UTF-16 to UTF-8 using buffer provided by the caller or
1059 * a fittingly sized buffer allocated by the function.
1060 *
1061 * @returns iprt status code.
1062 * @param pwszString The UTF-16 string to convert.
1063 * @param cwcString The number of RTUTF16 items to translation from pwszString.
1064 * The translate will stop when reaching cwcString or the terminator ('\\0').
1065 * Use RTSTR_MAX to translate the entire string.
1066 * @param ppsz If cch is non-zero, this must either be pointing to pointer to
1067 * a buffer of the specified size, or pointer to a NULL pointer.
1068 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
1069 * will be allocated to hold the translated string.
1070 * If a buffer was requirest it must be freed using RTUtf16Free().
1071 * @param cch The buffer size in chars (the type). This includes the terminator.
1072 * @param pcch Where to store the length of the translated string. (Optional)
1073 * This field will be updated even on failure, however the value is only
1074 * specified for the following two error codes. On VERR_BUFFER_OVERFLOW
1075 * and VERR_NO_STR_MEMORY it contains the required buffer space.
1076 */
1077RTDECL(int) RTUtf16ToUtf8Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
1078
1079
1080/**
1081 * Allocates tmp buffer, translates pwszString from UCS-2 to UTF8.
1082 *
1083 * @returns iprt status code.
1084 * @param ppszString Receives pointer of allocated UTF8 string.
1085 * The returned pointer must be freed using RTStrFree().
1086 * @param pwszString UCS-2 string to convert.
1087 * @deprecated Use RTUtf16ToUtf8().
1088 */
1089DECLINLINE(int) RTStrUcs2ToUtf8(char **ppszString, PCRTUCS2 pwszString)
1090{
1091 return RTUtf16ToUtf8(pwszString, ppszString);
1092}
1093
1094/**
1095 * Translates UCS-2 to UTF-8 using buffer provided by the caller or
1096 * a fittingly sized buffer allocated by the function.
1097 *
1098 * @returns iprt status code.
1099 * @param ppszString If cch is not zero, this points to the pointer to the
1100 * buffer where the converted string shall be resulted.
1101 * If cch is zero, this is where the pointer to the allocated
1102 * buffer with the converted string is stored. The allocated
1103 * buffer must be freed by using RTStrFree().
1104 * @param cch Size of the passed in buffer (*ppszString).
1105 * If 0 a fittingly sized buffer is allocated.
1106 * @param pwszString UCS-2 string to convert.
1107 * @deprecated
1108 */
1109DECLINLINE(int) RTStrUcs2ToUtf8Ex(char **ppszString, size_t cch, PCRTUCS2 pwszString)
1110{
1111 return RTUtf16ToUtf8Ex(pwszString, RTSTR_MAX, ppszString, cch, NULL);
1112}
1113
1114/**
1115 * Free a UCS-2 string allocated by RTStrUtf8ToUcs2().
1116 *
1117 * @returns iprt status code.
1118 * @param pwszString Pointer to buffer with unicode string to free.
1119 * NULL is accepted.
1120 * @deprecated
1121 */
1122DECLINLINE(void) RTStrUcs2Free(PRTUCS2 pwszString)
1123{
1124 RTUtf16Free(pwszString);
1125}
1126
1127/**
1128 * Allocates a new copy of the given UCS-2 string.
1129 *
1130 * @returns Pointer to the allocated string copy. Use RTStrUcs2Free() to free it.
1131 * @returns NULL when out of memory.
1132 * @param pwszString UCS-2 string to duplicate.
1133 * @deprecated
1134 */
1135DECLINLINE(PRTUCS2) RTStrUcs2Dup(PCRTUCS2 pwszString)
1136{
1137 return RTUtf16Dup(pwszString);
1138}
1139
1140/**
1141 * Allocates a new copy of the given UCS-2 string.
1142 *
1143 * @returns iprt status code.
1144 * @param ppwszString Receives pointer of the allocated UCS-2 string.
1145 * The returned pointer must be freed using RTStrUcs2Free().
1146 * @param pwszString UCS-2 string to duplicate.
1147 * @deprecated
1148 */
1149DECLINLINE(int) RTStrUcs2DupEx(PRTUCS2 *ppwszString, PCRTUCS2 pwszString)
1150{
1151 return RTUtf16DupEx(ppwszString, pwszString, 0);
1152}
1153
1154/**
1155 * Returns the length of a UCS-2 string in UCS-2 characters
1156 * without trailing '\\0'.
1157 *
1158 * @returns Length of input string in UCS-2 characters.
1159 * @param pwszString Pointer the UCS-2 string.
1160 * @deprecated
1161 */
1162DECLINLINE(size_t) RTStrUcs2Len(PCRTUCS2 pwszString)
1163{
1164 return RTUtf16Len(pwszString);
1165}
1166
1167/**
1168 * Performs a case sensitive string compare between two UCS-2 strings.
1169 *
1170 * @returns < 0 if the first string less than the second string.
1171 * @returns 0 if the first string identical to the second string.
1172 * @returns > 0 if the first string greater than the second string.
1173 * @param pwsz1 First UCS-2 string.
1174 * @param pwsz2 Second UCS-2 string.
1175 * @deprecated
1176 */
1177DECLINLINE(int) RTStrUcs2Cmp(register PCRTUCS2 pwsz1, register PCRTUCS2 pwsz2)
1178{
1179 return RTUtf16Cmp(pwsz1, pwsz2);
1180}
1181
1182
1183/**
1184 * Get the unicode code point at the given string position.
1185 *
1186 * @returns unicode code point.
1187 * @returns RTUNICP_INVALID if the encoding is invalid.
1188 * @param pwsz The string.
1189 *
1190 * @remark This is an internal worker for RTUtf16GetCp().
1191 */
1192RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
1193
1194/**
1195 * Get the unicode code point at the given string position.
1196 *
1197 * @returns iprt status code.
1198 * @param ppwsz Pointer to the string pointer. This will be updated to
1199 * point to the char following the current code point.
1200 * @param pCp Where to store the code point.
1201 * RTUNICP_INVALID is stored here on failure.
1202 *
1203 * @remark This is an internal worker for RTUtf16GetCpEx().
1204 */
1205RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1206
1207/**
1208 * Put the unicode code point at the given string position
1209 * and return the pointer to the char following it.
1210 *
1211 * This function will not consider anything at or following the the
1212 * buffer area pointed to by pwsz. It is therefore not suitable for
1213 * inserting code points into a string, only appending/overwriting.
1214 *
1215 * @returns pointer to the char following the written code point.
1216 * @param pwsz The string.
1217 * @param CodePoint The code point to write.
1218 * This sould not be RTUNICP_INVALID or any other charater
1219 * out of the UTF-16 range.
1220 *
1221 * @remark This is an internal worker for RTUtf16GetCpEx().
1222 */
1223RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
1224
1225/**
1226 * Get the unicode code point at the given string position.
1227 *
1228 * @returns unicode code point.
1229 * @returns RTUNICP_INVALID if the encoding is invalid.
1230 * @param pwsz The string.
1231 *
1232 * @remark We optimize this operation by using an inline function for
1233 * everything which isn't a surrogate pair or an endian indicator.
1234 */
1235DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
1236{
1237 const RTUTF16 wc = *pwsz;
1238 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1239 return wc;
1240 return RTUtf16GetCpInternal(pwsz);
1241}
1242
1243/**
1244 * Get the unicode code point at the given string position.
1245 *
1246 * @returns iprt status code.
1247 * @param ppwsz Pointer to the string pointer. This will be updated to
1248 * point to the char following the current code point.
1249 * @param pCp Where to store the code point.
1250 * RTUNICP_INVALID is stored here on failure.
1251 *
1252 * @remark We optimize this operation by using an inline function for
1253 * everything which isn't a surrogate pair or and endian indicator.
1254 */
1255DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1256{
1257 const RTUTF16 wc = **ppwsz;
1258 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1259 {
1260 (*ppwsz)++;
1261 *pCp = wc;
1262 return VINF_SUCCESS;
1263 }
1264 return RTUtf16GetCpExInternal(ppwsz, pCp);
1265}
1266
1267/**
1268 * Put the unicode code point at the given string position
1269 * and return the pointer to the char following it.
1270 *
1271 * This function will not consider anything at or following the the
1272 * buffer area pointed to by pwsz. It is therefore not suitable for
1273 * inserting code points into a string, only appending/overwriting.
1274 *
1275 * @returns pointer to the char following the written code point.
1276 * @param pwsz The string.
1277 * @param CodePoint The code point to write.
1278 * This sould not be RTUNICP_INVALID or any other charater
1279 * out of the UTF-16 range.
1280 *
1281 * @remark We optimize this operation by using an inline function for
1282 * everything which isn't a surrogate pair or and endian indicator.
1283 */
1284DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
1285{
1286 if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
1287 {
1288 *pwsz++ = (RTUTF16)CodePoint;
1289 return pwsz;
1290 }
1291 return RTUtf16PutCpInternal(pwsz, CodePoint);
1292}
1293
1294/**
1295 * Skips ahead, past the current code point.
1296 *
1297 * @returns Pointer to the char after the current code point.
1298 * @param pwsz Pointer to the current code point.
1299 * @remark This will not move the next valid code point, only past the current one.
1300 */
1301DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
1302{
1303 RTUNICP Cp;
1304 RTUtf16GetCpEx(&pwsz, &Cp);
1305 return (PRTUTF16)pwsz;
1306}
1307
1308/**
1309 * Skips backwards, to the previous code point.
1310 *
1311 * @returns Pointer to the char after the current code point.
1312 * @param pwszStart Pointer to the start of the string.
1313 * @param pwsz Pointer to the current code point.
1314 */
1315RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
1316
1317
1318/**
1319 * Checks if the UTF-16 char is the high surrogate char (i.e.
1320 * the 1st char in the pair).
1321 *
1322 * @returns true if it is.
1323 * @returns false if it isn't.
1324 * @param wc The character to investigate.
1325 */
1326DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
1327{
1328 return wc >= 0xd800 && wc <= 0xdbff;
1329}
1330
1331/**
1332 * Checks if the UTF-16 char is the low surrogate char (i.e.
1333 * the 2nd char in the pair).
1334 *
1335 * @returns true if it is.
1336 * @returns false if it isn't.
1337 * @param wc The character to investigate.
1338 */
1339DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
1340{
1341 return wc >= 0xdc00 && wc <= 0xdfff;
1342}
1343
1344
1345/**
1346 * Checks if the two UTF-16 chars form a valid surrogate pair.
1347 *
1348 * @returns true if they do.
1349 * @returns false if they doesn't.
1350 * @param wcHigh The high (1st) character.
1351 * @param wcLow The low (2nd) character.
1352 */
1353DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
1354{
1355 return RTUtf16IsHighSurrogate(wcHigh)
1356 && RTUtf16IsLowSurrogate(wcLow);
1357}
1358
1359/** @} */
1360
1361__END_DECLS
1362
1363/** @} */
1364
1365#endif
1366
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