]>
git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blob - ubuntu/vbox/include/iprt/utf16.h
2 * IPRT - String Manipulation, UTF-16 encoding.
6 * Copyright (C) 2006-2016 Oracle Corporation
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.
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.
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.
26 #ifndef ___iprt_utf16_h
27 #define ___iprt_utf16_h
29 #include <iprt/string.h>
34 /** @defgroup rt_str_utf16 UTF-16 String Manipulation
40 * Allocates memory for UTF-16 string storage (default tag).
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
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.
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.
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.
59 #define RTUtf16Alloc(cb) RTUtf16AllocTag((cb), RTSTR_TAG)
62 * Allocates memory for UTF-16 string storage (custom tag).
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
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.
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.
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.
82 RTDECL(PRTUTF16
) RTUtf16AllocTag(size_t cb
, const char *pszTag
);
85 * Reallocates the specified UTF-16 string (default tag).
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
91 * @returns VINF_SUCCESS.
92 * @retval VERR_NO_UTF16_MEMORY if we failed to reallocate the string, @a
93 * *ppwsz remains unchanged.
95 * @param ppwsz Pointer to the string variable containing the
96 * input and output string.
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
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.
110 * @param cbNew When @a cbNew is zero, we'll behave like
111 * RTUtf16Free and @a *ppwsz will be set to NULL.
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.
118 #define RTUtf16Realloc(ppwsz, cbNew) RTUtf16ReallocTag((ppwsz), (cbNew), RTSTR_TAG)
121 * Reallocates the specified UTF-16 string (custom tag).
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
127 * @returns VINF_SUCCESS.
128 * @retval VERR_NO_UTF16_MEMORY if we failed to reallocate the string, @a
129 * *ppwsz remains unchanged.
131 * @param ppwsz Pointer to the string variable containing the
132 * input and output string.
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
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.
146 * @param cbNew When @a cbNew is zero, we'll behave like
147 * RTUtf16Free and @a *ppwsz will be set to NULL.
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.
155 RTDECL(int) RTUtf16ReallocTag(PRTUTF16
*ppwsz
, size_t cbNew
, const char *pszTag
);
158 * Free a UTF-16 string allocated by RTStrToUtf16(), RTStrToUtf16Ex(),
159 * RTLatin1ToUtf16(), RTLatin1ToUtf16Ex(), RTUtf16Dup() or RTUtf16DupEx().
161 * @returns iprt status code.
162 * @param pwszString The UTF-16 string to free. NULL is accepted.
164 RTDECL(void) RTUtf16Free(PRTUTF16 pwszString
);
167 * Allocates a new copy of the specified UTF-16 string (default tag).
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.
174 #define RTUtf16Dup(pwszString) RTUtf16DupTag((pwszString), RTSTR_TAG)
177 * Allocates a new copy of the specified UTF-16 string (custom tag).
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.
185 RTDECL(PRTUTF16
) RTUtf16DupTag(PCRTUTF16 pwszString
, const char *pszTag
);
188 * Allocates a new copy of the specified UTF-16 string (default tag).
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.
197 #define RTUtf16DupEx(ppwszString, pwszString, cwcExtra) \
198 RTUtf16DupExTag((ppwszString), (pwszString), (cwcExtra), RTSTR_TAG)
201 * Allocates a new copy of the specified UTF-16 string (custom tag).
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.
211 RTDECL(int) RTUtf16DupExTag(PRTUTF16
*ppwszString
, PCRTUTF16 pwszString
, size_t cwcExtra
, const char *pszTag
);
214 * Returns the length of a UTF-16 string in UTF-16 characters
215 * without trailing '\\0'.
217 * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
218 * to get the exact number of code points in the string.
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.
224 RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString
);
227 * Find the length of a zero-terminated byte string, given a max string length.
229 * @returns The string length or cbMax. The returned length does not include
230 * the zero terminator if it was found.
232 * @param pwszString The string.
233 * @param cwcMax The max string length in RTUTF16s.
234 * @sa RTUtf16NLenEx, RTStrNLen.
236 RTDECL(size_t) RTUtf16NLen(PCRTUTF16 pwszString
, size_t cwcMax
);
239 * Find the length of a zero-terminated byte string, given
240 * a max string length.
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.
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
252 * @sa RTUtf16NLen, RTStrNLenEx.
254 RTDECL(int) RTUtf16NLenEx(PCRTUTF16 pwszString
, size_t cwcMax
, size_t *pcwc
);
257 * Find the zero terminator in a string with a limited length.
259 * @returns Pointer to the zero terminator.
260 * @returns NULL if the zero terminator was not found.
262 * @param pwszString The string.
263 * @param cwcMax The max string length. RTSTR_MAX is fine.
265 RTDECL(PCRTUTF16
) RTUtf16End(PCRTUTF16 pwszString
, size_t cwcMax
);
268 * Strips blankspaces from both ends of the string.
270 * @returns Pointer to first non-blank char in the string.
271 * @param pwsz The string to strip.
273 RTDECL(PRTUTF16
) RTUtf16Strip(PRTUTF16 pwsz
);
276 * Strips blankspaces from the start of the string.
278 * @returns Pointer to first non-blank char in the string.
279 * @param pwsz The string to strip.
281 RTDECL(PRTUTF16
) RTUtf16StripL(PCRTUTF16 pwsz
);
284 * Strips blankspaces from the end of the string.
287 * @param pwsz The string to strip.
289 RTDECL(PRTUTF16
) RTUtf16StripR(PRTUTF16 pwsz
);
292 * String copy with overflow handling.
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
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.
303 RTDECL(int) RTUtf16Copy(PRTUTF16 pwszDst
, size_t cwcDst
, PCRTUTF16 pwszSrc
);
306 * String copy with overflow handling, ASCII source.
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
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.
317 RTDECL(int) RTUtf16CopyAscii(PRTUTF16 pwszDst
, size_t cwcDst
, const char *pszSrc
);
320 * String copy with overflow handling.
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
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.
334 RTDECL(int) RTUtf16CopyEx(PRTUTF16 pwszDst
, size_t cwcDst
, PCRTUTF16 pwszSrc
, size_t cwcSrcMax
);
337 * String concatenation with overflow handling.
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
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.
348 RTDECL(int) RTUtf16Cat(PRTUTF16 pwszDst
, size_t cwcDst
, PCRTUTF16 pwszSrc
);
351 * String concatenation with overflow handling, ASCII source.
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
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.
362 RTDECL(int) RTUtf16CatAscii(PRTUTF16 pwszDst
, size_t cwcDst
, const char *pszSrc
);
365 * String concatenation with overflow handling.
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
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.
379 RTDECL(int) RTUtf16CatEx(PRTUTF16 pwszDst
, size_t cwcDst
, PCRTUTF16 pwszSrc
, size_t cwcSrcMax
);
382 * Performs a case sensitive string compare between two UTF-16 strings.
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.
391 RTDECL(int) RTUtf16Cmp(PCRTUTF16 pwsz1
, PCRTUTF16 pwsz2
);
394 * Performs a case sensitive string compare between an UTF-16 string and a pure
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.
404 RTDECL(int) RTUtf16CmpAscii(PCRTUTF16 pwsz1
, const char *psz2
);
407 * Performs a case sensitive string compare between an UTF-16 string and a UTF-8
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.
417 RTDECL(int) RTUtf16CmpUtf8(PCRTUTF16 pwsz1
, const char *psz2
);
420 * Performs a case insensitive string compare between two UTF-16 strings.
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.
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.
432 RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1
, PCRTUTF16 pwsz2
);
435 * Performs a case insensitive string compare between an UTF-16 string and a
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.
445 RTDECL(int) RTUtf16ICmpUtf8(PCRTUTF16 pwsz1
, const char *psz2
);
448 * Performs a case insensitive string compare between an UTF-16 string and a
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.
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.
460 RTDECL(int) RTUtf16ICmpAscii(PCRTUTF16 pwsz1
, const char *psz2
);
463 * Performs a case insensitive string compare between two UTF-16 strings
464 * using the current locale of the process (if applicable).
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.
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.
476 RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1
, PCRTUTF16 pwsz2
);
479 * Performs a case insensitive string compare between a UTF-16 string and a pure
480 * ASCII string, stopping after N characters.
482 * Since this compare only takes cares about the first 128 codepoints in
483 * unicode, no tables are needed and there aren't any real complications.
485 * @returns < 0 if the first string less than the second string.
486 * @returns 0 if the first string identical to the second string.
487 * @returns > 0 if the first string greater than the second string.
488 * @param pwsz1 The UTF-16 first string. Null is allowed.
489 * @param psz2 The pure ASCII second string. Null is allowed.
490 * @param cwcMax Maximum number of UTF-16 characters to compare.
492 RTDECL(int) RTUtf16NICmpAscii(PCRTUTF16 pwsz1
, const char *psz2
, size_t cwcMax
);
496 * Folds a UTF-16 string to lowercase.
498 * This is a very simple folding; is uses the simple lowercase
499 * code point, it is not related to any locale just the most common
500 * lowercase codepoint setup by the unicode specs, and it will not
501 * create new surrogate pairs or remove existing ones.
503 * @returns Pointer to the passed in string.
504 * @param pwsz The string to fold.
506 RTDECL(PRTUTF16
) RTUtf16ToLower(PRTUTF16 pwsz
);
509 * Folds a UTF-16 string to uppercase.
511 * This is a very simple folding; is uses the simple uppercase
512 * code point, it is not related to any locale just the most common
513 * uppercase codepoint setup by the unicode specs, and it will not
514 * create new surrogate pairs or remove existing ones.
516 * @returns Pointer to the passed in string.
517 * @param pwsz The string to fold.
519 RTDECL(PRTUTF16
) RTUtf16ToUpper(PRTUTF16 pwsz
);
522 * Validates the UTF-16 encoding of the string.
524 * @returns iprt status code.
525 * @param pwsz The string.
527 RTDECL(int) RTUtf16ValidateEncoding(PCRTUTF16 pwsz
);
530 * Validates the UTF-16 encoding of the string.
532 * @returns iprt status code.
533 * @param pwsz The string.
534 * @param cwc The max string length (/ size) in UTF-16 units. Use
535 * RTSTR_MAX to process the entire string.
536 * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
538 RTDECL(int) RTUtf16ValidateEncodingEx(PCRTUTF16 pwsz
, size_t cwc
, uint32_t fFlags
);
541 * Checks if the UTF-16 encoding is valid.
543 * @returns true / false.
544 * @param pwsz The string.
546 RTDECL(bool) RTUtf16IsValidEncoding(PCRTUTF16 pwsz
);
549 * Sanitise a (valid) UTF-16 string by replacing all characters outside a white
550 * list in-place by an ASCII replacement character.
552 * Surrogate paris will be replaced by two chars.
554 * @returns The number of code points replaced. In the case of an incorrectly
555 * encoded string -1 will be returned, and the string is not completely
556 * processed. In the case of puszValidPairs having an odd number of
557 * code points, -1 will be also return but without any modification to
559 * @param pwsz The string to sanitise.
560 * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
561 * Each pair is the start and end point of a range,
562 * and the union of these ranges forms the white list.
563 * @param chReplacement The ASCII replacement character.
564 * @sa RTStrPurgeComplementSet
566 RTDECL(ssize_t
) RTUtf16PurgeComplementSet(PRTUTF16 pwsz
, PCRTUNICP puszValidPairs
, char chReplacement
);
569 * Translate a UTF-16 string into a UTF-8 allocating the result buffer (default
572 * @returns iprt status code.
573 * @param pwszString UTF-16 string to convert.
574 * @param ppszString Receives pointer of allocated UTF-8 string on
575 * success, and is always set to NULL on failure.
576 * The returned pointer must be freed using RTStrFree().
578 #define RTUtf16ToUtf8(pwszString, ppszString) RTUtf16ToUtf8Tag((pwszString), (ppszString), RTSTR_TAG)
581 * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
583 * @returns iprt status code.
584 * @param pwszString UTF-16 string to convert.
585 * @param ppszString Receives pointer of allocated UTF-8 string on
586 * success, and is always set to NULL on failure.
587 * The returned pointer must be freed using RTStrFree().
588 * @param pszTag Allocation tag used for statistics and such.
590 RTDECL(int) RTUtf16ToUtf8Tag(PCRTUTF16 pwszString
, char **ppszString
, const char *pszTag
);
593 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
594 * sized buffer allocated by the function (default tag).
596 * @returns iprt status code.
597 * @param pwszString The UTF-16 string to convert.
598 * @param cwcString The number of RTUTF16 items to translate from pwszString.
599 * The translation will stop when reaching cwcString or the terminator ('\\0').
600 * Use RTSTR_MAX to translate the entire string.
601 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
602 * a buffer of the specified size, or pointer to a NULL pointer.
603 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
604 * will be allocated to hold the translated string.
605 * If a buffer was requested it must be freed using RTStrFree().
606 * @param cch The buffer size in chars (the type). This includes the terminator.
607 * @param pcch Where to store the length of the translated string,
608 * excluding the terminator. (Optional)
610 * This may be set under some error conditions,
611 * however, only for VERR_BUFFER_OVERFLOW and
612 * VERR_NO_STR_MEMORY will it contain a valid string
613 * length that can be used to resize the buffer.
615 #define RTUtf16ToUtf8Ex(pwszString, cwcString, ppsz, cch, pcch) \
616 RTUtf16ToUtf8ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
619 * Translates UTF-16 to UTF-8 using buffer provided by the caller or a fittingly
620 * sized buffer allocated by the function (custom tag).
622 * @returns iprt status code.
623 * @param pwszString The UTF-16 string to convert.
624 * @param cwcString The number of RTUTF16 items to translate from pwszString.
625 * The translation will stop when reaching cwcString or the terminator ('\\0').
626 * Use RTSTR_MAX to translate the entire string.
627 * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
628 * a buffer of the specified size, or pointer to a NULL pointer.
629 * If *ppsz is NULL or cch is zero a buffer of at least cch chars
630 * will be allocated to hold the translated string.
631 * If a buffer was requested it must be freed using RTStrFree().
632 * @param cch The buffer size in chars (the type). This includes the terminator.
633 * @param pcch Where to store the length of the translated string,
634 * excluding the terminator. (Optional)
636 * This may be set under some error conditions,
637 * however, only for VERR_BUFFER_OVERFLOW and
638 * VERR_NO_STR_MEMORY will it contain a valid string
639 * length that can be used to resize the buffer.
640 * @param pszTag Allocation tag used for statistics and such.
642 RTDECL(int) RTUtf16ToUtf8ExTag(PCRTUTF16 pwszString
, size_t cwcString
, char **ppsz
, size_t cch
, size_t *pcch
, const char *pszTag
);
645 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
647 * This function will validate the string, and incorrectly encoded UTF-16
648 * strings will be rejected. The primary purpose of this function is to
649 * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
650 * other purposes RTUtf16ToUtf8Ex() should be used.
652 * @returns Number of char (bytes).
653 * @returns 0 if the string was incorrectly encoded.
654 * @param pwsz The UTF-16 string.
656 RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz
);
659 * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
661 * This function will validate the string, and incorrectly encoded UTF-16
662 * strings will be rejected.
664 * @returns iprt status code.
665 * @param pwsz The string.
666 * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
667 * @param pcch Where to store the string length (in bytes). Optional.
668 * This is undefined on failure.
670 RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz
, size_t cwc
, size_t *pcch
);
673 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
674 * buffer (default tag).
676 * @returns iprt status code.
677 * @param pwszString UTF-16 string to convert.
678 * @param ppszString Receives pointer of allocated Latin1 string on
679 * success, and is always set to NULL on failure.
680 * The returned pointer must be freed using RTStrFree().
682 #define RTUtf16ToLatin1(pwszString, ppszString) RTUtf16ToLatin1Tag((pwszString), (ppszString), RTSTR_TAG)
685 * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
686 * buffer (custom tag).
688 * @returns iprt status code.
689 * @param pwszString UTF-16 string to convert.
690 * @param ppszString Receives pointer of allocated Latin1 string on
691 * success, and is always set to NULL on failure.
692 * The returned pointer must be freed using RTStrFree().
693 * @param pszTag Allocation tag used for statistics and such.
695 RTDECL(int) RTUtf16ToLatin1Tag(PCRTUTF16 pwszString
, char **ppszString
, const char *pszTag
);
698 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
699 * or a fittingly sized buffer allocated by the function (default tag).
701 * @returns iprt status code.
702 * @param pwszString The UTF-16 string to convert.
703 * @param cwcString The number of RTUTF16 items to translate from
704 * pwszString. The translation will stop when reaching
705 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
706 * to translate the entire string.
707 * @param ppsz Pointer to the pointer to the Latin-1 string. The
708 * buffer can optionally be preallocated by the caller.
710 * If cch is zero, *ppsz is undefined.
712 * If cch is non-zero and *ppsz is not NULL, then this
713 * will be used as the output buffer.
714 * VERR_BUFFER_OVERFLOW will be returned if this is
717 * If cch is zero or *ppsz is NULL, then a buffer of
718 * sufficient size is allocated. cch can be used to
719 * specify a minimum size of this buffer. Use
720 * RTUtf16Free() to free the result.
722 * @param cch The buffer size in chars (the type). This includes
724 * @param pcch Where to store the length of the translated string,
725 * excluding the terminator. (Optional)
727 * This may be set under some error conditions,
728 * however, only for VERR_BUFFER_OVERFLOW and
729 * VERR_NO_STR_MEMORY will it contain a valid string
730 * length that can be used to resize the buffer.
732 #define RTUtf16ToLatin1Ex(pwszString, cwcString, ppsz, cch, pcch) \
733 RTUtf16ToLatin1ExTag((pwszString), (cwcString), (ppsz), (cch), (pcch), RTSTR_TAG)
736 * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
737 * or a fittingly sized buffer allocated by the function (custom tag).
739 * @returns iprt status code.
740 * @param pwszString The UTF-16 string to convert.
741 * @param cwcString The number of RTUTF16 items to translate from
742 * pwszString. The translation will stop when reaching
743 * cwcString or the terminator ('\\0'). Use RTSTR_MAX
744 * to translate the entire string.
745 * @param ppsz Pointer to the pointer to the Latin-1 string. The
746 * buffer can optionally be preallocated by the caller.
748 * If cch is zero, *ppsz is undefined.
750 * If cch is non-zero and *ppsz is not NULL, then this
751 * will be used as the output buffer.
752 * VERR_BUFFER_OVERFLOW will be returned if this is
755 * If cch is zero or *ppsz is NULL, then a buffer of
756 * sufficient size is allocated. cch can be used to
757 * specify a minimum size of this buffer. Use
758 * RTUtf16Free() to free the result.
760 * @param cch The buffer size in chars (the type). This includes
762 * @param pcch Where to store the length of the translated string,
763 * excluding the terminator. (Optional)
765 * This may be set under some error conditions,
766 * however, only for VERR_BUFFER_OVERFLOW and
767 * VERR_NO_STR_MEMORY will it contain a valid string
768 * length that can be used to resize the buffer.
769 * @param pszTag Allocation tag used for statistics and such.
771 RTDECL(int) RTUtf16ToLatin1ExTag(PCRTUTF16 pwszString
, size_t cwcString
, char **ppsz
, size_t cch
, size_t *pcch
, const char *pszTag
);
774 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
776 * This function will validate the string, and incorrectly encoded UTF-16
777 * strings will be rejected. The primary purpose of this function is to
778 * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
779 * other purposes RTUtf16ToLatin1Ex() should be used.
781 * @returns Number of char (bytes).
782 * @returns 0 if the string was incorrectly encoded.
783 * @param pwsz The UTF-16 string.
785 RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz
);
788 * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
790 * This function will validate the string, and incorrectly encoded UTF-16
791 * strings will be rejected.
793 * @returns iprt status code.
794 * @param pwsz The string.
795 * @param cwc The max string length. Use RTSTR_MAX to process the
797 * @param pcch Where to store the string length (in bytes). Optional.
798 * This is undefined on failure.
800 RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz
, size_t cwc
, size_t *pcch
);
803 * Get the unicode code point at the given string position.
805 * @returns unicode code point.
806 * @returns RTUNICP_INVALID if the encoding is invalid.
807 * @param pwsz The string.
809 * @remark This is an internal worker for RTUtf16GetCp().
811 RTDECL(RTUNICP
) RTUtf16GetCpInternal(PCRTUTF16 pwsz
);
814 * Get the unicode code point at the given string position.
816 * @returns iprt status code.
817 * @param ppwsz Pointer to the string pointer. This will be updated to
818 * point to the char following the current code point.
819 * @param pCp Where to store the code point.
820 * RTUNICP_INVALID is stored here on failure.
822 * @remark This is an internal worker for RTUtf16GetCpEx().
824 RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16
*ppwsz
, PRTUNICP pCp
);
827 * Put the unicode code point at the given string position
828 * and return the pointer to the char following it.
830 * This function will not consider anything at or following the
831 * buffer area pointed to by pwsz. It is therefore not suitable for
832 * inserting code points into a string, only appending/overwriting.
834 * @returns pointer to the char following the written code point.
835 * @param pwsz The string.
836 * @param CodePoint The code point to write.
837 * This should not be RTUNICP_INVALID or any other
838 * character out of the UTF-16 range.
840 * @remark This is an internal worker for RTUtf16GetCpEx().
842 RTDECL(PRTUTF16
) RTUtf16PutCpInternal(PRTUTF16 pwsz
, RTUNICP CodePoint
);
845 * Get the unicode code point at the given string position.
847 * @returns unicode code point.
848 * @returns RTUNICP_INVALID if the encoding is invalid.
849 * @param pwsz The string.
851 * @remark We optimize this operation by using an inline function for
852 * everything which isn't a surrogate pair or an endian indicator.
854 DECLINLINE(RTUNICP
) RTUtf16GetCp(PCRTUTF16 pwsz
)
856 const RTUTF16 wc
= *pwsz
;
857 if (wc
< 0xd800 || (wc
> 0xdfff && wc
< 0xfffe))
859 return RTUtf16GetCpInternal(pwsz
);
863 * Get the unicode code point at the given string position.
865 * @returns iprt status code.
866 * @param ppwsz Pointer to the string pointer. This will be updated to
867 * point to the char following the current code point.
868 * @param pCp Where to store the code point.
869 * RTUNICP_INVALID is stored here on failure.
871 * @remark We optimize this operation by using an inline function for
872 * everything which isn't a surrogate pair or and endian indicator.
874 DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16
*ppwsz
, PRTUNICP pCp
)
876 const RTUTF16 wc
= **ppwsz
;
877 if (wc
< 0xd800 || (wc
> 0xdfff && wc
< 0xfffe))
883 return RTUtf16GetCpExInternal(ppwsz
, pCp
);
887 * Put the unicode code point at the given string position
888 * and return the pointer to the char following it.
890 * This function will not consider anything at or following the
891 * buffer area pointed to by pwsz. It is therefore not suitable for
892 * inserting code points into a string, only appending/overwriting.
894 * @returns pointer to the char following the written code point.
895 * @param pwsz The string.
896 * @param CodePoint The code point to write.
897 * This should not be RTUNICP_INVALID or any other
898 * character out of the UTF-16 range.
900 * @remark We optimize this operation by using an inline function for
901 * everything which isn't a surrogate pair or and endian indicator.
903 DECLINLINE(PRTUTF16
) RTUtf16PutCp(PRTUTF16 pwsz
, RTUNICP CodePoint
)
905 if (CodePoint
< 0xd800 || (CodePoint
> 0xd800 && CodePoint
< 0xfffe))
907 *pwsz
++ = (RTUTF16
)CodePoint
;
910 return RTUtf16PutCpInternal(pwsz
, CodePoint
);
914 * Skips ahead, past the current code point.
916 * @returns Pointer to the char after the current code point.
917 * @param pwsz Pointer to the current code point.
918 * @remark This will not move the next valid code point, only past the current one.
920 DECLINLINE(PRTUTF16
) RTUtf16NextCp(PCRTUTF16 pwsz
)
923 RTUtf16GetCpEx(&pwsz
, &Cp
);
924 return (PRTUTF16
)pwsz
;
928 * Skips backwards, to the previous code point.
930 * @returns Pointer to the char after the current code point.
931 * @param pwszStart Pointer to the start of the string.
932 * @param pwsz Pointer to the current code point.
934 RTDECL(PRTUTF16
) RTUtf16PrevCp(PCRTUTF16 pwszStart
, PCRTUTF16 pwsz
);
938 * Checks if the UTF-16 char is the high surrogate char (i.e.
939 * the 1st char in the pair).
941 * @returns true if it is.
942 * @returns false if it isn't.
943 * @param wc The character to investigate.
945 DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc
)
947 return wc
>= 0xd800 && wc
<= 0xdbff;
951 * Checks if the UTF-16 char is the low surrogate char (i.e.
952 * the 2nd char in the pair).
954 * @returns true if it is.
955 * @returns false if it isn't.
956 * @param wc The character to investigate.
958 DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc
)
960 return wc
>= 0xdc00 && wc
<= 0xdfff;
965 * Checks if the two UTF-16 chars form a valid surrogate pair.
967 * @returns true if they do.
968 * @returns false if they doesn't.
969 * @param wcHigh The high (1st) character.
970 * @param wcLow The low (2nd) character.
972 DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh
, RTUTF16 wcLow
)
974 return RTUtf16IsHighSurrogate(wcHigh
)
975 && RTUtf16IsLowSurrogate(wcLow
);
979 * Formats a buffer stream as hex bytes.
981 * The default is no separating spaces or line breaks or anything.
983 * @returns IPRT status code.
984 * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
985 * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
987 * @param pwszBuf Output string buffer.
988 * @param cwcBuf The size of the output buffer in RTUTF16 units.
989 * @param pv Pointer to the bytes to stringify.
990 * @param cb The number of bytes to stringify.
991 * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
992 * @sa RTStrPrintHexBytes.
994 RTDECL(int) RTUtf16PrintHexBytes(PRTUTF16 pwszBuf
, size_t cwcBuf
, void const *pv
, size_t cb
, uint32_t fFlags
);