chsvlib
chsv helper source code

◆ wcstou8s()

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

Converts a sequence of wide characters, assumed to be in the UCS format, to a sequence of UTF-8 multibyte characters, and writes these characters into a buffer.

Parameters
[out]pUtfis a pointer to an output buffer receiving at most cbUtf bytes of the UTF-8 sequence of multibyte characters. No more than cbUtf bytes of the buffer are modified.
[in]pUcsis a pointer to a string of wide characters in the in UCS-2 format or in the UCS-4 format, if an object of the wchar_t type is large enough to store a UCS-4 character. The function reads elements of the string until cbUtf bytes has been written to the pUtf buffer or a null character has been read from pUcs and written to pUtf.
[in]cbUtfis a maximum number of bytes to be written to the pUtf buffer. No more than that number of bytes will be modified.
Returns
If a wide character in pUcs cannot be represented with a valid UTF-8 character, the function returns (size_t)(-1) (note however that validity of the characters is not guaranteed by a successful return value of the function). Otherwise, the function returns the number of bytes modified, not including a terminating null character, if any. The output string pointed to by pUcs will be null-terminated unless the returned value equals cbUtf.

The function is built in a portable way to perform the conversion independently of the current locale. The interface of the function is otherwise similar to one of the wcstombs function defined by the C standard.

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

See also
wcstou8s_s;
u8stowcs;
wctou8.