std::wstrin...:from_bytes(3)

🦋 std::wstring_convert::from_bytes 🦋

okay bestie, welcome to the C++ Standard Libary manual page for std::wstring_convert::from_bytes — yes, that’s the manual name exactly as it appears, typo and all, so we’re keeping it 💅. This one lives in <locale> and is all about glamming multibyte bytes into a wide string. ✨

🌸 NAME 🌸

std::wstring_convert::from_bytes - std::wstring_convert::from_bytes

✨ Synopsis ✨

Defined in header <locale>
wide_string from_bytes( char byte );                           (1)
wide_string from_bytes( const char* ptr );                     (2)
wide_string from_bytes( const byte_string& str );              (3)
wide_string from_bytes( const char* first, const char* last ); (4)

It performs multibyte-to-wide conversion, using the codecvt facet supplied at construction. 🫶

1. Converts byte as if it was a string of length 1 to wide_string.
2. Converts the null-terminated multibyte character sequence beginning at the character pointed to by ptr to wide_string.
3. Converts the narrow string str to wide_string.
4. Converts the narrow multibyte character sequence [first, last) to wide_string.

In all cases, the conversion begins in the initial shift state — unless a non-initial starting state was provided to this wstring_convert constructor. The number of characters converted and the final value of the conversion state are remembered, and you can access them with state() and converted(). 🔥

💖 Return value 💖

A wide_string object containing the results of the multibyte-to-wide conversion. If the conversion failed and there was a user-supplied wide-error string provided to the constructor of this wstring_convert, it returns that wide-error string. 🎀

⚠️ Exceptions ⚠️

If this wstring_convert object was constructed without a user-supplied wide-error string, it throws std::range_error on conversion failure. no cap, that’s the rule. 💀

🔥 Example 🔥

The example literally says // Run this code, so run it, bestie:

#include <codecvt>
#include <cstdint>
#include <iostream>
#include <locale>
#include <string>

int main()
{
    std::string utf8 = "z\u00df\u6c34\U0001d10b"; // or u8"zß水𝄋"
                 // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";

    // the UTF-8 / UTF-16 standard conversion facet
    std::u16string utf16 = std::wstring_convert<
        std::codecvt_utf8_utf16<char16_t>,
       char16_t>{}.from_bytes(utf8.data());
    std::cout << "UTF-16 conversion produced " << utf16.size()
              << " code units: " << std::showbase;
    for (char16_t c : utf16)
        std::cout << std::hex << static_cast<std::uint16_t>(c) << ' ';

    // the UTF-8 / UTF-32 standard conversion facet
    std::u32string utf32 = std::wstring_convert<
        std::codecvt_utf8<char32_t>, char32_t>{}.from_bytes(utf8);
    std::cout << "\nUTF-32 conversion produced " << std::dec
              << utf32.size() << " code units: ";
    for (char32_t c : utf32)
        std::cout << std::hex << static_cast<std::uint32_t>(c) << ' ';
    std::cout << '\n';
}

🌈 Output 🌈

UTF-16 conversion produced 5 code units: 0x7a 0xdf 0x6c34 0xd834 0xdd0b
UTF-32 conversion produced 4 code units: 0x7a 0xdf 0x6c34 0x1d10b

👀 See also 👀

• to_bytes — converts a wide string into a byte string (public member function)
• mbsrtowcs — converts a narrow multibyte character string to wide string, given state (function)
• do_in — converts a string from ExternT to InternT, such as when reading from file; [virtual] (virtual protected member function of std::codecvt<InternT,ExternT,StateT>)

mwah 💖 this page came from http://cppreference.com and is dated 2024.06.10 — catch you in the group chat, bestie! 🫶