# std::mbsrtowcs

> C++ Atlas: `cppatlas.com/w/cpp/string/multibyte/mbsrtowcs` | Source: https://en.cppreference.com/w/cpp/string/multibyte/mbsrtowcs | Domain: Strings

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.

## Official Specification Summary (cppreference)

```cpp
// 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 a null pointer 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.

### 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` 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 `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` is a null pointer.

### Example

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

void print_as_wide(const char* mbstr)
{
    std::mbstate_t state = std::mbstate_t();
    std::size_t len = 1 + std::mbsrtowcs(nullptr, &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 = "z\u00df\u6c34\U0001f34c"; // or u8"zß水🍌"
    print_as_wide(mbstr);
}
```

Output:

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

### See also

- [`mbrtowc`](https://en.cppreference.com/w/cpp/string/multibyte/mbrtowc): converts the next multibyte character to wide character, given state (function)
- [`wcsrtombs`](https://en.cppreference.com/w/cpp/string/multibyte/wcsrtombs): converts a wide string to narrow multibyte character string, given state (function)
- [`do_in`](https://en.cppreference.com/w/cpp/locale/codecvt/in) [virtual]: converts a string from `ExternT` to `InternT`, such as when reading from file (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- [C documentation for `mbsrtowcs`](https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs)

---
Attribution: content from https://en.cppreference.com/w/cpp/string/multibyte/mbsrtowcs (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.