# std::mbsrtowcs

From cppreference.com
< cpp‎ | string‎ | multibyte

Defined in header `<cwchar>` |  |
std::size_t mbsrtowcs( wchar_t* dst, const char** src, std::size_t len, std::mbstate_t* ps ); |  |

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 std::mbrtowc. The conversion stops if:

- The multibyte null character was converted and stored. `src` is set to NULL 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==NULL.

### 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

### Return value

On success, returns the number of wide characters, excluding the terminating L'\0', written to the character array.. If dst==NULL, returns the number of wide characters that would have been written given unlimited length.

On conversion error (if invalid multibyte character was encountered), returns static_cast<std::size_t>(-1), stores EILSEQ in errno, and leaves *ps in unspecified state.

### Notes

This function moves the `src` pointer to the end of the converted multibyte string. This doesn't happen if dst==NULL.

### Example

Run this code

    #include <iostream>
    #include <vector>
    #include <clocale>
    #include <cwchar>

    void print_as_wide(const char* mbstr)
    {
        std::mbstate_t state = std::mbstate_t();
        int len = 1 + std::mbsrtowcs(NULL, &mbstr, 0, &state);
        std::vector<wchar_t> wstr(len);
        std::mbsrtowcs(&wstr[0], &mbstr, wstr.size(), &state);
        std::wcout << "Wide string: " << &wstr[0] << '\n'
                   << "The length, including '\\0': " << wstr.size() << '\n';
    }

    int main()
    {
        std::setlocale(LC_ALL, "en_US.utf8");
        const char* mbstr = u8"z\u00df\u6c34\U0001f34c"; // or u8"zß水🍌"
        print_as_wide(mbstr);
    }

Output:

    Wide string: zß水🍌
    The length, including '\0': 5

### See also

mbrtowc | converts the next multibyte character to wide character, given state (function)
wcsrtombs | converts a wide string to narrow multibyte character string, given state (function)
do_in [virtual] | converts a string from externT to internT, such as when reading from file (virtual protected member function of `std::codecvt`)
C documentation for mbsrtowcs

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/string/multibyte/mbsrtowcs&oldid=85896"