# std::codecvt_utf16

> C++ Atlas: `cppatlas.com/w/cpp/locale/codecvt_utf16` | Source: https://en.cppreference.com/w/cpp/locale/codecvt_utf16 | Domain: Localization | Standards: C++11, C++17, C++26

std::codecvt_utf16 is a std::codecvt facet which encapsulates conversion between a UTF-16 encoded byte string and UCS-2 or UTF-32 character string (depending on the type of Elem).

## Official Specification Summary (cppreference)

```cpp
// Defined in header <codecvt>

template<
    class Elem,
    unsigned long Maxcode = 0x10ffff,
    std::codecvt_mode Mode = (std::codecvt_mode)0 >
class codecvt_utf16
    : public std::codecvt<Elem, char, std::mbstate_t>; // (since C++11) (deprecated in C++17) (removed in C++26)
```

`std::codecvt_utf16` is a `std::codecvt` facet which encapsulates conversion between a UTF-16 encoded byte string and UCS-2 or UTF-32 character string (depending on the type of `Elem`). This `std::codecvt` facet can be used to read and write UTF-16 files in binary mode.

UCS-2 is an archaic encoding that is a subset of UTF-16, which encodes scalar values in the range U+0000-U+FFFF (Basic Multilingual Plane) only.

#### Template Parameters

- `Elem` - either `char16_t`, `char32_t`, or `wchar_t`
- `Maxcode` - the largest value of `Elem` that this facet will read or write without error
- `Mode` - a constant of type `std::codecvt_mode`

#### Member functions

- (constructor): constructs a new `codecvt_utf16` facet (public member function)
- (destructor): destroys a `codecvt_utf16` facet (public member function)

### std::codecvt_utf16::codecvt_utf16

```cpp
explicit codecvt_utf16( std::size_t refs = 0 );
```

Constructs a new `std::codecvt_utf16` facet, passes the initial reference counter `refs` to the base class.

#### Parameters

- `refs` - the number of references that link to the facet

### std::codecvt_utf16::~codecvt_utf16

```cpp
~codecvt_utf16();
```

Destroys the facet. Unlike the locale-managed facets, this facet's destructor is public.

### Inherited from std::codecvt

#### Nested types

**Type — Definition**

- `intern_type`: `internT`
- `extern_type`: `externT`
- `state_type`: `stateT`

#### Data members

**Member — Description**

- `std::locale::id` `id` [static]: the identifier of the facet

#### Member functions

- `out`: invokes `do_out` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `in`: invokes `do_in` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `unshift`: invokes `do_unshift` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `encoding`: invokes `do_encoding` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `always_noconv`: invokes `do_always_noconv` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `length`: invokes `do_length` (public member function of `std::codecvt<InternT,ExternT,StateT>`)
- `max_length`: invokes `do_max_length` (public member function of `std::codecvt<InternT,ExternT,StateT>`)

#### Protected member functions

