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)