function
<cstdlib>
mbstowcs
size_t mbstowcs (wchar_t* dest, const char* src, size_t max);
Convert multibyte string to wide-character string
Translates the multibyte sequence pointed by src to the equivalent sequence of wide-characters (which is stored in the array pointed by dest), up until either max wide characters have been translated or until a null character is encountered in the multibyte sequence src (which is also translated and stored, but not counted in the length returned by the function).
If max characters are successfully translated, the resulting string stored in dest is not null-terminated.
The behavior of this function depends on the LC_CTYPE category of the selected C locale.
Parameters
- dest
- Pointer to an array of
wchar_t elements long enough to contain the resulting sequence (at most, max wide characters).
- src
- C-string with the multibyte characters to be interpreted.
The multibyte sequence shall begin in the initial shift state.
- max
- Maximum number of
wchar_t characters to write to dest.
size_t is an unsigned integral type.
Return Value
The number of wide characters written to dest, not including the eventual terminating null character.
If an invalid multibyte character is encountered, a value of (size_t)-1 is returned.
Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.
Data races
The function accesses the array pointed by src, and modifies the array pointed by dest.
The function may also access and modify an internal state object, which may cause data races on concurrent calls to this function if the implementation uses a static object (see mbsrtowcs for an alternative that can use an external state object).
Concurrently changing locale settings may also introduce data races.
Exceptions (C++)
No-throw guarantee: this function throws no exceptions.
If dest does not point to an array long enough to contain the translated sequence, or if src is either not null-terminated or does not contain enough bytes to generate max wide characters (or if it does not begin in the initial shift state), it causes undefined behavior.
See also
- mblen
- Get length of multibyte character (function)
- mbtowc
- Convert multibyte sequence to wide character (function)
- wcstombs
- Convert wide-character string to multibyte string (function)