VirtualBox

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

Last change on this file since 66392 was 62930, checked in by vboxsync, 8 years ago

RTUtf16PurgeEncoding: Optimized it a little, adding debug assertion for bad pairs.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 40.4 KB
Line 
1/** @file
2 * IPRT - String Manipulation, UTF-16 encoding.
3 */
4
5/*
6 * Copyright (C) 2006-2016 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 an UTF-16 string and a
436 * UTF-8 string.
437 *
438 * @returns < 0 if the first string less than the second string.s
439 * @returns 0 if the first string identical to the second string.
440 * @returns > 0 if the first string greater than the second string.
441 * @param pwsz1 First UTF-16 string. Null is allowed.
442 * @param psz2 Second string, UTF-8. Null is allowed.
443 * @remarks NULL and empty strings are treated equally.
444 */
445RTDECL(int) RTUtf16ICmpUtf8(PCRTUTF16 pwsz1, const char *psz2);
446
447/**
448 * Performs a case insensitive string compare between an UTF-16 string and an
449 * pure ASCII string.
450 *
451 * Since this compare only takes cares about the first 128 codepoints in
452 * unicode, no tables are needed and there aren't any real complications.
453 *
454 * @returns < 0 if the first string less than the second string.
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, pure ASCII. Null is allowed.
459 */
460RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1, const char *psz2);
461
462/**
463 * Performs a case insensitive string compare between two UTF-16 strings
464 * using the current locale of the process (if applicable).
465 *
466 * This differs from RTUtf16ICmp() in that it will try, if a locale with the
467 * required data is available, to do a correct case-insensitive compare. It
468 * follows that it is more complex and thereby likely to be more expensive.
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 pwsz2 Second UTF-16 string. Null is allowed.
475 */
476RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
477
478/**
479 * Folds a UTF-16 string to lowercase.
480 *
481 * This is a very simple folding; is uses the simple lowercase
482 * code point, it is not related to any locale just the most common
483 * lowercase codepoint setup by the unicode specs, and it will not
484 * create new surrogate pairs or remove existing ones.
485 *
486 * @returns Pointer to the passed in string.
487 * @param pwsz The string to fold.
488 */
489RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
490
491/**
492 * Folds a UTF-16 string to uppercase.
493 *
494 * This is a very simple folding; is uses the simple uppercase
495 * code point, it is not related to any locale just the most common
496 * uppercase codepoint setup by the unicode specs, and it will not
497 * create new surrogate pairs or remove existing ones.
498 *
499 * @returns Pointer to the passed in string.
500 * @param pwsz The string to fold.
501 */
502RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
503
504/**
505 * Validates the UTF-16 encoding of the string.
506 *
507 * @returns iprt status code.
508 * @param pwsz The string.
509 */
510RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz);
511
512/**
513 * Validates the UTF-16 encoding of the string.
514 *
515 * @returns iprt status code.
516 * @param pwsz The string.
517 * @param cwc The max string length (/ size) in UTF-16 units. Use
518 * RTSTR_MAX to process the entire string.
519 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
520 */
521RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz, size_t cwc, uint32_t fFlags);
522
523/**
524 * Checks if the UTF-16 encoding is valid.
525 *
526 * @returns true / false.
527 * @param pwsz The string.
528 */
529RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz);
530
531/**
532 * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
533 * list in-place by an ASCII replacement character.
534 *
535 * Surrogate paris will be replaced by two chars.
536 *
537 * @returns The number of code points replaced. In the case of an incorrectly
538 * encoded string -1 will be returned, and the string is not completely
539 * processed. In the case of puszValidPairs having an odd number of
540 * code points, -1 will be also return but without any modification to
541 * the string.
542 * @param pwsz The string to sanitise.
543 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
544 * Each pair is the start and end point of a range,
545 * and the union of these ranges forms the white list.
546 * @param chReplacement The ASCII replacement character.
547 * @sa RTStrPurgeComplementSet
548 */
549RTDECL(ssize_t) RTUtf16PurgeComplementSet(PRTUTF16 pwsz, PCRTUNICP puszValidPairs, char chReplacement);
550
551/**
552 * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
553 * tag).
554 *
555 * @returns iprt status code.
556 * @param pwszString UTF-16 string to convert.
557 * @param ppszString Receives pointer of allocated UTF-8 string on
558 * success, and is always set to NULL on failure.
559 * The returned pointer must be freed using RTStrFree().
560 */
561#define RTUtf16ToUtf8(pwszString, ppszString) RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
562
563/**
564 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
565 *
566 * @returns iprt status code.
567 * @param pwszString UTF-16 string to convert.
568 * @param ppszString Receives pointer of allocated UTF-8 string on
569 * success, and is always set to NULL on failure.
570 * The returned pointer must be freed using RTStrFree().
571 * @param pszTag Allocation tag used for statistics and such.
572 */
573RTDECL(int) RTUtf16ToUtf8Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
574
575/**
576 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
577 * sized buffer allocated by the function (default tag).
578 *
579 * @returns iprt status code.
580 * @param pwszString The UTF-16 string to convert.
581 * @param cwcString The number of RTUTF16 items to translate from pwszString.
582 * The translation will stop when reaching cwcString or the terminator ('\\0').
583 * Use RTSTR_MAX to translate the entire string.
584 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
585 * a buffer of the specified size, or pointer to a NULL pointer.
586 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
587 * will be allocated to hold the translated string.
588 * If a buffer was requested it must be freed using RTStrFree().
589 * @param cch The buffer size in chars (the type). This includes the terminator.
590 * @param pcch Where to store the length of the translated string,
591 * excluding the terminator. (Optional)
592 *
593 * This may be set under some error conditions,
594 * however, only for VERR_BUFFER_OVERFLOW and
595 * VERR_NO_STR_MEMORY will it contain a valid string
596 * length that can be used to resize the buffer.
597 */
598#define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
599 RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
600
601/**
602 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
603 * sized buffer allocated by the function (custom tag).
604 *
605 * @returns iprt status code.
606 * @param pwszString The UTF-16 string to convert.
607 * @param cwcString The number of RTUTF16 items to translate from pwszString.
608 * The translation will stop when reaching cwcString or the terminator ('\\0').
609 * Use RTSTR_MAX to translate the entire string.
610 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
611 * a buffer of the specified size, or pointer to a NULL pointer.
612 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
613 * will be allocated to hold the translated string.
614 * If a buffer was requested it must be freed using RTStrFree().
615 * @param cch The buffer size in chars (the type). This includes the terminator.
616 * @param pcch Where to store the length of the translated string,
617 * excluding the terminator. (Optional)
618 *
619 * This may be set under some error conditions,
620 * however, only for VERR_BUFFER_OVERFLOW and
621 * VERR_NO_STR_MEMORY will it contain a valid string
622 * length that can be used to resize the buffer.
623 * @param pszTag Allocation tag used for statistics and such.
624 */
625RTDECL(int) RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
626
627/**
628 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
629 *
630 * This function will validate the string, and incorrectly encoded UTF-16
631 * strings will be rejected. The primary purpose of this function is to
632 * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
633 * other purposes RTUtf16ToUtf8Ex() should be used.
634 *
635 * @returns Number of char (bytes).
636 * @returns 0 if the string was incorrectly encoded.
637 * @param pwsz The UTF-16 string.
638 */
639RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
640
641/**
642 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
643 *
644 * This function will validate the string, and incorrectly encoded UTF-16
645 * strings will be rejected.
646 *
647 * @returns iprt status code.
648 * @param pwsz The string.
649 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
650 * @param pcch Where to store the string length (in bytes). Optional.
651 * This is undefined on failure.
652 */
653RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
654
655/**
656 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
657 * buffer (default tag).
658 *
659 * @returns iprt status code.
660 * @param pwszString UTF-16 string to convert.
661 * @param ppszString Receives pointer of allocated Latin1 string on
662 * success, and is always set to NULL on failure.
663 * The returned pointer must be freed using RTStrFree().
664 */
665#define RTUtf16ToLatin1(pwszString, ppszString) RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
666
667/**
668 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
669 * buffer (custom tag).
670 *
671 * @returns iprt status code.
672 * @param pwszString UTF-16 string to convert.
673 * @param ppszString Receives pointer of allocated Latin1 string on
674 * success, and is always set to NULL on failure.
675 * The returned pointer must be freed using RTStrFree().
676 * @param pszTag Allocation tag used for statistics and such.
677 */
678RTDECL(int) RTUtf16ToLatin1Tag(PCRTUTF16 pwszString, char **ppszString, const char *pszTag);
679
680/**
681 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
682 * or a fittingly sized buffer allocated by the function (default tag).
683 *
684 * @returns iprt status code.
685 * @param pwszString The UTF-16 string to convert.
686 * @param cwcString The number of RTUTF16 items to translate from
687 * pwszString. The translation will stop when reaching
688 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
689 * to translate the entire string.
690 * @param ppsz Pointer to the pointer to the Latin-1 string. The
691 * buffer can optionally be preallocated by the caller.
692 *
693 * If cch is zero, *ppsz is undefined.
694 *
695 * If cch is non-zero and *ppsz is not NULL, then this
696 * will be used as the output buffer.
697 * VERR_BUFFER_OVERFLOW will be returned if this is
698 * insufficient.
699 *
700 * If cch is zero or *ppsz is NULL, then a buffer of
701 * sufficient size is allocated. cch can be used to
702 * specify a minimum size of this buffer. Use
703 * RTUtf16Free() to free the result.
704 *
705 * @param cch The buffer size in chars (the type). This includes
706 * the terminator.
707 * @param pcch Where to store the length of the translated string,
708 * excluding the terminator. (Optional)
709 *
710 * This may be set under some error conditions,
711 * however, only for VERR_BUFFER_OVERFLOW and
712 * VERR_NO_STR_MEMORY will it contain a valid string
713 * length that can be used to resize the buffer.
714 */
715#define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
716 RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
717
718/**
719 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
720 * or a fittingly sized buffer allocated by the function (custom tag).
721 *
722 * @returns iprt status code.
723 * @param pwszString The UTF-16 string to convert.
724 * @param cwcString The number of RTUTF16 items to translate from
725 * pwszString. The translation will stop when reaching
726 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
727 * to translate the entire string.
728 * @param ppsz Pointer to the pointer to the Latin-1 string. The
729 * buffer can optionally be preallocated by the caller.
730 *
731 * If cch is zero, *ppsz is undefined.
732 *
733 * If cch is non-zero and *ppsz is not NULL, then this
734 * will be used as the output buffer.
735 * VERR_BUFFER_OVERFLOW will be returned if this is
736 * insufficient.
737 *
738 * If cch is zero or *ppsz is NULL, then a buffer of
739 * sufficient size is allocated. cch can be used to
740 * specify a minimum size of this buffer. Use
741 * RTUtf16Free() to free the result.
742 *
743 * @param cch The buffer size in chars (the type). This includes
744 * 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) RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
755
756/**
757 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
758 *
759 * This function will validate the string, and incorrectly encoded UTF-16
760 * strings will be rejected. The primary purpose of this function is to
761 * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
762 * other purposes RTUtf16ToLatin1Ex() should be used.
763 *
764 * @returns Number of char (bytes).
765 * @returns 0 if the string was incorrectly encoded.
766 * @param pwsz The UTF-16 string.
767 */
768RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
769
770/**
771 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
772 *
773 * This function will validate the string, and incorrectly encoded UTF-16
774 * strings will be rejected.
775 *
776 * @returns iprt status code.
777 * @param pwsz The string.
778 * @param cwc The max string length. Use RTSTR_MAX to process the
779 * entire string.
780 * @param pcch Where to store the string length (in bytes). Optional.
781 * This is undefined on failure.
782 */
783RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
784
785/**
786 * Get the unicode code point at the given string position.
787 *
788 * @returns unicode code point.
789 * @returns RTUNICP_INVALID if the encoding is invalid.
790 * @param pwsz The string.
791 *
792 * @remark This is an internal worker for RTUtf16GetCp().
793 */
794RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
795
796/**
797 * Get the unicode code point at the given string position.
798 *
799 * @returns iprt status code.
800 * @param ppwsz Pointer to the string pointer. This will be updated to
801 * point to the char following the current code point.
802 * @param pCp Where to store the code point.
803 * RTUNICP_INVALID is stored here on failure.
804 *
805 * @remark This is an internal worker for RTUtf16GetCpEx().
806 */
807RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
808
809/**
810 * Put the unicode code point at the given string position
811 * and return the pointer to the char following it.
812 *
813 * This function will not consider anything at or following the
814 * buffer area pointed to by pwsz. It is therefore not suitable for
815 * inserting code points into a string, only appending/overwriting.
816 *
817 * @returns pointer to the char following the written code point.
818 * @param pwsz The string.
819 * @param CodePoint The code point to write.
820 * This should not be RTUNICP_INVALID or any other
821 * character out of the UTF-16 range.
822 *
823 * @remark This is an internal worker for RTUtf16GetCpEx().
824 */
825RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
826
827/**
828 * Get the unicode code point at the given string position.
829 *
830 * @returns unicode code point.
831 * @returns RTUNICP_INVALID if the encoding is invalid.
832 * @param pwsz The string.
833 *
834 * @remark We optimize this operation by using an inline function for
835 * everything which isn't a surrogate pair or an endian indicator.
836 */
837DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
838{
839 const RTUTF16 wc = *pwsz;
840 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
841 return wc;
842 return RTUtf16GetCpInternal(pwsz);
843}
844
845/**
846 * Get the unicode code point at the given string position.
847 *
848 * @returns iprt status code.
849 * @param ppwsz Pointer to the string pointer. This will be updated to
850 * point to the char following the current code point.
851 * @param pCp Where to store the code point.
852 * RTUNICP_INVALID is stored here on failure.
853 *
854 * @remark We optimize this operation by using an inline function for
855 * everything which isn't a surrogate pair or and endian indicator.
856 */
857DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
858{
859 const RTUTF16 wc = **ppwsz;
860 if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
861 {
862 (*ppwsz)++;
863 *pCp = wc;
864 return VINF_SUCCESS;
865 }
866 return RTUtf16GetCpExInternal(ppwsz, pCp);
867}
868
869/**
870 * Put the unicode code point at the given string position
871 * and return the pointer to the char following it.
872 *
873 * This function will not consider anything at or following the
874 * buffer area pointed to by pwsz. It is therefore not suitable for
875 * inserting code points into a string, only appending/overwriting.
876 *
877 * @returns pointer to the char following the written code point.
878 * @param pwsz The string.
879 * @param CodePoint The code point to write.
880 * This should not be RTUNICP_INVALID or any other
881 * character out of the UTF-16 range.
882 *
883 * @remark We optimize this operation by using an inline function for
884 * everything which isn't a surrogate pair or and endian indicator.
885 */
886DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
887{
888 if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
889 {
890 *pwsz++ = (RTUTF16)CodePoint;
891 return pwsz;
892 }
893 return RTUtf16PutCpInternal(pwsz, CodePoint);
894}
895
896/**
897 * Skips ahead, past the current code point.
898 *
899 * @returns Pointer to the char after the current code point.
900 * @param pwsz Pointer to the current code point.
901 * @remark This will not move the next valid code point, only past the current one.
902 */
903DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
904{
905 RTUNICP Cp;
906 RTUtf16GetCpEx(&pwsz, &Cp);
907 return (PRTUTF16)pwsz;
908}
909
910/**
911 * Skips backwards, to the previous code point.
912 *
913 * @returns Pointer to the char after the current code point.
914 * @param pwszStart Pointer to the start of the string.
915 * @param pwsz Pointer to the current code point.
916 */
917RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
918
919
920/**
921 * Checks if the UTF-16 char is the high surrogate char (i.e.
922 * the 1st char in the pair).
923 *
924 * @returns true if it is.
925 * @returns false if it isn't.
926 * @param wc The character to investigate.
927 */
928DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
929{
930 return wc >= 0xd800 && wc <= 0xdbff;
931}
932
933/**
934 * Checks if the UTF-16 char is the low surrogate char (i.e.
935 * the 2nd char in the pair).
936 *
937 * @returns true if it is.
938 * @returns false if it isn't.
939 * @param wc The character to investigate.
940 */
941DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
942{
943 return wc >= 0xdc00 && wc <= 0xdfff;
944}
945
946
947/**
948 * Checks if the two UTF-16 chars form a valid surrogate pair.
949 *
950 * @returns true if they do.
951 * @returns false if they doesn't.
952 * @param wcHigh The high (1st) character.
953 * @param wcLow The low (2nd) character.
954 */
955DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
956{
957 return RTUtf16IsHighSurrogate(wcHigh)
958 && RTUtf16IsLowSurrogate(wcLow);
959}
960
961/**
962 * Formats a buffer stream as hex bytes.
963 *
964 * The default is no separating spaces or line breaks or anything.
965 *
966 * @returns IPRT status code.
967 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
968 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
969 *
970 * @param pwszBuf Output string buffer.
971 * @param cwcBuf The size of the output buffer in RTUTF16 units.
972 * @param pv Pointer to the bytes to stringify.
973 * @param cb The number of bytes to stringify.
974 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
975 * @sa RTStrPrintHexBytes.
976 */
977RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf, size_t cwcBuf, void const *pv, size_t cb, uint32_t fFlags);
978
979/** @} */
980
981
982RT_C_DECLS_END
983
984/** @} */
985
986#endif
987
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