std::c16rtomb - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::c16rtomb

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

Defined in header `<cuchar>` |  |
std::size_t c16rtomb( char* s, char16_t c16, std::mbstate_t* ps ); |  | (since C++11)

Converts a UCS-2 code point to narrow multibyte character.

If `s` is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of `c16` (including any shift sequences), and stores the multibyte character representation in the character array whose first element is pointed to by `s`. At most MB_CUR_MAX bytes can be written by this function.

If `s` is a null pointer, the call is equivalent to std::c16rtomb(buf, u'\0', ps) for some internal buffer `buf`.

If c16 is the null wide character u'\0', a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter *ps is updated to represent the initial shift state.

The multibyte encoding used by this function is specified by the currently active C locale.

### [edit] Parameters

s | - | pointer to narrow character array where the multibyte character will be stored
c16 | - | the 16-bit character to convert
ps | - | pointer to the conversion state object used when interpreting the multibyte string

### [edit] Return value

On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by `s`. This value may be ​0​, e.g. when processing the first char16_t in a surrogate pair.

On failure (if c16 is not a valid 16-bit character), returns -1, stores EILSEQ in errno, and leaves *ps in unspecified state.

### [edit] Notes

Unlike std::mbrtoc16, which converts variable-width multibyte (such as UTF-8) to variable-width 16-bit (such as UTF-16) encoding, this function can only convert single-unit 16-bit encoding, meaning it cannot convert UTF-16 to UTF-8.

### [edit] Example

Run this code

    #include <iostream>
    #include <iomanip>
    #include <clocale>
    #include <cuchar>
    #include <cstdlib>

    int main()
    {
        std::setlocale(LC_ALL, "en_US.utf8");
        std::u16string str = u"zß水";
        std::cout << "Processing " << str.size() << " UTF-16 code units: [ ";
        for(char16_t c : str) std::cout << std::showbase << std::hex << c << ' ';
        std::cout << "]\n";

        std::mbstate_t state{};
        std::string out(MB_CUR_MAX, '\0');
        for(size_t n = 0; n < str.size(); ++n)
        {
            int rc = std::c16rtomb(&out[0], str[n], &state);
            std::cout << str[n] << " converted to [ ";
            for(int x = 0; x < rc; ++x) std::cout << +(unsigned char)out[x] << ' ';
            std::cout << "]\n";
        }
    }

Output:

    Processing 3 UTF-16 code units: [ 0x7a 0xdf 0x6c34 ]
    0x7a converted to [ 0x7a ]
    0xdf converted to [ 0xc3 0x9f ]
    0x6c34 converted to [ 0xe6 0xb0 0xb4 ]

### [edit] See also

mbrtoc16 (C++11) | generate the next 16-bit wide character from a narrow multibyte string (function) [edit]
do_out [virtual] | converts a string from internT to externT, such as when writing to file (virtual protected member function of `std::codecvt`) [edit]
C documentation for c16rtomb

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