chsvlib
chsv helper source code

◆ wctou8()

int Chusov::String::wctou8 ( char *  pUtf,
wchar_t  chUcs 
)
noexcept

Determines the number of bytes needed to represent a wide character, expected to be in UCS format, in the UTF-8 format. Optionally, the function stores the representation in a buffer provided by the caller.

Parameters
[out]pUtfis an optional pointer to a buffer where the multibyte equivalent of the wide character can be written. At most UTF8_LEN_MAX bytes are stored. If pUtf is NULL, the function returns 0 indicating a state-independence of the UTF-8 encoding.
[in]chUcsis a wide character given in UCS-2 (or UCS-4 if it is allowed by the wchar_t type) format. If pUtf is not NULL, the wide character is converted to its UTF-8 multibyte equivalent which is stored to the buffer pointed to by the pUtf parameter.
Returns
If the pUtf pointer is NULL, the function returns 0 indicating a state-independence of the UTF-8 (to correspond to the [wcstomb] requirements given by the C standard). If pUtf is not a NULL pointer, the function returns -1 setting errno to EILSEQ, if the chUcs cannot be converted to a UTF-8 code due to its invalid value, or an actual number of bytes of the UTF-8 representation.

A successful call of the function does not guarantee validity of the UTF-8 representation. To verify the code point one should use the u8check_cp function.

The function is built in a portable way to perform the conversion to UTF-8 representation independently of the current locale.

The interface is built similarly to the wctomb function specified by the C standard except for the maximum possible byte length of the UTF-8 characters which is UTF8_MAX_LEN and not MB_CUR_MAX or MB_LEN_MAX.

See also
wctou8_s;
u8towc;
wcstou8s.