chsvlib
chsv helper source code

◆ u8stowcs()

std:: size_t Chusov::String::u8stowcs ( wchar_t *restrict  pUcs,
const char *restrict  pUtf,
std::size_t  cchChars 
)
noexcept

Converts the specified sequence of UTF-8 characters into a sequence of corresponding wide characters in the UCS format and writes at most the specified number of wide characters to a buffer.

Parameters
[out]pUcsis a pointer to an output buffer receiving at most cchChars wide characters of the UCS-2 (or UCS-4, if an object of the wchar_t type is large enough to contain UCS-4 characters) string, the UTF-8 string is converted to.
[in]pUtfis a pointer to a UTF-8 string to be converted to its UCS-2 (or UCS-4) equivalent. No UTF-8 characters that follow a null character (which is converted into a null wide character) will be examined or converted.
[in]cchCharsis a maximum number of characters to be written to the buffer pointed to by the pUcs parameter. No more than that number of elements will be modified.
Returns
If an invalid UTF-8 character is encountered so that its conversion cannot be performed, the function returns (size_t)(-1) and sets errno to EILSEQ. Otherwise, the function returns the number of wide characters written to the pUcs array, not including a terminating null wide character, if any. The array will not be null-terminated if the value returned equals cchChars. Note that a successful return value by itself does not guarantee the validity of all UTF-8 codes nor the validity of the resulting wide characters.

The function is built in a portable way to perform the conversion of a UTF-8 code string to a string of wide characters independently of the current locale. The wide characters are generated in the UCS-2 format or, if a wchar_t object can hold UCS-4 values, in the UCS-4 format.

A successful execution of the function does not guarantee that all UTF-8 codes of the input string or the resulting wide characters are in a valid state as defined by the Unicode 11.0 standard. However, this verification is performed by the bound-checking alternative u8stowcs_s.

See also
u8stowcs_s;
wcstou8s;
u8towc.