public member function
<locale>

std::codecvt::in

result in (state_type& state,   const extern_type* from, const extern_type* from_end, const extern_type*& from_next,        intern_type* to, intern_type* to_limit, intern_type*& to_next) const;
将字符转换为内部编码
将范围 [from,from_end) 中的字符顺序转换为内部编码,并将结果放入以 to 开头的范围中。一旦达到 to_limit,则不再尝试存储更多字符。

此成员函数将字符从外部类型转换为内部类型,这通常是多字节到宽字符的转换(请参阅成员 in 进行反向操作)。

只要无法转换字符,或者到达 from_end 且其字符已成功转换,该函数就会停止转换。

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

在内部,此函数仅调用虚拟受保护成员 do_in,该成员默认执行上述操作。

参数

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

返回值

值为 codecvt_base::result 类型,具有以下可能值:
成员常量intresult
ok0转换成功:所有字符均已转换。
partial1部分转换:目标序列 [to,to_limit) 不够长,或者已到达 from_end 但仍需要更多源字符才能完成目标字符的转换。
所有之前的字符都已成功转换。
error2转换错误: from_next 指向的字符不存在有效的转换。
所有之前的字符都已成功转换。
noconv3无转换:源字符类型和目标字符类型(intern_typeextern_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
// codecvt::in example
#include <iostream>       // std::wcout, std::wcout
#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);

  const char mystr[] = "Test string";

  // prepare objects to be filled by codecvt::in :
  wchar_t pwstr[sizeof(mystr)];              // the destination buffer (might be too short)
  std::mbstate_t mystate = std::mbstate_t(); // the shift state object
  const char* pc;                            // from_next
  wchar_t* pwc;                              // to_next

  // translate characters:
  facet_type::result myresult = myfacet.in (mystate,
      mystr, mystr+sizeof(mystr), pc,
      pwstr, pwstr+sizeof(mystr), pwc);

  if ( myresult == facet_type::ok )
  {
    std::wcout << L"Translation successful: ";
    std::wcout << pwstr << std::endl;
  }
  return 0;
}

输出

Translation successful: Test string


数据竞争

将访问面对象以及 [from,from_end) 范围内的所有字符。
参数 statefrom_nextto_next 以及目标范围 [to,to_limit) 中的所有字符都会被修改。

异常安全

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

另见