VirtualBox

source: vbox/trunk/include/iprt/utf16.h@ 69411

Last change on this file since 69411 was 69105, checked in by vboxsync, 7 years ago

include/iprt/: (C) year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 56.6 KB
Line 
1/** @file
2 * IPRT - String Manipulation, UTF-16 encoding.
3 */
4
5/*
6 * Copyright (C) 2006-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_utf16_h
27#define ___iprt_utf16_h
28
29#include <iprt/string.h>
30
31RT_C_DECLS_BEGIN
32
33
34/** @defgroup rt_str_utf16 UTF-16 String Manipulation
35 * @ingroup grp_rt_str
36 * @{
37 */
38
39/**
40 * Allocates memory for UTF-16 string storage (default tag).
41 *
42 * You should normally not use this function, except if there is some very
43 * custom string handling you need doing that isn't covered by any of the other
44 * APIs.
45 *
46 * @returns Pointer to the allocated UTF-16 string. The first wide char is
47 * always set to the string terminator char, the contents of the
48 * remainder of the memory is undefined. The string must be freed by
49 * calling RTUtf16Free.
50 *
51 * NULL is returned if the allocation failed. Please translate this to
52 * VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY. Also consider
53 * RTUtf16AllocEx if an IPRT status code is required.
54 *
55 * @param cb How many bytes to allocate, will be rounded up
56 * to a multiple of two. If this is zero, we will
57 * allocate a terminator wide char anyway.
58 */
59#define RTUtf16Alloc(cb) RTUtf16AllocTag((cb), RTSTR_TAG)
60
61/**
62 * Allocates memory for UTF-16 string storage (custom tag).
63 *
64 * You should normally not use this function, except if there is some very
65 * custom string handling you need doing that isn't covered by any of the other
66 * APIs.
67 *
68 * @returns Pointer to the allocated UTF-16 string. The first wide char is
69 * always set to the string terminator char, the contents of the
70 * remainder of the memory is undefined. The string must be freed by
71 * calling RTUtf16Free.
72 *
73 * NULL is returned if the allocation failed. Please translate this to
74 * VERR_NO_UTF16_MEMORY and not VERR_NO_MEMORY. Also consider
75 * RTUtf16AllocExTag if an IPRT status code is required.
76 *
77 * @param cb How many bytes to allocate, will be rounded up
78 * to a multiple of two. If this is zero, we will
79 * allocate a terminator wide char anyway.
80 * @param pszTag Allocation tag used for statistics and such.
81 */
82RTDECL(PRTUTF16) RTUtf16AllocTag(size_t cb, const char *pszTag);
83
84/**
85 * Reallocates the specified UTF-16 string (default tag).
86 *
87 * You should normally not use this function, except if there is some very
88 * custom string handling you need doing that isn't covered by any of the other
89 * APIs.
90 *
91 * @returns VINF_SUCCESS.
92 * @retval VERR_NO_UTF16_MEMORY if we failed to reallocate the string, @a
93 * *ppwsz remains unchanged.
94 *
95 * @param ppwsz Pointer to the string variable containing the
96 * input and output string.
97 *
98 * When not freeing the string, the result will
99 * always have the last RTUTF16 set to the
100 * terminator character so that when used for
101 * string truncation the result will be a valid
102 * C-style string (your job to keep it a valid
103 * UTF-16 string).
104 *
105 * When the input string is NULL and we're supposed
106 * to reallocate, the returned string will also
107 * have the first RTUTF16 set to the terminator
108 * char so it will be a valid C-style string.
109 *
110 * @param cbNew When @a cbNew is zero, we'll behave like
111 * RTUtf16Free and @a *ppwsz will be set to NULL.
112 *
113 * When not zero, this will be rounded up to a
114 * multiple of two, and used as the new size of the
115 * memory backing the string, i.e. it includes the
116 * terminator (RTUTF16) char.
117 */
118#define RTUtf16Realloc(ppwsz, cbNew) RTUtf16ReallocTag((ppwsz), (cbNew), RTSTR_TAG)
119
120/**
121 * Reallocates the specified UTF-16 string (custom tag).
122 *
123 * You should normally not use this function, except if there is some very
124 * custom string handling you need doing that isn't covered by any of the other
125 * APIs.
126 *
127 * @returns VINF_SUCCESS.
128 * @retval VERR_NO_UTF16_MEMORY if we failed to reallocate the string, @a
129 * *ppwsz remains unchanged.
130 *
131 * @param ppwsz Pointer to the string variable containing the
132 * input and output string.
133 *
134 * When not freeing the string, the result will
135 * always have the last RTUTF16 set to the
136 * terminator character so that when used for
137 * string truncation the result will be a valid
138 * C-style string (your job to keep it a valid
139 * UTF-16 string).
140 *
141 * When the input string is NULL and we're supposed
142 * to reallocate, the returned string will also
143 * have the first RTUTF16 set to the terminator
144 * char so it will be a valid C-style string.
145 *
146 * @param cbNew When @a cbNew is zero, we'll behave like
147 * RTUtf16Free and @a *ppwsz will be set to NULL.
148 *
149 * When not zero, this will be rounded up to a
150 * multiple of two, and used as the new size of the
151 * memory backing the string, i.e. it includes the
152 * terminator (RTUTF16) char.
153 * @param pszTag Allocation tag used for statistics and such.
154 */
155RTDECL(int) RTUtf16ReallocTag(PRTUTF16 *ppwsz, size_t cbNew, const char *pszTag);
156
157/**
158 * Free a UTF-16 string allocated by RTStrToUtf16(), RTStrToUtf16Ex(),
159 * RTLatin1ToUtf16(), RTLatin1ToUtf16Ex(), RTUtf16Dup() or RTUtf16DupEx().
160 *
161 * @returns iprt status code.
162 * @param pwszString The UTF-16 string to free. NULL is accepted.
163 */
164RTDECL(void) RTUtf16Free(PRTUTF16 pwszString);
165
166/**
167 * Allocates a new copy of the specified UTF-16 string (default tag).
168 *
169 * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
170 * @returns NULL when out of memory.
171 * @param pwszString UTF-16 string to duplicate.
172 * @remark This function will not make any attempt to validate the encoding.
173 */
174#define RTUtf16Dup(pwszString) RTUtf16DupTag((pwszString), RTSTR_TAG)
175
176/**
177 * Allocates a new copy of the specified UTF-16 string (custom tag).
178 *
179 * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
180 * @returns NULL when out of memory.
181 * @param pwszString UTF-16 string to duplicate.
182 * @param pszTag Allocation tag used for statistics and such.
183 * @remark This function will not make any attempt to validate the encoding.
184 */
185RTDECL(PRTUTF16) RTUtf16DupTag(PCRTUTF16 pwszString, const char *pszTag);
186
187/**
188 * Allocates a new copy of the specified UTF-16 string (default tag).
189 *
190 * @returns iprt status code.
191 * @param ppwszString Receives pointer of the allocated UTF-16 string.
192 * The returned pointer must be freed using RTUtf16Free().
193 * @param pwszString UTF-16 string to duplicate.
194 * @param cwcExtra Number of extra RTUTF16 items to allocate.
195 * @remark This function will not make any attempt to validate the encoding.
196 */
197#define RTUtf16DupEx(ppwszString, pwszString, cwcExtra) \
198 RTUtf16DupExTag((ppwszString), (pwszString), (cwcExtra), RTSTR_TAG)
199
200/**
201 * Allocates a new copy of the specified UTF-16 string (custom tag).
202 *
203 * @returns iprt status code.
204 * @param ppwszString Receives pointer of the allocated UTF-16 string.
205 * The returned pointer must be freed using RTUtf16Free().
206 * @param pwszString UTF-16 string to duplicate.
207 * @param cwcExtra Number of extra RTUTF16 items to allocate.
208 * @param pszTag Allocation tag used for statistics and such.
209 * @remark This function will not make any attempt to validate the encoding.
210 */
211RTDECL(int) RTUtf16DupExTag(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra, const char *pszTag);
212
213/**
214 * Returns the length of a UTF-16 string in UTF-16 characters
215 * without trailing '\\0'.
216 *
217 * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
218 * to get the exact number of code points in the string.
219 *
220 * @returns The number of RTUTF16 items in the string.
221 * @param pwszString Pointer the UTF-16 string.
222 * @remark This function will not make any attempt to validate the encoding.
223 */
224RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
225
226/**
227 * Find the length of a zero-terminated byte string, given a max string length.
228 *
229 * @returns The string length or cbMax. The returned length does not include
230 * the zero terminator if it was found.
231 *
232 * @param pwszString The string.
233 * @param cwcMax The max string length in RTUTF16s.
234 * @sa RTUtf16NLenEx, RTStrNLen.
235 */
236RTDECL(size_t) RTUtf16NLen(PCRTUTF16 pwszString, size_t cwcMax);
237
238/**
239 * Find the length of a zero-terminated byte string, given
240 * a max string length.
241 *
242 * @returns IPRT status code.
243 * @retval VINF_SUCCESS if the string has a length less than cchMax.
244 * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
245 * before cwcMax was reached.
246 *
247 * @param pwszString The string.
248 * @param cwcMax The max string length in RTUTF16s.
249 * @param pcwc Where to store the string length excluding the
250 * terminator. This is set to cwcMax if the terminator
251 * isn't found.
252 * @sa RTUtf16NLen, RTStrNLenEx.
253 */
254RTDECL(int) RTUtf16NLenEx(PCRTUTF16 pwszString, size_t cwcMax, size_t *pcwc);
255
256/**
257 * Find the zero terminator in a string with a limited length.
258 *
259 * @returns Pointer to the zero terminator.
260 * @returns NULL if the zero terminator was not found.
261 *
262 * @param pwszString The string.
263 * @param cwcMax The max string length. RTSTR_MAX is fine.
264 */
265RTDECL(PCRTUTF16) RTUtf16End(PCRTUTF16 pwszString, size_t cwcMax);
266
267/**
268 * Strips blankspaces from both ends of the string.
269 *
270 * @returns Pointer to first non-blank char in the string.
271 * @param pwsz The string to strip.
272 */
273RTDECL(PRTUTF16) RTUtf16Strip(PRTUTF16 pwsz);
274
275/**
276 * Strips blankspaces from the start of the string.
277 *
278 * @returns Pointer to first non-blank char in the string.
279 * @param pwsz The string to strip.
280 */
281RTDECL(PRTUTF16) RTUtf16StripL(PCRTUTF16 pwsz);
282
283/**
284 * Strips blankspaces from the end of the string.
285 *
286 * @returns pwsz.
287 * @param pwsz The string to strip.
288 */
289RTDECL(PRTUTF16) RTUtf16StripR(PRTUTF16 pwsz);
290
291/**
292 * String copy with overflow handling.
293 *
294 * @retval VINF_SUCCESS on success.
295 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
296 * buffer will contain as much of the string as it can hold, fully
297 * terminated.
298 *
299 * @param pwszDst The destination buffer.
300 * @param cwcDst The size of the destination buffer in RTUTF16s.
301 * @param pwszSrc The source string. NULL is not OK.
302 */
303RTDECL(int) RTUtf16Copy(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
304
305/**
306 * String copy with overflow handling, ASCII source.
307 *
308 * @retval VINF_SUCCESS on success.
309 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
310 * buffer will contain as much of the string as it can hold, fully
311 * terminated.
312 *
313 * @param pwszDst The destination buffer.
314 * @param cwcDst The size of the destination buffer in RTUTF16s.
315 * @param pszSrc The source string, pure ASCII. NULL is not OK.
316 */
317RTDECL(int) RTUtf16CopyAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
318
319/**
320 * String copy with overflow handling.
321 *
322 * @retval VINF_SUCCESS on success.
323 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
324 * buffer will contain as much of the string as it can hold, fully
325 * terminated.
326 *
327 * @param pwszDst The destination buffer.
328 * @param cwcDst The size of the destination buffer in RTUTF16s.
329 * @param pwszSrc The source string. NULL is not OK.
330 * @param cwcSrcMax The maximum number of chars (not code points) to
331 * copy from the source string, not counting the
332 * terminator as usual.
333 */
334RTDECL(int) RTUtf16CopyEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
335
336/**
337 * String concatenation with overflow handling.
338 *
339 * @retval VINF_SUCCESS on success.
340 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
341 * buffer will contain as much of the string as it can hold, fully
342 * terminated.
343 *
344 * @param pwszDst The destination buffer.
345 * @param cwcDst The size of the destination buffer in RTUTF16s.
346 * @param pwszSrc The source string. NULL is not OK.
347 */
348RTDECL(int) RTUtf16Cat(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc);
349
350/**
351 * String concatenation with overflow handling, ASCII source.
352 *
353 * @retval VINF_SUCCESS on success.
354 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
355 * buffer will contain as much of the string as it can hold, fully
356 * terminated.
357 *
358 * @param pwszDst The destination buffer.
359 * @param cwcDst The size of the destination buffer in RTUTF16s.
360 * @param pszSrc The source string, pure ASCII. NULL is not OK.
361 */
362RTDECL(int) RTUtf16CatAscii(PRTUTF16 pwszDst, size_t cwcDst, const char *pszSrc);
363
364/**
365 * String concatenation with overflow handling.
366 *
367 * @retval VINF_SUCCESS on success.
368 * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
369 * buffer will contain as much of the string as it can hold, fully
370 * terminated.
371 *
372 * @param pwszDst The destination buffer.
373 * @param cwcDst The size of the destination buffer in RTUTF16s.
374 * @param pwszSrc The source string. NULL is not OK.
375 * @param cwcSrcMax The maximum number of UTF-16 chars (not code
376 * points) to copy from the source string, not
377 * counting the terminator as usual.
378 */
379RTDECL(int) RTUtf16CatEx(PRTUTF16 pwszDst, size_t cwcDst, PCRTUTF16 pwszSrc, size_t cwcSrcMax);
380
381/**
382 * Performs a case sensitive string compare between two UTF-16 strings.
383 *
384 * @returns < 0 if the first string less than the second string.s
385 * @returns 0 if the first string identical to the second string.
386 * @returns > 0 if the first string greater than the second string.
387 * @param pwsz1 First UTF-16 string. Null is allowed.
388 * @param pwsz2 Second UTF-16 string. Null is allowed.
389 * @remark This function will not make any attempt to validate the encoding.
390 */
391RTDECL(int) RTUtf16Cmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
392
393/**
394 * Performs a case sensitive string compare between an UTF-16 string and a pure
395 * ASCII string.
396 *
397 * @returns < 0 if the first string less than the second string.s
398 * @returns 0 if the first string identical to the second string.
399 * @returns > 0 if the first string greater than the second string.
400 * @param pwsz1 First UTF-16 string. Null is allowed.
401 * @param psz2 Second string, pure ASCII. Null is allowed.
402 * @remark This function will not make any attempt to validate the encoding.
403 */
404RTDECL(int) RTUtf16CmpAscii(PCRTUTF16 pwsz1, const char *psz2);
405
406/**
407 * Performs a case sensitive string compare between an UTF-16 string and a UTF-8
408 * string.
409 *
410 * @returns < 0 if the first string less than the second string.s
411 * @returns 0 if the first string identical to the second string.
412 * @returns > 0 if the first string greater than the second string.
413 * @param pwsz1 First UTF-16 string. Null is allowed.
414 * @param psz2 Second string, UTF-8. Null is allowed.
415 * @remarks NULL and empty strings are treated equally.
416 */
417RTDECL(int) RTUtf16CmpUtf8(PCRTUTF16 pwsz1, const char *psz2);
418
419/**
420 * Performs a case insensitive string compare between two UTF-16 strings.
421 *
422 * This is a simplified compare, as only the simplified lower/upper case folding
423 * specified by the unicode specs are used. It does not consider character pairs
424 * as they are used in some languages, just simple upper & lower case compares.
425 *
426 * @returns < 0 if the first string less than the second string.
427 * @returns 0 if the first string identical to the second string.
428 * @returns > 0 if the first string greater than the second string.
429 * @param pwsz1 First UTF-16 string. Null is allowed.
430 * @param pwsz2 Second UTF-16 string. Null is allowed.
431 */
432RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
433
434/**
435 * Performs a case insensitive string compare between two big endian UTF-16
436 * strings.
437 *
438 * This is a simplified compare, as only the simplified lower/upper case folding
439 * specified by the unicode specs are used. It does not consider character pairs
440 * as they are used in some languages, just simple upper & lower case compares.
441 *
442 * @returns < 0 if the first string less than the second string.
443 * @returns 0 if the first string identical to the second string.
444 * @returns > 0 if the first string greater than the second string.
445 * @param pwsz1 First big endian UTF-16 string. Null is allowed.
446 * @param pwsz2 Second big endian UTF-16 string. Null is allowed.
447 */
448RTDECL(int) RTUtf16BigICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
449
450/**
451 * Performs a case insensitive string compare between an UTF-16 string and a
452 * UTF-8 string.
453 *
454 * @returns < 0 if the first string less than the second string.s
455 * @returns 0 if the first string identical to the second string.
456 * @returns > 0 if the first string greater than the second string.
457 * @param pwsz1 First UTF-16 string. Null is allowed.
458 * @param psz2 Second string, UTF-8. Null is allowed.
459 * @remarks NULL and empty strings are treated equally.
460 */
461RTDECL(int) RTUtf16ICmpUtf8(PCRTUTF16 pwsz1, const char *psz2);
462
463/**
464 * Performs a case insensitive string compare between an UTF-16 string and a
465 * pure ASCII string.
466 *
467 * Since this compare only takes cares about the first 128 codepoints in
468 * unicode, no tables are needed and there aren't any real complications.
469 *
470 * @returns < 0 if the first string less than the second string.
471 * @returns 0 if the first string identical to the second string.
472 * @returns > 0 if the first string greater than the second string.
473 * @param pwsz1 First UTF-16 string. Null is allowed.
474 * @param psz2 Second string, pure ASCII. Null is allowed.
475 */
476RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1, const char *psz2);
477
478/**
479 * Performs a case insensitive string compare between two UTF-16 strings
480 * using the current locale of the process (if applicable).
481 *
482 * This differs from RTUtf16ICmp() in that it will try, if a locale with the
483 * required data is available, to do a correct case-insensitive compare. It
484 * follows that it is more complex and thereby likely to be more expensive.
485 *
486 * @returns < 0 if the first string less than the second string.
487 * @returns 0 if the first string identical to the second string.
488 * @returns > 0 if the first string greater than the second string.
489 * @param pwsz1 First UTF-16 string. Null is allowed.
490 * @param pwsz2 Second UTF-16 string. Null is allowed.
491 */
492RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
493
494/**
495 * Performs a case insensitive string compare between two UTF-16 strings,
496 * stopping after N characters.
497 *
498 * This is a simplified compare, as only the simplified lower/upper case folding
499 * specified by the unicode specs are used. It does not consider character pairs
500 * as they are used in some languages, just simple upper & lower case compares.
501 *
502 * @returns < 0 if the first string less than the second string.
503 * @returns 0 if the first string identical to the second string.
504 * @returns > 0 if the first string greater than the second string.
505 * @param pwsz1 First UTF-16 string. Null is allowed.
506 * @param pwsz2 Second UTF-16 string. Null is allowed.
507 * @param cwcMax Maximum number of characters to compare.
508 */
509RTDECL(int) RTUtf16NICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2, size_t cwcMax);
510
511/**
512 * Performs a case insensitive string compare between two big endian UTF-16
513 * strings, stopping after N characters.
514 *
515 * This is a simplified compare, as only the simplified lower/upper case folding
516 * specified by the unicode specs are used. It does not consider character pairs
517 * as they are used in some languages, just simple upper & lower case compares.
518 *
519 * @returns < 0 if the first string less than the second string.
520 * @returns 0 if the first string identical to the second string.
521 * @returns > 0 if the first string greater than the second string.
522 * @param pwsz1 First big endian UTF-16 string. Null is allowed.
523 * @param pwsz2 Second big endian UTF-16 string. Null is allowed.
524 * @param cwcMax Maximum number of characters to compare.
525 */
526RTDECL(int) RTUtf16BigNICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2, size_t cwcMax);
527
528/**
529 * Performs a case insensitive string compare between a UTF-16 string and a pure
530 * ASCII string, stopping after N characters.
531 *
532 * Since this compare only takes cares about the first 128 codepoints in
533 * unicode, no tables are needed and there aren't any real complications.
534 *
535 * @returns < 0 if the first string less than the second string.
536 * @returns 0 if the first string identical to the second string.
537 * @returns > 0 if the first string greater than the second string.
538 * @param pwsz1 The UTF-16 first string. Null is allowed.
539 * @param psz2 The pure ASCII second string. Null is allowed.
540 * @param cwcMax Maximum number of UTF-16 characters to compare.
541 */
542RTDECL(int) RTUtf16NICmpAscii(PCRTUTF16 pwsz1, const char *psz2, size_t cwcMax);
543
544
545/**
546 * Folds a UTF-16 string to lowercase.
547 *
548 * This is a very simple folding; is uses the simple lowercase
549 * code point, it is not related to any locale just the most common
550 * lowercase codepoint setup by the unicode specs, and it will not
551 * create new surrogate pairs or remove existing ones.
552 *
553 * @returns Pointer to the passed in string.
554 * @param pwsz The string to fold.
555 */
556RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
557
558/**
559 * Folds a UTF-16 string to uppercase.
560 *
561 * This is a very simple folding; is uses the simple uppercase
562 * code point, it is not related to any locale just the most common
563 * uppercase codepoint setup by the unicode specs, and it will not
564 * create new surrogate pairs or remove existing ones.
565 *
566 * @returns Pointer to the passed in string.
567 * @param pwsz The string to fold.
568 */
569RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
570
571/**
572 * Validates the UTF-16 encoding of the string.
573 *
574 * @returns iprt status code.
575 * @param pwsz The string.
576 */
577RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz);
578
579/**
580 * Validates the UTF-16 encoding of the string.
581 *
582 * @returns iprt status code.
583 * @param pwsz The string.
584 * @param cwc The max string length (/ size) in UTF-16 units. Use
585 * RTSTR_MAX to process the entire string.
586 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
587 */
588RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz, size_t cwc, uint32_t fFlags);
589
590/**
591 * Checks if the UTF-16 encoding is valid.
592 *
593 * @returns true / false.
594 * @param pwsz The string.
595 */
596RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz);
597
598/**
599 * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
600 * list in-place by an ASCII replacement character.
601 *
602 * Surrogate paris will be replaced by two chars.
603 *
604 * @returns The number of code points replaced. In the case of an incorrectly
605 * encoded string -1 will be returned, and the string is not completely
606 * processed. In the case of puszValidPairs having an odd number of
607 * code points, -1 will be also return but without any modification to
608 * the string.
609 * @param pwsz The string to sanitise.
610 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
611 * Each pair is the start and end point of a range,
612 * and the union of these ranges forms the white list.
613 * @param chReplacement The ASCII replacement character.
614 * @sa RTStrPurgeComplementSet
615 */
616RTDECL(ssize_t) RTUtf16PurgeComplementSet(PRTUTF16 pwsz, PCRTUNICP puszValidPairs, char chReplacement);
617
618
619/**
620 * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
621 * tag).
622 *
623 * @returns iprt status code.
624 * @param pwszString UTF-16 string to convert.
625 * @param ppszString Receives pointer of allocated UTF-8 string on
626 * success, and is always set to NULL on failure.
627 * The returned pointer must be freed using RTStrFree().
628 */
629#define RTUtf16ToUtf8(pwszString, ppszString) RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
630
631/**
632 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
633 *
634 * @returns iprt status code.
635 * @param pwszString UTF-16 string to convert.
636 * @param ppszString Receives pointer of allocated UTF-8 string on
637 * success, and is always set to NULL on failure.
638 * The returned pointer must be freed using RTStrFree().
639 * @param pszTag Allocation tag used for statistics and such.
640 */
641RTDECL(int) RTUtf16ToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
642
643/**
644 * Translate a UTF-16BE string into a UTF-8 allocating the result buffer
645 * (default tag).
646 *
647 * This differs from RTUtf16ToUtf8 in that the input is always a
648 * big-endian string.
649 *
650 * @returns iprt status code.
651 * @param pwszString UTF-16BE string to convert.
652 * @param ppszString Receives pointer of allocated UTF-8 string on
653 * success, and is always set to NULL on failure.
654 * The returned pointer must be freed using RTStrFree().
655 */
656#define RTUtf16BigToUtf8(pwszString, ppszString) RTUtf16BigToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
657
658/**
659 * Translate a UTF-16BE string into a UTF-8 allocating the result buffer.
660 *
661 * This differs from RTUtf16ToUtf8Tag in that the input is always a
662 * big-endian string.
663 *
664 * @returns iprt status code.
665 * @param pwszString UTF-16BE string to convert.
666 * @param ppszString Receives pointer of allocated UTF-8 string on
667 * success, and is always set to NULL on failure.
668 * The returned pointer must be freed using RTStrFree().
669 * @param pszTag Allocation tag used for statistics and such.
670 */
671RTDECL(int) RTUtf16BigToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
672
673/**
674 * Translate a UTF-16LE string into a UTF-8 allocating the result buffer
675 * (default tag).
676 *
677 * This differs from RTUtf16ToUtf8 in that the input is always a
678 * little-endian string.
679 *
680 * @returns iprt status code.
681 * @param pwszString UTF-16LE string to convert.
682 * @param ppszString Receives pointer of allocated UTF-8 string on
683 * success, and is always set to NULL on failure.
684 * The returned pointer must be freed using RTStrFree().
685 */
686#define RTUtf16LittleToUtf8(pwszString, ppszString) RTUtf16LittleToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
687
688/**
689 * Translate a UTF-16LE string into a UTF-8 allocating the result buffer.
690 *
691 * This differs from RTUtf16ToUtf8Tag in that the input is always a
692 * little-endian string.
693 *
694 * @returns iprt status code.
695 * @param pwszString UTF-16LE string to convert.
696 * @param ppszString Receives pointer of allocated UTF-8 string on
697 * success, and is always set to NULL on failure.
698 * The returned pointer must be freed using RTStrFree().
699 * @param pszTag Allocation tag used for statistics and such.
700 */
701RTDECL(int) RTUtf16LittleToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
702
703
704/**
705 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
706 * sized buffer allocated by the function (default tag).
707 *
708 * @returns iprt status code.
709 * @param pwszString The UTF-16 string to convert.
710 * @param cwcString The number of RTUTF16 items to translate from pwszString.
711 * The translation will stop when reaching cwcString or the terminator ('\\0').
712 * Use RTSTR_MAX to translate the entire string.
713 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
714 * a buffer of the specified size, or pointer to a NULL pointer.
715 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
716 * will be allocated to hold the translated string.
717 * If a buffer was requested it must be freed using RTStrFree().
718 * @param cch The buffer size in chars (the type). This includes the terminator.
719 * @param pcch Where to store the length of the translated string,
720 * excluding the terminator. (Optional)
721 *
722 * This may be set under some error conditions,
723 * however, only for VERR_BUFFER_OVERFLOW and
724 * VERR_NO_STR_MEMORY will it contain a valid string
725 * length that can be used to resize the buffer.
726 */
727#define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
728 RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
729
730/**
731 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
732 * sized buffer allocated by the function (custom tag).
733 *
734 * @returns iprt status code.
735 * @param pwszString The UTF-16 string to convert.
736 * @param cwcString The number of RTUTF16 items to translate from pwszString.
737 * The translation will stop when reaching cwcString or the terminator ('\\0').
738 * Use RTSTR_MAX to translate the entire string.
739 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
740 * a buffer of the specified size, or pointer to a NULL pointer.
741 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
742 * will be allocated to hold the translated string.
743 * If a buffer was requested it must be freed using RTStrFree().
744 * @param cch The buffer size in chars (the type). This includes the terminator.
745 * @param pcch Where to store the length of the translated string,
746 * excluding the terminator. (Optional)
747 *
748 * This may be set under some error conditions,
749 * however, only for VERR_BUFFER_OVERFLOW and
750 * VERR_NO_STR_MEMORY will it contain a valid string
751 * length that can be used to resize the buffer.
752 * @param pszTag Allocation tag used for statistics and such.
753 */
754RTDECL(int) RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
755
756/**
757 * Translates UTF-16BE to UTF-8 using buffer provided by the caller or a
758 * fittingly sized buffer allocated by the function (default tag).
759 *
760 * This differs from RTUtf16ToUtf8Ex in that the input is always a
761 * big-endian string.
762 *
763 * @returns iprt status code.
764 * @param pwszString The UTF-16BE string to convert.
765 * @param cwcString The number of RTUTF16 items to translate from pwszString.
766 * The translation will stop when reaching cwcString or the terminator ('\\0').
767 * Use RTSTR_MAX to translate the entire string.
768 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
769 * a buffer of the specified size, or pointer to a NULL pointer.
770 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
771 * will be allocated to hold the translated string.
772 * If a buffer was requested it must be freed using RTStrFree().
773 * @param cch The buffer size in chars (the type). This includes the terminator.
774 * @param pcch Where to store the length of the translated string,
775 * excluding the terminator. (Optional)
776 *
777 * This may be set under some error conditions,
778 * however, only for VERR_BUFFER_OVERFLOW and
779 * VERR_NO_STR_MEMORY will it contain a valid string
780 * length that can be used to resize the buffer.
781 */
782#define RTUtf16BigToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
783 RTUtf16BigToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
784
785/**
786 * Translates UTF-16BE to UTF-8 using buffer provided by the caller or a
787 * fittingly sized buffer allocated by the function (custom tag).
788 *
789 * This differs from RTUtf16ToUtf8ExTag in that the input is always a
790 * big-endian string.
791 *
792 * @returns iprt status code.
793 * @param pwszString The UTF-16BE string to convert.
794 * @param cwcString The number of RTUTF16 items to translate from pwszString.
795 * The translation will stop when reaching cwcString or the terminator ('\\0').
796 * Use RTSTR_MAX to translate the entire string.
797 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
798 * a buffer of the specified size, or pointer to a NULL pointer.
799 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
800 * will be allocated to hold the translated string.
801 * If a buffer was requested it must be freed using RTStrFree().
802 * @param cch The buffer size in chars (the type). This includes the terminator.
803 * @param pcch Where to store the length of the translated string,
804 * excluding the terminator. (Optional)
805 *
806 * This may be set under some error conditions,
807 * however, only for VERR_BUFFER_OVERFLOW and
808 * VERR_NO_STR_MEMORY will it contain a valid string
809 * length that can be used to resize the buffer.
810 * @param pszTag Allocation tag used for statistics and such.
811 */
812RTDECL(int) RTUtf16BigToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
813
814/**
815 * Translates UTF-16LE to UTF-8 using buffer provided by the caller or a
816 * fittingly sized buffer allocated by the function (default tag).
817 *
818 * This differs from RTUtf16ToUtf8Ex in that the input is always a
819 * little-endian string.
820 *
821 * @returns iprt status code.
822 * @param pwszString The UTF-16LE string to convert.
823 * @param cwcString The number of RTUTF16 items to translate from pwszString.
824 * The translation will stop when reaching cwcString or the terminator ('\\0').
825 * Use RTSTR_MAX to translate the entire string.
826 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
827 * a buffer of the specified size, or pointer to a NULL pointer.
828 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
829 * will be allocated to hold the translated string.
830 * If a buffer was requested it must be freed using RTStrFree().
831 * @param cch The buffer size in chars (the type). This includes the terminator.
832 * @param pcch Where to store the length of the translated string,
833 * excluding the terminator. (Optional)
834 *
835 * This may be set under some error conditions,
836 * however, only for VERR_BUFFER_OVERFLOW and
837 * VERR_NO_STR_MEMORY will it contain a valid string
838 * length that can be used to resize the buffer.
839 */
840#define RTUtf16LittleToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
841 RTUtf16LittleToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
842
843/**
844 * Translates UTF-16LE to UTF-8 using buffer provided by the caller or a
845 * fittingly sized buffer allocated by the function (custom tag).
846 *
847 * This differs from RTUtf16ToUtf8ExTag in that the input is always a
848 * little-endian string.
849 *
850 * @returns iprt status code.
851 * @param pwszString The UTF-16LE string to convert.
852 * @param cwcString The number of RTUTF16 items to translate from pwszString.
853 * The translation will stop when reaching cwcString or the terminator ('\\0').
854 * Use RTSTR_MAX to translate the entire string.
855 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
856 * a buffer of the specified size, or pointer to a NULL pointer.
857 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
858 * will be allocated to hold the translated string.
859 * If a buffer was requested it must be freed using RTStrFree().
860 * @param cch The buffer size in chars (the type). This includes the terminator.
861 * @param pcch Where to store the length of the translated string,
862 * excluding the terminator. (Optional)
863 *
864 * This may be set under some error conditions,
865 * however, only for VERR_BUFFER_OVERFLOW and
866 * VERR_NO_STR_MEMORY will it contain a valid string
867 * length that can be used to resize the buffer.
868 * @param pszTag Allocation tag used for statistics and such.
869 */
870RTDECL(int) RTUtf16LittleToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch,
871 const char *pszTag);
872
873/**
874 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
875 *
876 * This function will validate the string, and incorrectly encoded UTF-16
877 * strings will be rejected. The primary purpose of this function is to
878 * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
879 * other purposes RTUtf16ToUtf8Ex() should be used.
880 *
881 * @returns Number of char (bytes).
882 * @returns 0 if the string was incorrectly encoded.
883 * @param pwsz The UTF-16 string.
884 */
885RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
886
887/**
888 * Calculates the length of the UTF-16BE string in UTF-8 chars (bytes).
889 *
890 * This function will validate the string, and incorrectly encoded UTF-16BE
891 * strings will be rejected. The primary purpose of this function is to
892 * help allocate buffers for RTUtf16BigToUtf8() of the correct size. For most
893 * other purposes RTUtf16BigToUtf8Ex() should be used.
894 *
895 * @returns Number of char (bytes).
896 * @returns 0 if the string was incorrectly encoded.
897 * @param pwsz The UTF-16BE string.
898 */
899RTDECL(size_t) RTUtf16BigCalcUtf8Len(PCRTUTF16 pwsz);
900
901/**
902 * Calculates the length of the UTF-16LE string in UTF-8 chars (bytes).
903 *
904 * This function will validate the string, and incorrectly encoded UTF-16LE
905 * strings will be rejected. The primary purpose of this function is to
906 * help allocate buffers for RTUtf16LittleToUtf8() of the correct size. For
907 * most other purposes RTUtf16LittleToUtf8Ex() should be used.
908 *
909 * @returns Number of char (bytes).
910 * @returns 0 if the string was incorrectly encoded.
911 * @param pwsz The UTF-16LE string.
912 */
913RTDECL(size_t) RTUtf16LittleCalcUtf8Len(PCRTUTF16 pwsz);
914
915/**
916 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
917 *
918 * This function will validate the string, and incorrectly encoded UTF-16
919 * strings will be rejected.
920 *
921 * @returns iprt status code.
922 * @param pwsz The string.
923 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
924 * @param pcch Where to store the string length (in bytes). Optional.
925 * This is undefined on failure.
926 */
927RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
928
929/**
930 * Calculates the length of the UTF-16BE string in UTF-8 chars (bytes).
931 *
932 * This function will validate the string, and incorrectly encoded UTF-16BE
933 * strings will be rejected.
934 *
935 * @returns iprt status code.
936 * @param pwsz The string.
937 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
938 * @param pcch Where to store the string length (in bytes). Optional.
939 * This is undefined on failure.
940 */
941RTDECL(int) RTUtf16BigCalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
942
943/**
944 * Calculates the length of the UTF-16LE string in UTF-8 chars (bytes).
945 *
946 * This function will validate the string, and incorrectly encoded UTF-16LE
947 * strings will be rejected.
948 *
949 * @returns iprt status code.
950 * @param pwsz The string.
951 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
952 * @param pcch Where to store the string length (in bytes). Optional.
953 * This is undefined on failure.
954 */
955RTDECL(int) RTUtf16LittleCalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
956
957/**
958 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
959 * buffer (default tag).
960 *
961 * @returns iprt status code.
962 * @param pwszString UTF-16 string to convert.
963 * @param ppszString Receives pointer of allocated Latin1 string on
964 * success, and is always set to NULL on failure.
965 * The returned pointer must be freed using RTStrFree().
966 */
967#define RTUtf16ToLatin1(pwszString, ppszString) RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
968
969/**
970 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
971 * buffer (custom tag).
972 *
973 * @returns iprt status code.
974 * @param pwszString UTF-16 string to convert.
975 * @param ppszString Receives pointer of allocated Latin1 string on
976 * success, and is always set to NULL on failure.
977 * The returned pointer must be freed using RTStrFree().
978 * @param pszTag Allocation tag used for statistics and such.
979 */
980RTDECL(int) RTUtf16ToLatin1Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
981
982/**
983 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
984 * or a fittingly sized buffer allocated by the function (default tag).
985 *
986 * @returns iprt status code.
987 * @param pwszString The UTF-16 string to convert.
988 * @param cwcString The number of RTUTF16 items to translate from
989 * pwszString. The translation will stop when reaching
990 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
991 * to translate the entire string.
992 * @param ppsz Pointer to the pointer to the Latin-1 string. The
993 * buffer can optionally be preallocated by the caller.
994 *
995 * If cch is zero, *ppsz is undefined.
996 *
997 * If cch is non-zero and *ppsz is not NULL, then this
998 * will be used as the output buffer.
999 * VERR_BUFFER_OVERFLOW will be returned if this is
1000 * insufficient.
1001 *
1002 * If cch is zero or *ppsz is NULL, then a buffer of
1003 * sufficient size is allocated. cch can be used to
1004 * specify a minimum size of this buffer. Use
1005 * RTUtf16Free() to free the result.
1006 *
1007 * @param cch The buffer size in chars (the type). This includes
1008 * the terminator.
1009 * @param pcch Where to store the length of the translated string,
1010 * excluding the terminator. (Optional)
1011 *
1012 * This may be set under some error conditions,
1013 * however, only for VERR_BUFFER_OVERFLOW and
1014 * VERR_NO_STR_MEMORY will it contain a valid string
1015 * length that can be used to resize the buffer.
1016 */
1017#define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
1018 RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
1019
1020/**
1021 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
1022 * or a fittingly sized buffer allocated by the function (custom tag).
1023 *
1024 * @returns iprt status code.
1025 * @param pwszString The UTF-16 string to convert.
1026 * @param cwcString The number of RTUTF16 items to translate from
1027 * pwszString. The translation will stop when reaching
1028 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
1029 * to translate the entire string.
1030 * @param ppsz Pointer to the pointer to the Latin-1 string. The
1031 * buffer can optionally be preallocated by the caller.
1032 *
1033 * If cch is zero, *ppsz is undefined.
1034 *
1035 * If cch is non-zero and *ppsz is not NULL, then this
1036 * will be used as the output buffer.
1037 * VERR_BUFFER_OVERFLOW will be returned if this is
1038 * insufficient.
1039 *
1040 * If cch is zero or *ppsz is NULL, then a buffer of
1041 * sufficient size is allocated. cch can be used to
1042 * specify a minimum size of this buffer. Use
1043 * RTUtf16Free() to free the result.
1044 *
1045 * @param cch The buffer size in chars (the type). This includes
1046 * the terminator.
1047 * @param pcch Where to store the length of the translated string,
1048 * excluding the terminator. (Optional)
1049 *
1050 * This may be set under some error conditions,
1051 * however, only for VERR_BUFFER_OVERFLOW and
1052 * VERR_NO_STR_MEMORY will it contain a valid string
1053 * length that can be used to resize the buffer.
1054 * @param pszTag Allocation tag used for statistics and such.
1055 */
1056RTDECL(int) RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
1057
1058/**
1059 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
1060 *
1061 * This function will validate the string, and incorrectly encoded UTF-16
1062 * strings will be rejected. The primary purpose of this function is to
1063 * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
1064 * other purposes RTUtf16ToLatin1Ex() should be used.
1065 *
1066 * @returns Number of char (bytes).
1067 * @returns 0 if the string was incorrectly encoded.
1068 * @param pwsz The UTF-16 string.
1069 */
1070RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
1071
1072/**
1073 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
1074 *
1075 * This function will validate the string, and incorrectly encoded UTF-16
1076 * strings will be rejected.
1077 *
1078 * @returns iprt status code.
1079 * @param pwsz The string.
1080 * @param cwc The max string length. Use RTSTR_MAX to process the
1081 * entire string.
1082 * @param pcch Where to store the string length (in bytes). Optional.
1083 * This is undefined on failure.
1084 */
1085RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
1086
1087/**
1088 * Get the unicode code point at the given string position.
1089 *
1090 * @returns unicode code point.
1091 * @returns RTUNICP_INVALID if the encoding is invalid.
1092 * @param pwsz The string.
1093 *
1094 * @remark This is an internal worker for RTUtf16GetCp().
1095 */
1096RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
1097
1098/**
1099 * Get the unicode code point at the given string position.
1100 *
1101 * @returns iprt status code.
1102 * @param ppwsz Pointer to the string pointer. This will be updated to
1103 * point to the char following the current code point.
1104 * @param pCp Where to store the code point.
1105 * RTUNICP_INVALID is stored here on failure.
1106 *
1107 * @remark This is an internal worker for RTUtf16GetCpEx().
1108 */
1109RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1110
1111/**
1112 * Get the unicode code point at the given string position, big endian.
1113 *
1114 * @returns iprt status code.
1115 * @param ppwsz Pointer to the string pointer. This will be updated to
1116 * point to the char following the current code point.
1117 * @param pCp Where to store the code point.
1118 * RTUNICP_INVALID is stored here on failure.
1119 *
1120 * @remark This is an internal worker for RTUtf16BigGetCpEx().
1121 */
1122RTDECL(int) RTUtf16BigGetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1123
1124/**
1125 * Put the unicode code point at the given string position
1126 * and return the pointer to the char following it.
1127 *
1128 * This function will not consider anything at or following the
1129 * buffer area pointed to by pwsz. It is therefore not suitable for
1130 * inserting code points into a string, only appending/overwriting.
1131 *
1132 * @returns pointer to the char following the written code point.
1133 * @param pwsz The string.
1134 * @param CodePoint The code point to write.
1135 * This should not be RTUNICP_INVALID or any other
1136 * character out of the UTF-16 range.
1137 *
1138 * @remark This is an internal worker for RTUtf16GetCpEx().
1139 */
1140RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
1141
1142/**
1143 * Get the unicode code point at the given string position.
1144 *
1145 * @returns unicode code point.
1146 * @returns RTUNICP_INVALID if the encoding is invalid.
1147 * @param pwsz The string.
1148 *
1149 * @remark We optimize this operation by using an inline function for
1150 * everything which isn't a surrogate pair or an endian indicator.
1151 */
1152DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
1153{
1154 const RTUTF16 wc = *pwsz;
1155 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1156 return wc;
1157 return RTUtf16GetCpInternal(pwsz);
1158}
1159
1160/**
1161 * Get the unicode code point at the given string position.
1162 *
1163 * @returns iprt status code.
1164 * @param ppwsz Pointer to the string pointer. This will be updated to
1165 * point to the char following the current code point.
1166 * @param pCp Where to store the code point.
1167 * RTUNICP_INVALID is stored here on failure.
1168 *
1169 * @remark We optimize this operation by using an inline function for
1170 * everything which isn't a surrogate pair or and endian indicator.
1171 */
1172DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1173{
1174 const RTUTF16 wc = **ppwsz;
1175 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1176 {
1177 (*ppwsz)++;
1178 *pCp = wc;
1179 return VINF_SUCCESS;
1180 }
1181 return RTUtf16GetCpExInternal(ppwsz, pCp);
1182}
1183
1184/**
1185 * Get the unicode code point at the given string position, big endian version.
1186 *
1187 * @returns iprt status code.
1188 * @param ppwsz Pointer to the string pointer. This will be updated to
1189 * point to the char following the current code point.
1190 * @param pCp Where to store the code point.
1191 * RTUNICP_INVALID is stored here on failure.
1192 *
1193 * @remark We optimize this operation by using an inline function for
1194 * everything which isn't a surrogate pair or and endian indicator.
1195 */
1196DECLINLINE(int) RTUtf16BigGetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1197{
1198#ifdef RT_BIG_ENDIAN
1199 return RTUtf16GetCpEx(ppwsz, pCp);
1200#else
1201# ifdef ___iprt_asm_h
1202 const RTUTF16 wc = RT_BE2H_U16(**ppwsz);
1203 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1204 {
1205 (*ppwsz)++;
1206 *pCp = wc;
1207 return VINF_SUCCESS;
1208 }
1209# endif
1210 return RTUtf16BigGetCpExInternal(ppwsz, pCp);
1211#endif
1212}
1213
1214/**
1215 * Put the unicode code point at the given string position
1216 * and return the pointer to the char following it.
1217 *
1218 * This function will not consider anything at or following the
1219 * buffer area pointed to by pwsz. It is therefore not suitable for
1220 * inserting code points into a string, only appending/overwriting.
1221 *
1222 * @returns pointer to the char following the written code point.
1223 * @param pwsz The string.
1224 * @param CodePoint The code point to write.
1225 * This should not be RTUNICP_INVALID or any other
1226 * character out of the UTF-16 range.
1227 *
1228 * @remark We optimize this operation by using an inline function for
1229 * everything which isn't a surrogate pair or and endian indicator.
1230 */
1231DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
1232{
1233 if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
1234 {
1235 *pwsz++ = (RTUTF16)CodePoint;
1236 return pwsz;
1237 }
1238 return RTUtf16PutCpInternal(pwsz, CodePoint);
1239}
1240
1241/**
1242 * Skips ahead, past the current code point.
1243 *
1244 * @returns Pointer to the char after the current code point.
1245 * @param pwsz Pointer to the current code point.
1246 * @remark This will not move the next valid code point, only past the current one.
1247 */
1248DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
1249{
1250 RTUNICP Cp;
1251 RTUtf16GetCpEx(&pwsz, &Cp);
1252 return (PRTUTF16)pwsz;
1253}
1254
1255/**
1256 * Skips backwards, to the previous code point.
1257 *
1258 * @returns Pointer to the char after the current code point.
1259 * @param pwszStart Pointer to the start of the string.
1260 * @param pwsz Pointer to the current code point.
1261 */
1262RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
1263
1264
1265/**
1266 * Checks if the UTF-16 char is the high surrogate char (i.e.
1267 * the 1st char in the pair).
1268 *
1269 * @returns true if it is.
1270 * @returns false if it isn't.
1271 * @param wc The character to investigate.
1272 */
1273DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
1274{
1275 return wc >= 0xd800 && wc <= 0xdbff;
1276}
1277
1278/**
1279 * Checks if the UTF-16 char is the low surrogate char (i.e.
1280 * the 2nd char in the pair).
1281 *
1282 * @returns true if it is.
1283 * @returns false if it isn't.
1284 * @param wc The character to investigate.
1285 */
1286DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
1287{
1288 return wc >= 0xdc00 && wc <= 0xdfff;
1289}
1290
1291
1292/**
1293 * Checks if the two UTF-16 chars form a valid surrogate pair.
1294 *
1295 * @returns true if they do.
1296 * @returns false if they doesn't.
1297 * @param wcHigh The high (1st) character.
1298 * @param wcLow The low (2nd) character.
1299 */
1300DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
1301{
1302 return RTUtf16IsHighSurrogate(wcHigh)
1303 && RTUtf16IsLowSurrogate(wcLow);
1304}
1305
1306/**
1307 * Formats a buffer stream as hex bytes.
1308 *
1309 * The default is no separating spaces or line breaks or anything.
1310 *
1311 * @returns IPRT status code.
1312 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
1313 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
1314 *
1315 * @param pwszBuf Output string buffer.
1316 * @param cwcBuf The size of the output buffer in RTUTF16 units.
1317 * @param pv Pointer to the bytes to stringify.
1318 * @param cb The number of bytes to stringify.
1319 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
1320 * @sa RTStrPrintHexBytes.
1321 */
1322RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf, size_t cwcBuf, void const *pv, size_t cb, uint32_t fFlags);
1323
1324/** @} */
1325
1326
1327RT_C_DECLS_END
1328
1329/** @} */
1330
1331#endif
1332
Note: See TracBrowser for help on using the repository browser.

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