VirtualBox

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

Last change on this file since 71293 was 70443, checked in by vboxsync, 7 years ago

iprt/utf16.h: doxygen fix

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 58.8 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.
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.
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.
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/**
421 * Performs a case sensitive and length limited string compare between two UTF-16 strings.
422 *
423 * @returns < 0 if the first string less than the second string.
424 * @returns 0 if the first string identical to the second string.
425 * @returns > 0 if the first string greater than the second string.
426 * @param pwsz1 First UTF-16 string. Null is allowed.
427 * @param pwsz2 Second UTF-16 string. Null is allowed.
428 * @param cwcMax Maximum number of characters (RTUTF16) from the first
429 * @remark This function will not make any attempt to validate the encoding.
430 */
431RTDECL(int) RTUtf16NCmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2, size_t cwcMax);
432
433/**
434 * Performs a case sensitive and length limited string compare between an UTF-16
435 * string and a pure ASCII string.
436 *
437 * @returns < 0 if the first string less than the second string.
438 * @returns 0 if the first string identical to the second string.
439 * @returns > 0 if the first string greater than the second string.
440 * @param pwsz1 First UTF-16 string. Null is allowed.
441 * @param psz2 Second string, pure ASCII. Null is allowed.
442 * @param cwcMax Maximum number of characters (RTUTF16) to compare.
443 * @remark This function will not make any attempt to validate the encoding.
444 */
445RTDECL(int) RTUtf16NCmpAscii(PCRTUTF16 pwsz1, const char *psz2, size_t cwcMax);
446
447/**
448 * Performs a case sensitive and length limited string compare between an UTF-16
449 * string and a UTF-8 string.
450 *
451 * @returns < 0 if the first string less than the second string.
452 * @returns 0 if the first string identical to the second string.
453 * @returns > 0 if the first string greater than the second string.
454 * @param pwsz1 First UTF-16 string. Null is allowed.
455 * @param psz2 Second string, UTF-8. Null is allowed.
456 * @param cwcMax1 Maximum number of UTF-16 characters (RTUTF16) from the
457 * first string to compare.
458 * @param cchMax2 Maximum number of UTF-8 characters (char) from the
459 * second string to compare.
460 * @remarks NULL and empty strings are treated equally.
461 */
462RTDECL(int) RTUtf16NCmpUtf8(PCRTUTF16 pwsz1, const char *psz2, size_t cwcMax1, size_t cchMax2);
463
464
465/**
466 * Performs a case insensitive string compare between two UTF-16 strings.
467 *
468 * This is a simplified compare, as only the simplified lower/upper case folding
469 * specified by the unicode specs are used. It does not consider character pairs
470 * as they are used in some languages, just simple upper & lower case compares.
471 *
472 * @returns < 0 if the first string less than the second string.
473 * @returns 0 if the first string identical to the second string.
474 * @returns > 0 if the first string greater than the second string.
475 * @param pwsz1 First UTF-16 string. Null is allowed.
476 * @param pwsz2 Second UTF-16 string. Null is allowed.
477 */
478RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
479
480/**
481 * Performs a case insensitive string compare between two big endian UTF-16
482 * strings.
483 *
484 * This is a simplified compare, as only the simplified lower/upper case folding
485 * specified by the unicode specs are used. It does not consider character pairs
486 * as they are used in some languages, just simple upper & lower case compares.
487 *
488 * @returns < 0 if the first string less than the second string.
489 * @returns 0 if the first string identical to the second string.
490 * @returns > 0 if the first string greater than the second string.
491 * @param pwsz1 First big endian UTF-16 string. Null is allowed.
492 * @param pwsz2 Second big endian UTF-16 string. Null is allowed.
493 */
494RTDECL(int) RTUtf16BigICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
495
496/**
497 * Performs a case insensitive string compare between an UTF-16 string and a
498 * UTF-8 string.
499 *
500 * @returns < 0 if the first string less than the second string.s
501 * @returns 0 if the first string identical to the second string.
502 * @returns > 0 if the first string greater than the second string.
503 * @param pwsz1 First UTF-16 string. Null is allowed.
504 * @param psz2 Second string, UTF-8. Null is allowed.
505 * @remarks NULL and empty strings are treated equally.
506 */
507RTDECL(int) RTUtf16ICmpUtf8(PCRTUTF16 pwsz1, const char *psz2);
508
509/**
510 * Performs a case insensitive string compare between an UTF-16 string and a
511 * pure ASCII string.
512 *
513 * Since this compare only takes cares about the first 128 codepoints in
514 * unicode, no tables are needed and there aren't any real complications.
515 *
516 * @returns < 0 if the first string less than the second string.
517 * @returns 0 if the first string identical to the second string.
518 * @returns > 0 if the first string greater than the second string.
519 * @param pwsz1 First UTF-16 string. Null is allowed.
520 * @param psz2 Second string, pure ASCII. Null is allowed.
521 */
522RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1, const char *psz2);
523
524/**
525 * Performs a case insensitive string compare between two UTF-16 strings
526 * using the current locale of the process (if applicable).
527 *
528 * This differs from RTUtf16ICmp() in that it will try, if a locale with the
529 * required data is available, to do a correct case-insensitive compare. It
530 * follows that it is more complex and thereby likely to be more expensive.
531 *
532 * @returns < 0 if the first string less than the second string.
533 * @returns 0 if the first string identical to the second string.
534 * @returns > 0 if the first string greater than the second string.
535 * @param pwsz1 First UTF-16 string. Null is allowed.
536 * @param pwsz2 Second UTF-16 string. Null is allowed.
537 */
538RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
539
540/**
541 * Performs a case insensitive string compare between two UTF-16 strings,
542 * stopping after N characters.
543 *
544 * This is a simplified compare, as only the simplified lower/upper case folding
545 * specified by the unicode specs are used. It does not consider character pairs
546 * as they are used in some languages, just simple upper & lower case compares.
547 *
548 * @returns < 0 if the first string less than the second string.
549 * @returns 0 if the first string identical to the second string.
550 * @returns > 0 if the first string greater than the second string.
551 * @param pwsz1 First UTF-16 string. Null is allowed.
552 * @param pwsz2 Second UTF-16 string. Null is allowed.
553 * @param cwcMax Maximum number of characters to compare.
554 */
555RTDECL(int) RTUtf16NICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2, size_t cwcMax);
556
557/**
558 * Performs a case insensitive string compare between two big endian UTF-16
559 * strings, stopping after N characters.
560 *
561 * This is a simplified compare, as only the simplified lower/upper case folding
562 * specified by the unicode specs are used. It does not consider character pairs
563 * as they are used in some languages, just simple upper & lower case compares.
564 *
565 * @returns < 0 if the first string less than the second string.
566 * @returns 0 if the first string identical to the second string.
567 * @returns > 0 if the first string greater than the second string.
568 * @param pwsz1 First big endian UTF-16 string. Null is allowed.
569 * @param pwsz2 Second big endian UTF-16 string. Null is allowed.
570 * @param cwcMax Maximum number of characters to compare.
571 */
572RTDECL(int) RTUtf16BigNICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2, size_t cwcMax);
573
574/**
575 * Performs a case insensitive string compare between a UTF-16 string and a pure
576 * ASCII string, stopping after N characters.
577 *
578 * Since this compare only takes cares about the first 128 codepoints in
579 * unicode, no tables are needed and there aren't any real complications.
580 *
581 * @returns < 0 if the first string less than the second string.
582 * @returns 0 if the first string identical to the second string.
583 * @returns > 0 if the first string greater than the second string.
584 * @param pwsz1 The UTF-16 first string. Null is allowed.
585 * @param psz2 The pure ASCII second string. Null is allowed.
586 * @param cwcMax Maximum number of UTF-16 characters to compare.
587 */
588RTDECL(int) RTUtf16NICmpAscii(PCRTUTF16 pwsz1, const char *psz2, size_t cwcMax);
589
590
591/**
592 * Folds a UTF-16 string to lowercase.
593 *
594 * This is a very simple folding; is uses the simple lowercase
595 * code point, it is not related to any locale just the most common
596 * lowercase codepoint setup by the unicode specs, and it will not
597 * create new surrogate pairs or remove existing ones.
598 *
599 * @returns Pointer to the passed in string.
600 * @param pwsz The string to fold.
601 */
602RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
603
604/**
605 * Folds a UTF-16 string to uppercase.
606 *
607 * This is a very simple folding; is uses the simple uppercase
608 * code point, it is not related to any locale just the most common
609 * uppercase codepoint setup by the unicode specs, and it will not
610 * create new surrogate pairs or remove existing ones.
611 *
612 * @returns Pointer to the passed in string.
613 * @param pwsz The string to fold.
614 */
615RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
616
617/**
618 * Validates the UTF-16 encoding of the string.
619 *
620 * @returns iprt status code.
621 * @param pwsz The string.
622 */
623RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz);
624
625/**
626 * Validates the UTF-16 encoding of the string.
627 *
628 * @returns iprt status code.
629 * @param pwsz The string.
630 * @param cwc The max string length (/ size) in UTF-16 units. Use
631 * RTSTR_MAX to process the entire string.
632 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
633 */
634RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz, size_t cwc, uint32_t fFlags);
635
636/**
637 * Checks if the UTF-16 encoding is valid.
638 *
639 * @returns true / false.
640 * @param pwsz The string.
641 */
642RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz);
643
644/**
645 * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
646 * list in-place by an ASCII replacement character.
647 *
648 * Surrogate paris will be replaced by two chars.
649 *
650 * @returns The number of code points replaced. In the case of an incorrectly
651 * encoded string -1 will be returned, and the string is not completely
652 * processed. In the case of puszValidPairs having an odd number of
653 * code points, -1 will be also return but without any modification to
654 * the string.
655 * @param pwsz The string to sanitise.
656 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
657 * Each pair is the start and end point of a range,
658 * and the union of these ranges forms the white list.
659 * @param chReplacement The ASCII replacement character.
660 * @sa RTStrPurgeComplementSet
661 */
662RTDECL(ssize_t) RTUtf16PurgeComplementSet(PRTUTF16 pwsz, PCRTUNICP puszValidPairs, char chReplacement);
663
664
665/**
666 * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
667 * tag).
668 *
669 * @returns iprt status code.
670 * @param pwszString UTF-16 string to convert.
671 * @param ppszString Receives pointer of allocated UTF-8 string on
672 * success, and is always set to NULL on failure.
673 * The returned pointer must be freed using RTStrFree().
674 */
675#define RTUtf16ToUtf8(pwszString, ppszString) RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
676
677/**
678 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
679 *
680 * @returns iprt status code.
681 * @param pwszString UTF-16 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 * @param pszTag Allocation tag used for statistics and such.
686 */
687RTDECL(int) RTUtf16ToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
688
689/**
690 * Translate a UTF-16BE string into a UTF-8 allocating the result buffer
691 * (default tag).
692 *
693 * This differs from RTUtf16ToUtf8 in that the input is always a
694 * big-endian string.
695 *
696 * @returns iprt status code.
697 * @param pwszString UTF-16BE string to convert.
698 * @param ppszString Receives pointer of allocated UTF-8 string on
699 * success, and is always set to NULL on failure.
700 * The returned pointer must be freed using RTStrFree().
701 */
702#define RTUtf16BigToUtf8(pwszString, ppszString) RTUtf16BigToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
703
704/**
705 * Translate a UTF-16BE string into a UTF-8 allocating the result buffer.
706 *
707 * This differs from RTUtf16ToUtf8Tag in that the input is always a
708 * big-endian string.
709 *
710 * @returns iprt status code.
711 * @param pwszString UTF-16BE string to convert.
712 * @param ppszString Receives pointer of allocated UTF-8 string on
713 * success, and is always set to NULL on failure.
714 * The returned pointer must be freed using RTStrFree().
715 * @param pszTag Allocation tag used for statistics and such.
716 */
717RTDECL(int) RTUtf16BigToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
718
719/**
720 * Translate a UTF-16LE string into a UTF-8 allocating the result buffer
721 * (default tag).
722 *
723 * This differs from RTUtf16ToUtf8 in that the input is always a
724 * little-endian string.
725 *
726 * @returns iprt status code.
727 * @param pwszString UTF-16LE string to convert.
728 * @param ppszString Receives pointer of allocated UTF-8 string on
729 * success, and is always set to NULL on failure.
730 * The returned pointer must be freed using RTStrFree().
731 */
732#define RTUtf16LittleToUtf8(pwszString, ppszString) RTUtf16LittleToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
733
734/**
735 * Translate a UTF-16LE string into a UTF-8 allocating the result buffer.
736 *
737 * This differs from RTUtf16ToUtf8Tag in that the input is always a
738 * little-endian string.
739 *
740 * @returns iprt status code.
741 * @param pwszString UTF-16LE string to convert.
742 * @param ppszString Receives pointer of allocated UTF-8 string on
743 * success, and is always set to NULL on failure.
744 * The returned pointer must be freed using RTStrFree().
745 * @param pszTag Allocation tag used for statistics and such.
746 */
747RTDECL(int) RTUtf16LittleToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
748
749
750/**
751 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
752 * sized buffer allocated by the function (default tag).
753 *
754 * @returns iprt status code.
755 * @param pwszString The UTF-16 string to convert.
756 * @param cwcString The number of RTUTF16 items to translate from pwszString.
757 * The translation will stop when reaching cwcString or the terminator ('\\0').
758 * Use RTSTR_MAX to translate the entire string.
759 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
760 * a buffer of the specified size, or pointer to a NULL pointer.
761 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
762 * will be allocated to hold the translated string.
763 * If a buffer was requested it must be freed using RTStrFree().
764 * @param cch The buffer size in chars (the type). This includes the terminator.
765 * @param pcch Where to store the length of the translated string,
766 * excluding the terminator. (Optional)
767 *
768 * This may be set under some error conditions,
769 * however, only for VERR_BUFFER_OVERFLOW and
770 * VERR_NO_STR_MEMORY will it contain a valid string
771 * length that can be used to resize the buffer.
772 */
773#define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
774 RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
775
776/**
777 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
778 * sized buffer allocated by the function (custom tag).
779 *
780 * @returns iprt status code.
781 * @param pwszString The UTF-16 string to convert.
782 * @param cwcString The number of RTUTF16 items to translate from pwszString.
783 * The translation will stop when reaching cwcString or the terminator ('\\0').
784 * Use RTSTR_MAX to translate the entire string.
785 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
786 * a buffer of the specified size, or pointer to a NULL pointer.
787 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
788 * will be allocated to hold the translated string.
789 * If a buffer was requested it must be freed using RTStrFree().
790 * @param cch The buffer size in chars (the type). This includes the terminator.
791 * @param pcch Where to store the length of the translated string,
792 * excluding the terminator. (Optional)
793 *
794 * This may be set under some error conditions,
795 * however, only for VERR_BUFFER_OVERFLOW and
796 * VERR_NO_STR_MEMORY will it contain a valid string
797 * length that can be used to resize the buffer.
798 * @param pszTag Allocation tag used for statistics and such.
799 */
800RTDECL(int) RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
801
802/**
803 * Translates UTF-16BE to UTF-8 using buffer provided by the caller or a
804 * fittingly sized buffer allocated by the function (default tag).
805 *
806 * This differs from RTUtf16ToUtf8Ex in that the input is always a
807 * big-endian string.
808 *
809 * @returns iprt status code.
810 * @param pwszString The UTF-16BE string to convert.
811 * @param cwcString The number of RTUTF16 items to translate from pwszString.
812 * The translation will stop when reaching cwcString or the terminator ('\\0').
813 * Use RTSTR_MAX to translate the entire string.
814 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
815 * a buffer of the specified size, or pointer to a NULL pointer.
816 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
817 * will be allocated to hold the translated string.
818 * If a buffer was requested it must be freed using RTStrFree().
819 * @param cch The buffer size in chars (the type). This includes the terminator.
820 * @param pcch Where to store the length of the translated string,
821 * excluding the terminator. (Optional)
822 *
823 * This may be set under some error conditions,
824 * however, only for VERR_BUFFER_OVERFLOW and
825 * VERR_NO_STR_MEMORY will it contain a valid string
826 * length that can be used to resize the buffer.
827 */
828#define RTUtf16BigToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
829 RTUtf16BigToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
830
831/**
832 * Translates UTF-16BE to UTF-8 using buffer provided by the caller or a
833 * fittingly sized buffer allocated by the function (custom tag).
834 *
835 * This differs from RTUtf16ToUtf8ExTag in that the input is always a
836 * big-endian string.
837 *
838 * @returns iprt status code.
839 * @param pwszString The UTF-16BE string to convert.
840 * @param cwcString The number of RTUTF16 items to translate from pwszString.
841 * The translation will stop when reaching cwcString or the terminator ('\\0').
842 * Use RTSTR_MAX to translate the entire string.
843 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
844 * a buffer of the specified size, or pointer to a NULL pointer.
845 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
846 * will be allocated to hold the translated string.
847 * If a buffer was requested it must be freed using RTStrFree().
848 * @param cch The buffer size in chars (the type). This includes the terminator.
849 * @param pcch Where to store the length of the translated string,
850 * excluding the terminator. (Optional)
851 *
852 * This may be set under some error conditions,
853 * however, only for VERR_BUFFER_OVERFLOW and
854 * VERR_NO_STR_MEMORY will it contain a valid string
855 * length that can be used to resize the buffer.
856 * @param pszTag Allocation tag used for statistics and such.
857 */
858RTDECL(int) RTUtf16BigToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
859
860/**
861 * Translates UTF-16LE to UTF-8 using buffer provided by the caller or a
862 * fittingly sized buffer allocated by the function (default tag).
863 *
864 * This differs from RTUtf16ToUtf8Ex in that the input is always a
865 * little-endian string.
866 *
867 * @returns iprt status code.
868 * @param pwszString The UTF-16LE string to convert.
869 * @param cwcString The number of RTUTF16 items to translate from pwszString.
870 * The translation will stop when reaching cwcString or the terminator ('\\0').
871 * Use RTSTR_MAX to translate the entire string.
872 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
873 * a buffer of the specified size, or pointer to a NULL pointer.
874 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
875 * will be allocated to hold the translated string.
876 * If a buffer was requested it must be freed using RTStrFree().
877 * @param cch The buffer size in chars (the type). This includes the terminator.
878 * @param pcch Where to store the length of the translated string,
879 * excluding the terminator. (Optional)
880 *
881 * This may be set under some error conditions,
882 * however, only for VERR_BUFFER_OVERFLOW and
883 * VERR_NO_STR_MEMORY will it contain a valid string
884 * length that can be used to resize the buffer.
885 */
886#define RTUtf16LittleToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
887 RTUtf16LittleToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
888
889/**
890 * Translates UTF-16LE to UTF-8 using buffer provided by the caller or a
891 * fittingly sized buffer allocated by the function (custom tag).
892 *
893 * This differs from RTUtf16ToUtf8ExTag in that the input is always a
894 * little-endian string.
895 *
896 * @returns iprt status code.
897 * @param pwszString The UTF-16LE string to convert.
898 * @param cwcString The number of RTUTF16 items to translate from pwszString.
899 * The translation will stop when reaching cwcString or the terminator ('\\0').
900 * Use RTSTR_MAX to translate the entire string.
901 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
902 * a buffer of the specified size, or pointer to a NULL pointer.
903 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
904 * will be allocated to hold the translated string.
905 * If a buffer was requested it must be freed using RTStrFree().
906 * @param cch The buffer size in chars (the type). This includes the terminator.
907 * @param pcch Where to store the length of the translated string,
908 * excluding the terminator. (Optional)
909 *
910 * This may be set under some error conditions,
911 * however, only for VERR_BUFFER_OVERFLOW and
912 * VERR_NO_STR_MEMORY will it contain a valid string
913 * length that can be used to resize the buffer.
914 * @param pszTag Allocation tag used for statistics and such.
915 */
916RTDECL(int) RTUtf16LittleToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch,
917 const char *pszTag);
918
919/**
920 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
921 *
922 * This function will validate the string, and incorrectly encoded UTF-16
923 * strings will be rejected. The primary purpose of this function is to
924 * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
925 * other purposes RTUtf16ToUtf8Ex() should be used.
926 *
927 * @returns Number of char (bytes).
928 * @returns 0 if the string was incorrectly encoded.
929 * @param pwsz The UTF-16 string.
930 */
931RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
932
933/**
934 * Calculates the length of the UTF-16BE string in UTF-8 chars (bytes).
935 *
936 * This function will validate the string, and incorrectly encoded UTF-16BE
937 * strings will be rejected. The primary purpose of this function is to
938 * help allocate buffers for RTUtf16BigToUtf8() of the correct size. For most
939 * other purposes RTUtf16BigToUtf8Ex() should be used.
940 *
941 * @returns Number of char (bytes).
942 * @returns 0 if the string was incorrectly encoded.
943 * @param pwsz The UTF-16BE string.
944 */
945RTDECL(size_t) RTUtf16BigCalcUtf8Len(PCRTUTF16 pwsz);
946
947/**
948 * Calculates the length of the UTF-16LE string in UTF-8 chars (bytes).
949 *
950 * This function will validate the string, and incorrectly encoded UTF-16LE
951 * strings will be rejected. The primary purpose of this function is to
952 * help allocate buffers for RTUtf16LittleToUtf8() of the correct size. For
953 * most other purposes RTUtf16LittleToUtf8Ex() should be used.
954 *
955 * @returns Number of char (bytes).
956 * @returns 0 if the string was incorrectly encoded.
957 * @param pwsz The UTF-16LE string.
958 */
959RTDECL(size_t) RTUtf16LittleCalcUtf8Len(PCRTUTF16 pwsz);
960
961/**
962 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
963 *
964 * This function will validate the string, and incorrectly encoded UTF-16
965 * strings will be rejected.
966 *
967 * @returns iprt status code.
968 * @param pwsz The string.
969 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
970 * @param pcch Where to store the string length (in bytes). Optional.
971 * This is undefined on failure.
972 */
973RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
974
975/**
976 * Calculates the length of the UTF-16BE string in UTF-8 chars (bytes).
977 *
978 * This function will validate the string, and incorrectly encoded UTF-16BE
979 * strings will be rejected.
980 *
981 * @returns iprt status code.
982 * @param pwsz The string.
983 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
984 * @param pcch Where to store the string length (in bytes). Optional.
985 * This is undefined on failure.
986 */
987RTDECL(int) RTUtf16BigCalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
988
989/**
990 * Calculates the length of the UTF-16LE string in UTF-8 chars (bytes).
991 *
992 * This function will validate the string, and incorrectly encoded UTF-16LE
993 * strings will be rejected.
994 *
995 * @returns iprt status code.
996 * @param pwsz The string.
997 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
998 * @param pcch Where to store the string length (in bytes). Optional.
999 * This is undefined on failure.
1000 */
1001RTDECL(int) RTUtf16LittleCalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
1002
1003/**
1004 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
1005 * buffer (default tag).
1006 *
1007 * @returns iprt status code.
1008 * @param pwszString UTF-16 string to convert.
1009 * @param ppszString Receives pointer of allocated Latin1 string on
1010 * success, and is always set to NULL on failure.
1011 * The returned pointer must be freed using RTStrFree().
1012 */
1013#define RTUtf16ToLatin1(pwszString, ppszString) RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
1014
1015/**
1016 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
1017 * buffer (custom tag).
1018 *
1019 * @returns iprt status code.
1020 * @param pwszString UTF-16 string to convert.
1021 * @param ppszString Receives pointer of allocated Latin1 string on
1022 * success, and is always set to NULL on failure.
1023 * The returned pointer must be freed using RTStrFree().
1024 * @param pszTag Allocation tag used for statistics and such.
1025 */
1026RTDECL(int) RTUtf16ToLatin1Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
1027
1028/**
1029 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
1030 * or a fittingly sized buffer allocated by the function (default tag).
1031 *
1032 * @returns iprt status code.
1033 * @param pwszString The UTF-16 string to convert.
1034 * @param cwcString The number of RTUTF16 items to translate from
1035 * pwszString. The translation will stop when reaching
1036 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
1037 * to translate the entire string.
1038 * @param ppsz Pointer to the pointer to the Latin-1 string. The
1039 * buffer can optionally be preallocated by the caller.
1040 *
1041 * If cch is zero, *ppsz is undefined.
1042 *
1043 * If cch is non-zero and *ppsz is not NULL, then this
1044 * will be used as the output buffer.
1045 * VERR_BUFFER_OVERFLOW will be returned if this is
1046 * insufficient.
1047 *
1048 * If cch is zero or *ppsz is NULL, then a buffer of
1049 * sufficient size is allocated. cch can be used to
1050 * specify a minimum size of this buffer. Use
1051 * RTUtf16Free() to free the result.
1052 *
1053 * @param cch The buffer size in chars (the type). This includes
1054 * the terminator.
1055 * @param pcch Where to store the length of the translated string,
1056 * excluding the terminator. (Optional)
1057 *
1058 * This may be set under some error conditions,
1059 * however, only for VERR_BUFFER_OVERFLOW and
1060 * VERR_NO_STR_MEMORY will it contain a valid string
1061 * length that can be used to resize the buffer.
1062 */
1063#define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
1064 RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
1065
1066/**
1067 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
1068 * or a fittingly sized buffer allocated by the function (custom tag).
1069 *
1070 * @returns iprt status code.
1071 * @param pwszString The UTF-16 string to convert.
1072 * @param cwcString The number of RTUTF16 items to translate from
1073 * pwszString. The translation will stop when reaching
1074 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
1075 * to translate the entire string.
1076 * @param ppsz Pointer to the pointer to the Latin-1 string. The
1077 * buffer can optionally be preallocated by the caller.
1078 *
1079 * If cch is zero, *ppsz is undefined.
1080 *
1081 * If cch is non-zero and *ppsz is not NULL, then this
1082 * will be used as the output buffer.
1083 * VERR_BUFFER_OVERFLOW will be returned if this is
1084 * insufficient.
1085 *
1086 * If cch is zero or *ppsz is NULL, then a buffer of
1087 * sufficient size is allocated. cch can be used to
1088 * specify a minimum size of this buffer. Use
1089 * RTUtf16Free() to free the result.
1090 *
1091 * @param cch The buffer size in chars (the type). This includes
1092 * the terminator.
1093 * @param pcch Where to store the length of the translated string,
1094 * excluding the terminator. (Optional)
1095 *
1096 * This may be set under some error conditions,
1097 * however, only for VERR_BUFFER_OVERFLOW and
1098 * VERR_NO_STR_MEMORY will it contain a valid string
1099 * length that can be used to resize the buffer.
1100 * @param pszTag Allocation tag used for statistics and such.
1101 */
1102RTDECL(int) RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
1103
1104/**
1105 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
1106 *
1107 * This function will validate the string, and incorrectly encoded UTF-16
1108 * strings will be rejected. The primary purpose of this function is to
1109 * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
1110 * other purposes RTUtf16ToLatin1Ex() should be used.
1111 *
1112 * @returns Number of char (bytes).
1113 * @returns 0 if the string was incorrectly encoded.
1114 * @param pwsz The UTF-16 string.
1115 */
1116RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
1117
1118/**
1119 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
1120 *
1121 * This function will validate the string, and incorrectly encoded UTF-16
1122 * strings will be rejected.
1123 *
1124 * @returns iprt status code.
1125 * @param pwsz The string.
1126 * @param cwc The max string length. Use RTSTR_MAX to process the
1127 * entire string.
1128 * @param pcch Where to store the string length (in bytes). Optional.
1129 * This is undefined on failure.
1130 */
1131RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
1132
1133/**
1134 * Get the unicode code point at the given string position.
1135 *
1136 * @returns unicode code point.
1137 * @returns RTUNICP_INVALID if the encoding is invalid.
1138 * @param pwsz The string.
1139 *
1140 * @remark This is an internal worker for RTUtf16GetCp().
1141 */
1142RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
1143
1144/**
1145 * Get the unicode code point at the given string position.
1146 *
1147 * @returns iprt status code.
1148 * @param ppwsz Pointer to the string pointer. This will be updated to
1149 * point to the char following the current code point.
1150 * @param pCp Where to store the code point.
1151 * RTUNICP_INVALID is stored here on failure.
1152 *
1153 * @remark This is an internal worker for RTUtf16GetCpEx().
1154 */
1155RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1156
1157/**
1158 * Get the unicode code point at the given string position, big endian.
1159 *
1160 * @returns iprt status code.
1161 * @param ppwsz Pointer to the string pointer. This will be updated to
1162 * point to the char following the current code point.
1163 * @param pCp Where to store the code point.
1164 * RTUNICP_INVALID is stored here on failure.
1165 *
1166 * @remark This is an internal worker for RTUtf16BigGetCpEx().
1167 */
1168RTDECL(int) RTUtf16BigGetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
1169
1170/**
1171 * Put the unicode code point at the given string position
1172 * and return the pointer to the char following it.
1173 *
1174 * This function will not consider anything at or following the
1175 * buffer area pointed to by pwsz. It is therefore not suitable for
1176 * inserting code points into a string, only appending/overwriting.
1177 *
1178 * @returns pointer to the char following the written code point.
1179 * @param pwsz The string.
1180 * @param CodePoint The code point to write.
1181 * This should not be RTUNICP_INVALID or any other
1182 * character out of the UTF-16 range.
1183 *
1184 * @remark This is an internal worker for RTUtf16GetCpEx().
1185 */
1186RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
1187
1188/**
1189 * Get the unicode code point at the given string position.
1190 *
1191 * @returns unicode code point.
1192 * @returns RTUNICP_INVALID if the encoding is invalid.
1193 * @param pwsz The string.
1194 *
1195 * @remark We optimize this operation by using an inline function for
1196 * everything which isn't a surrogate pair or an endian indicator.
1197 */
1198DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
1199{
1200 const RTUTF16 wc = *pwsz;
1201 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1202 return wc;
1203 return RTUtf16GetCpInternal(pwsz);
1204}
1205
1206/**
1207 * Get the unicode code point at the given string position.
1208 *
1209 * @returns iprt status code.
1210 * @param ppwsz Pointer to the string pointer. This will be updated to
1211 * point to the char following the current code point.
1212 * @param pCp Where to store the code point.
1213 * RTUNICP_INVALID is stored here on failure.
1214 *
1215 * @remark We optimize this operation by using an inline function for
1216 * everything which isn't a surrogate pair or and endian indicator.
1217 */
1218DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1219{
1220 const RTUTF16 wc = **ppwsz;
1221 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1222 {
1223 (*ppwsz)++;
1224 *pCp = wc;
1225 return VINF_SUCCESS;
1226 }
1227 return RTUtf16GetCpExInternal(ppwsz, pCp);
1228}
1229
1230/**
1231 * Get the unicode code point at the given string position, big endian version.
1232 *
1233 * @returns iprt status code.
1234 * @param ppwsz Pointer to the string pointer. This will be updated to
1235 * point to the char following the current code point.
1236 * @param pCp Where to store the code point.
1237 * RTUNICP_INVALID is stored here on failure.
1238 *
1239 * @remark We optimize this operation by using an inline function for
1240 * everything which isn't a surrogate pair or and endian indicator.
1241 */
1242DECLINLINE(int) RTUtf16BigGetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
1243{
1244#ifdef RT_BIG_ENDIAN
1245 return RTUtf16GetCpEx(ppwsz, pCp);
1246#else
1247# ifdef ___iprt_asm_h
1248 const RTUTF16 wc = RT_BE2H_U16(**ppwsz);
1249 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
1250 {
1251 (*ppwsz)++;
1252 *pCp = wc;
1253 return VINF_SUCCESS;
1254 }
1255# endif
1256 return RTUtf16BigGetCpExInternal(ppwsz, pCp);
1257#endif
1258}
1259
1260/**
1261 * Put the unicode code point at the given string position
1262 * and return the pointer to the char following it.
1263 *
1264 * This function will not consider anything at or following the
1265 * buffer area pointed to by pwsz. It is therefore not suitable for
1266 * inserting code points into a string, only appending/overwriting.
1267 *
1268 * @returns pointer to the char following the written code point.
1269 * @param pwsz The string.
1270 * @param CodePoint The code point to write.
1271 * This should not be RTUNICP_INVALID or any other
1272 * character out of the UTF-16 range.
1273 *
1274 * @remark We optimize this operation by using an inline function for
1275 * everything which isn't a surrogate pair or and endian indicator.
1276 */
1277DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
1278{
1279 if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
1280 {
1281 *pwsz++ = (RTUTF16)CodePoint;
1282 return pwsz;
1283 }
1284 return RTUtf16PutCpInternal(pwsz, CodePoint);
1285}
1286
1287/**
1288 * Skips ahead, past the current code point.
1289 *
1290 * @returns Pointer to the char after the current code point.
1291 * @param pwsz Pointer to the current code point.
1292 * @remark This will not move the next valid code point, only past the current one.
1293 */
1294DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
1295{
1296 RTUNICP Cp;
1297 RTUtf16GetCpEx(&pwsz, &Cp);
1298 return (PRTUTF16)pwsz;
1299}
1300
1301/**
1302 * Skips backwards, to the previous code point.
1303 *
1304 * @returns Pointer to the char after the current code point.
1305 * @param pwszStart Pointer to the start of the string.
1306 * @param pwsz Pointer to the current code point.
1307 */
1308RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
1309
1310
1311/**
1312 * Checks if the UTF-16 char is the high surrogate char (i.e.
1313 * the 1st char in the pair).
1314 *
1315 * @returns true if it is.
1316 * @returns false if it isn't.
1317 * @param wc The character to investigate.
1318 */
1319DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
1320{
1321 return wc >= 0xd800 && wc <= 0xdbff;
1322}
1323
1324/**
1325 * Checks if the UTF-16 char is the low surrogate char (i.e.
1326 * the 2nd char in the pair).
1327 *
1328 * @returns true if it is.
1329 * @returns false if it isn't.
1330 * @param wc The character to investigate.
1331 */
1332DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
1333{
1334 return wc >= 0xdc00 && wc <= 0xdfff;
1335}
1336
1337
1338/**
1339 * Checks if the two UTF-16 chars form a valid surrogate pair.
1340 *
1341 * @returns true if they do.
1342 * @returns false if they doesn't.
1343 * @param wcHigh The high (1st) character.
1344 * @param wcLow The low (2nd) character.
1345 */
1346DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
1347{
1348 return RTUtf16IsHighSurrogate(wcHigh)
1349 && RTUtf16IsLowSurrogate(wcLow);
1350}
1351
1352/**
1353 * Formats a buffer stream as hex bytes.
1354 *
1355 * The default is no separating spaces or line breaks or anything.
1356 *
1357 * @returns IPRT status code.
1358 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
1359 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
1360 *
1361 * @param pwszBuf Output string buffer.
1362 * @param cwcBuf The size of the output buffer in RTUTF16 units.
1363 * @param pv Pointer to the bytes to stringify.
1364 * @param cb The number of bytes to stringify.
1365 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
1366 * @sa RTStrPrintHexBytes.
1367 */
1368RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf, size_t cwcBuf, void const *pv, size_t cb, uint32_t fFlags);
1369
1370/** @} */
1371
1372
1373RT_C_DECLS_END
1374
1375/** @} */
1376
1377#endif
1378
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