public member function

std::wstring_convert::from_bytes

wide_string from_bytes (char byte);wide_string from_bytes (const char* ptr);wide_string from_bytes (const byte_string& str);wide_string from_bytes (const char* first, const char* last);

Convert from bytes

Returns the wide-string equivalent of the byte or sequence of bytes represented by its arguments.

If the wstring_convert object was constructed with no explicit shift state value (constructors (1) and (3)), the shift state is reset before the conversion begins.

Parameters

byte: A single character.
ptr: A C-string (null-terminated character sequence).
str: A string.
byte_string is a member type, defined as an alias of basic_string<char,char_traits<char>,Byte_alloc> (where Byte_alloc is the fourth template parameter of wstring_convert).
first,last: Pointers to the first and past-the-end characters in a sequence. The range converted contains all the characters between first and last, without including the character pointed by last.

Return value

If successful, a wide string with the converted contents.
Otherwise, if the wstring_convert object was constructed with an error wide string (constructor (3)), this error string is returned.
Otherwise, range_error is thrown.

wide_string is a member type, defined as an alias of basic_string<Elem,char_traits<Elem>,Wide_alloc> (where Elem and Wide_alloc are the second and third template parameters of wstring_convert, respectivelly).

The number of characters converted can be accessed with member converted.

Example

// converting from UTF-8 to UTF-32
#include <iostream>       // std::cout, std::hex
#include <string>         // std::string, std::u32string
#include <locale>         // std::wstring_convert
#include <codecvt>        // std::codecvt_utf8
#include <cstdint>        // std::uint_least32_t

int main ()
{
  std::string str8 ("en espa\xc3\xb1ol");    // UTF-8 for "en español"

  std::wstring_convert<std::codecvt_utf8<char32_t>,char32_t> cv;

  std::u32string str32 = cv.from_bytes(str8);

  std::cout << std::hex;

  for (char32_t c : str32) {
    std::cout << '[' << std::uint_least32_t(c) << ']';
  }
  std::cout << '\n';

  return 0;
}

Output:


[65][6e][20][65][73][70][61][f1][6f][6c]

Data races

The wstring_convert object is modified.
Elements in the sequence pointed by the arguments (if any) are accessed.

Exception safety

Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of type range_error if the function fails.

functions

standard facets