public member function
<locale>

std::codecvt::out

result out (state_type& state,   const intern_type* from, const intern_type* from_end, const intern_type*& from_next,        extern_type* to, extern_type* to_limit, extern_type*& to_next) const;
Translate out characters
Translates sequentially the characters in the range [from,from_end) and places them in the range starting at to. It does not attempt to store more characters once to_limit is reached.

This member function translates from intern type to extern type, which typically is a wide character-to-multibyte conversion (see member in for the inverse operation).

The function stops converting as soon as it fails to convert a character, or once from_end is reached and its character is successfully converted.

The return value, along with the values that from_next and to_next have after the call, can be used to evaluate the success and state of the operation.

Internally, this function simply calls the virtual protected member do_out, which behaves as described above by default.

Parameters

state
A state object, as required by the facet instantiation.
Typically, this is an object of type mbstate_t, able to keep track of the shift state of a multibyte character conversion.
Member type state_type is the facet's state type (defined as an alias of codecvt's third template parameter, stateT).
from, from_end
Pointer to the initial and final characters of the source sequence. The range used is [from,from_end), which contains all the characters between from and from_end, including the character pointed by from but not the character pointed by from_end.
Note that null characters (if any) are also translated, and the function proceeds beyond them until from_end.
Member type intern_type is the facet's internal character type (defined as an alias of codecvt's first template parameter, internT).
from_next
Pointer able to point to an element in the above range. Once the function returns, this object points to the element in the source range beyond the last one successfully translated.
to, to_limit
Pointer to the initial and final characters of the destination sequence. The range used is, at most, [to,to_limit), which contains all the characters between to and to_limit, including the character pointed by to but not the character pointed by to_limit.
A translation does not necessarily need to fill up the range to its limit, and may also exhaust it before finishing.
No additional null character is automatically appended (other than those translated from the source sequence).
Member type extern_type is the facet's external character type (defined as an alias of codecvt's second template parameter, externT).
to_next
Pointer able to point to an element in the above range. Once the function returns, this object points to the element in the destination range beyond the last one successfully translated.

Return value

A value of type codecvt_base::result, with the following possible values:
member constantint valueresult
ok0Conversion successful: all characters were translated.
partial1Partial conversion: either the destination sequence [to,to_limit) is not long enough, or from_end has been reached but additional source characters are needed to complete a destination character.
To reset the shift state, see codecvt::unshift.
All previous characters have been successfully translated.
error2Conversion error: No valid conversion existed for the character pointed by from_next.
All previous characters have been successfully translated.
noconv3No conversion: The source and destination character types (intern_type and extern_type) are the same. No conversion attempted: the source characters have been copied to the destination.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// codecvt::out example
#include <iostream>       // std::cout, std::getline, std::wcin
#include <locale>         // std::locale, std::codecvt, std::use_facet
#include <string>         // std::wstring
#include <cwchar>         // std::mbstate_t

int main ()
{
  typedef std::codecvt<wchar_t,char,std::mbstate_t> facet_type;

  std::locale mylocale;

  const facet_type& myfacet = std::use_facet<facet_type>(mylocale);

  std::wstring mywstring;
  std::cout << "Enter sentence: ";
  std::getline (std::wcin,mywstring);

  std::wstring::size_type length = mywstring.length();

  // prepare objects to be filled by codecvt::out :
  char* pstr= new char [length+1];           // the destination buffer (might be too short)
  std::mbstate_t mystate = std::mbstate_t(); // the shift state object
  const wchar_t* pwc;                        // from_next
  char* pc;                                  // to_next

  // call codecvt::out (translate characters):
  facet_type::result myresult = myfacet.out (mystate,
      mywstring.c_str(), mywstring.c_str()+length+1, pwc,
      pstr, pstr+length+1, pc);

  if (myresult==facet_type::ok)
      std::cout << "Translation successful: " << pstr << '\n';

  delete[] pstr;

  return 0;
}

Possible output:

Enter sentence: Test sentence
Translation successful: Test sentence


Data races

The facet object and up to all the characters in the range [from,from_end) are accessed.
The arguments state, from_next and to_next, along with up to all the characters in the range [to,to_limit) are modified.

Exception safety

If an exception is thrown, there are no changes in the facet object, although characters in the destination range and arguments passed by reference may have been affected.

See also