C++

参考

<locale>

codecvt

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
将[from,from_end)范围内的字符顺序翻译，并将它们放置在以to开头的范围中。一旦达到to_limit，它将不再尝试存储更多字符。

此成员函数从内部类型翻译到外部类型，这通常是宽字符到多字节的转换（请参阅成员in了解反向操作）。

该函数在无法转换字符时停止转换，或者在到达from_end并且其字符被成功转换后停止。

返回值，以及调用后from_next和to_next的值，可用于评估操作的成功和状态。

在内部，此函数仅调用虚保护成员do_out，该成员默认按上述方式执行。

参数

state
一个 state 对象，如面实例所要求的。
通常，这是一个 mbstate_t 类型的对象，能够跟踪多字节字符转换的移位状态。
成员类型 state_type 是面类型的状态类型（定义为 codecvt 的第三个模板参数 stateT 的别名）。
from, from_end
指向源序列的起始和结束字符的指针。使用的范围是[from,from_end)，它包含from和from_end之间的所有字符，包括from指向的字符，但不包括from_end指向的字符。
请注意，空字符（如果有）也会被翻译，并且函数会继续处理它们直到from_end。
成员类型intern_type是该facet的内部字符类型（定义为codecvt的第一个模板参数internT的别名）。
from_next
能够指向上述范围中元素的指针。函数返回后，此对象指向源范围中最后一个成功翻译元素之后的元素。
to, to_limit
指向目标序列的起始和结束字符的指针。使用的范围最多是[to,to_limit)，它包含to和to_limit之间的所有字符，包括to指向的字符，但不包括to_limit指向的字符。
翻译不一定需要填满整个范围，也可能在完成前耗尽该范围。
不会自动附加额外的空字符（除了从源序列翻译过来的字符）。
成员类型extern_type是该facet的外部字符类型（定义为codecvt的第二个模板参数externT的别名）。
to_next
能够指向上述范围中元素的指针。函数返回后，此对象指向目标范围中最后一个成功翻译元素之后的元素。

返回值

值为 codecvt_base::result 类型，具有以下可能值：
成员常量int 值result
ok0转换成功：所有字符都已翻译。
partial1部分转换：目标序列[to,to_limit)不够长，或者已到达from_end但需要额外的源字符来完成目标字符的转换。
要重置移位状态，请参阅codecvt::unshift。
所有之前的字符都已成功翻译。
error2转换错误：对于from_next指向的字符，不存在有效的转换。
所有之前的字符都已成功翻译。
noconv3无转换：源字符类型和目标字符类型（intern_type和extern_type）相同。未进行转换：源字符已复制到目标。

示例

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;
}

可能的输出

Enter sentence: Test sentence
Translation successful: Test sentence


数据竞争

将访问面对象以及 [from,from_end) 范围内的所有字符。
参数state、from_next和to_next，以及目标范围[to,to_limit)中的最多所有字符都会被修改。

异常安全

如果抛出异常，facet对象将不会发生任何更改，尽管目标范围中的字符和通过引用传递的参数可能会受到影响。

另见

codecvt::in
Translate in characters (public member function)
codecvt::do_out
Translate out characters [virtual] (protected virtual member function)