From cppreference.com
Defined in header
size_tmbsrtowcs(wchar_t*dst,constchar**src,size_tlen,mbstate_t*ps); (1)(since C95)
(until C99)size_tmbsrtowcs(wchar_t*restrictdst,constchar**restrictsrc,size_tlen,mbstate_t*restrictps);(since C99)errno_tmbsrtowcs_s(size_t*restrictretval,wchar_t*restrictdst,rsize_tdstsz,constchar**restrictsrc,rsize_tlen,mbstate_t*restrictps); (2) (since C11)1) Converts a null-terminated multibyte character sequence, which begins in the conversion state described by *ps, from the array whose first element is pointed to by *src to its wide character representation. If dst is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dst. No more than len wide characters are written to the destination array. Each multibyte character is converted as if by a call to
. The conversion stops if:
The multibyte null character was converted and stored. *src is set to null pointer value and *ps represents the initial shift state.
An invalid multibyte character (according to the current C locale) was encountered. *src is set to point at the beginning of the first unconverted multibyte character.
the next wide character to be stored would exceed len. *src is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if dst is a null pointer.
2) Same as (1), except that
the function returns its result as an out-parameter retval
if no null character was written to dst after len wide characters were written, then L'\0' is stored in dst[len], which means len+1 total wide characters are written
the function clobbers the destination array from the terminating null and until dstsz
If src and dst overlap, the behavior is unspecified.
the following errors are detected at runtime and call the currently installed
function:
retval, ps, src, or *src is a null pointer
dstsz or len is greater than RSIZE_MAX/sizeof(wchar_t) (unless dst is null)
dstsz is not zero (unless dst is null)
There is no null character in the first dstsz multibyte characters in the *src array and len is greater than dstsz (unless dst is null)
As with all bounds-checked functions, mbsrtowcs_s is only guaranteed to be available if __STDC_LIB_EXT1__ is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__ to the integer constant 1 before including
.Parameters
dst - pointer to wide character array where the results will be stored src - pointer to pointer to the first element of a null-terminated multibyte string len - number of wide characters available in the array pointed to by dst ps - pointer to the conversion state object dstsz - max number of wide characters that will be written (size of the dst array) retval - pointer to a size_t object where the result will be stored Return value
1) On success, returns the number of wide characters, excluding the terminating L'\0', written to the character array. If dst is a null pointer, returns the number of wide characters that would have been written given unlimited length. On conversion error (if invalid multibyte character was encountered), returns (size_t)-1, stores
in
, and leaves *ps in unspecified state.
2) zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to dst, is stored in *retval), non-sero on error. In case of a runtime constraint violation, stores (size_t)-1 in *retval (unless retval is null) and sets dst[0] to L'\0' (unless dst is null or dstmax is zero or greater than RSIZE_MAX)
Example
Run this code
#include<stdio.h>#include<locale.h>#include<wchar.h>#include<string.h>voidprint_as_wide(constchar*mbstr){mbstate_tstate;memset(&state,0,sizeofstate);size_tlen=1+mbsrtowcs(NULL,&mbstr,0,&state);wchar_twstr[len];mbsrtowcs(&wstr[0],&mbstr,len,&state);wprintf(L"Wide string: %ls \n",wstr);wprintf(L"The length, including L'\\0': %zu\n",len);}intmain(void){setlocale(LC_ALL,"en_US.utf8");print_as_wide(u8"z\u00df\u6c34\U0001f34c");// u8"zß水🍌"}Output:
Wide string: zß水🍌 The length, including L'\0': 5 References
C11 standard (ISO/IEC 9899:2011):
7.29.6.4.1 The mbsrtowcs function (p: 445)
K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649)
C99 standard (ISO/IEC 9899:1999):
7.24.6.4.1 The mbsrtowcs function (p: 391)
See also