mbsrtowcs, mbsrtowcs_s - cppreference.com (original) (raw)

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 mbrtowc. 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.

1. 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 constraint handler 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 <wchar.h>.

[edit] Parameters

[edit] 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 EILSEQ in errno, 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)

[edit] Example

#include <stdio.h> #include <locale.h> #include <wchar.h> #include <string.h>   void print_as_wide(const char* mbstr) { mbstate_t state; memset(&state, 0, sizeof state); size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state); wchar_t wstr[len]; mbsrtowcs(&wstr[0], &mbstr, len, &state); wprintf(L"Wide string: %ls \n", wstr); wprintf(L"The length, including L'\0': %zu\n", len); }   int main(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

[edit] 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)

[edit] See also