- `do_out` [virtual]: converts a string from `InternT` to `ExternT`, such as when writing to file (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- `do_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>`)
- `do_unshift` [virtual]: generates the termination character sequence of `ExternT` characters for incomplete conversion (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- `do_encoding` [virtual]: returns the number of `ExternT` characters necessary to produce one `InternT` character, if constant (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- `do_always_noconv` [virtual]: tests if the facet encodes an identity conversion for all valid argument values (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- `do_length` [virtual]: calculates the length of the `ExternT` string that would be consumed by conversion into given `InternT` buffer (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)
- `do_max_length` [virtual]: returns the maximum number of `ExternT` characters that could be converted into a single `InternT` character (virtual protected member function of `std::codecvt<InternT,ExternT,StateT>`)

### Inherited from std::codecvt_base

**Nested type — Definition**

- `enum result { ok, partial, error, noconv };`: Unscoped enumeration type

**Enumeration constant — Definition**

- `ok`: conversion was completed with no error
- `partial`: not all source characters were converted
- `error`: encountered an invalid character
- `noconv`: no conversion required, input and output types are the same

#### Notes

Although the standard requires that this facet works with UCS-2 when the size of `Elem` is 16 bits, some implementations use UTF-16 instead, making this a non-converting locale. The term "UCS-2" was deprecated and removed from ISO 10646.

#### Example

The following example demonstrates decoding of UTF-16le file on a system with 32-bit `wchar_t`. On a system with 16-bit `wchar_t`, decoding of the third character will fail because `std::codecvt_utf16<char16_t>` produces UCS-2, not UTF-16.

```cpp
#include <codecvt>
#include <cwchar>
#include <fstream>
#include <iostream>
#include <locale>
#include <string>

void prepare_file()
{
    // UTF-16le data (if host system is little-endian)
    char16_t utf16le[4] = {0x007a,          // latin small letter 'z' U+007a
                           0x6c34,          // CJK ideograph "water"  U+6c34
                           0xd834, 0xdd0b}; // musical sign segno U+1d10b

    // store in a file
    std::ofstream fout("text.txt");
    fout.write(reinterpret_cast<char*>(utf16le), sizeof utf16le);
}

int main()
{
    prepare_file();
    // open as a byte stream
    std::wifstream fin("text.txt", std::ios::binary);
    // apply facet
    fin.imbue(std::locale(fin.getloc(),
        new std::codecvt_utf16<wchar_t, 0x10ffff, std::little_endian>));

    wchar_t c = 0;
    for (std::cout << std::showbase << std::hex; fin.get(c);
         std::cout << static_cast<std::wint_t>(c) << '\n');
}
```

Output:

```text
0x7a
0x6c34
0x1d10b
```

#### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 2229 | C++98 | the constructor and destructor were not specified | specifies them |

#### See also

| Character conversions | locale-defined multibyte (UTF-8, GB18030) | UTF-8 | UTF-16 |
| --- | --- | --- | --- |
| UTF-16 | [`mbrtoc16`](https://en.cppreference.com/w/cpp/string/multibyte/mbrtoc16) / [`c16rtomb`](https://en.cppreference.com/w/cpp/string/multibyte/c16rtomb) (with C11's DR488) | [`codecvt`](https://en.cppreference.com/w/cpp/locale/codecvt)`<char16_t,char,mbstate_t>` [`codecvt_utf8_utf16`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8_utf16)`<char16_t>` [`codecvt_utf8_utf16`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8_utf16)`<char32_t>` [`codecvt_utf8_utf16`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8_utf16)`<wchar_t>` | N/A |
| UCS-2 | [`c16rtomb`](https://en.cppreference.com/w/cpp/string/multibyte/c16rtomb) (without C11's DR488) | [`codecvt_utf8`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8)`<char16_t>` | `codecvt_utf16<char16_t>` |
| UTF-32 | [`mbrtoc32`](https://en.cppreference.com/w/cpp/string/multibyte/mbrtoc32) / [`c32rtomb`](https://en.cppreference.com/w/cpp/string/multibyte/c32rtomb) | [`codecvt`](https://en.cppreference.com/w/cpp/locale/codecvt)`<char32_t,char,mbstate_t>` [`codecvt_utf8`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8)`<char32_t>` | `codecvt_utf16<char32_t>` |
| system `wchar_t`: UTF-32 (non-Windows) UCS-2 (Windows) | [`mbsrtowcs`](https://en.cppreference.com/w/cpp/string/multibyte/mbsrtowcs) / [`wcsrtombs`](https://en.cppreference.com/w/cpp/string/multibyte/wcsrtombs) [`use_facet`](https://en.cppreference.com/w/cpp/locale/use_facet)`<`[`codecvt`](https://en.cppreference.com/w/cpp/locale/codecvt) `<wchar_t,char,mbstate_t>>`([`locale`](https://en.cppreference.com/w/cpp/locale/locale)) | [`codecvt_utf8`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8)`<wchar_t>` | `codecvt_utf16<wchar_t>` |

- [`codecvt`](https://en.cppreference.com/w/cpp/locale/codecvt): converts between character encodings, including UTF-8, UTF-16, UTF-32 (class template)
- [`codecvt_mode`](https://en.cppreference.com/w/cpp/locale/codecvt_mode) (C++11): tags to alter behavior of the standard codecvt facets (enum)
- [`codecvt_utf8`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8) (C++11): converts between UTF-8 and UCS-2/UCS-4 (class template)
- [`codecvt_utf8_utf16`](https://en.cppreference.com/w/cpp/locale/codecvt_utf8_utf16) (C++11): converts between UTF-8 and UTF-16 (class template)

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