本地化库
本地环境设施包含字符分类和字符串校对、数值、货币及日期/时间格式化和分析,以及消息取得的国际化支持。本地环境设置控制流 I/O 、正则表达式库和 C++ 标准库的其他组件的行为。
平面类别
从输入字符序列中解析时间/日期值到 std::tm 中
std::time_get
template< class CharT, |
类模板 std::time_get
封装日期和时间分析规则。 I/O 操纵符 std::get_time 用 I/O 流的 locale 的 std::time_get
平面转换文本输入为 std::tm 对象。
继承图
类型要求
- InputIt 必须满足遗留输入迭代器 (LegacyInputIterator) 的要求。 |
特化
标准库提供二个孤立(独立于本地环境的)全特化和二个部分特化:
定义于头文件 | |
std::time_get<char> | 分析日期和时间的窄字符串表示 |
std::time_get<wchar_t> | 分析日期和时间的宽字符串表示 |
std::time_get<char, InputIt> | 用定制输入迭代器分析日期和时间的窄字符串表示 |
std::time_get<wchar_t, InputIt> | 用定制输入迭代器分析日期和时间的宽字符串表示 |
另外, C++ 程序中构造的每个 locale 对象都实装这些特化的其自身(本地环境限定)版本。
成员类型
成员类型 | 定义 |
char_type | CharT |
iter_type | InputIt |
调用 do_get & 从输入流释出日期/时间组分,按照指定格式
std::time_get<CharT,InputIt>::get,
std::time_get<CharT,InputIt>::do_get
public: iter_type get(iter_type beg, iter_type end, std::ios_base& str, | (1) | (C++11 起) |
protected: virtual iter_type do_get(iter_type beg, iter_type end, std::ios_base& str, | (2) | (C++11 起) |
1) 按照字符序列 [fmtbeg, fmtend) 中提供的格式,从输入字符序列 [beg, end)
分析日期和时间。期待格式遵循描述于下的格式,尽管能通过覆写 do_get
定制每个格式指定符的实际处理。 get
函数进行下列内容: 首先,通过执行 err = std::ios_base::goodbit 清除 err
中的错误位。然后进入循环,凡在任何下列条件变为真时循环终止(以此顺序检查):
a) 已从格式字符串读取全部字符( fmtbeg == fmtend )
b) 有分析错误( err != std::ios_base::goodbit )
c) 已从输入序列读取全部字符( beg == end )。若此条件终止循环,则函数于 err
中一同设置 eofbit
和 failbit
。
循环体中,发生下列步骤:
a) 若格式字符串中的下个字符为 '%' ,后随一或二个组成合法 std::get_time 转换指定符的字符(见下方),则将这些字符用于调用 do_get(beg, end, str, err, t, format, modifier) ,其中 format
为初等转换指定符字符,而 modifier
为可选的修饰符(若存在,则出现于 %
和格式字符间)。若无修饰符,则使用值 '\0' 。若格式字符串有歧义,或过早结束而无以确定 '%' 后的转换指定符,则在 err
中设置 eofbit
并终止循环。若调用 do_get
后 err
中未设置错误位,则函数增加 fmtbeg
到正好指向转换指定符之后,并持续循环。
b) 若下个字符为流 str
中提供的 locale 所指示的空白符(即 std::isspace(*fmtbeg, str.getloc()) == true ),则函数保持自增 fmtbeg
直至它变为等于 fmtend
或指向非空白字符。
c) 若格式字符串中的下个字符按照大小写无关比较,等价于输入流中的下个字符,则函数令二个序列一同前进一个字符 ++fmtbeg, ++beg; 并持续循环。否则它设置 err
中的 failbit
。
2) 从输入序列 [beg, end)
分析一个格式指定符并按照它更新 t
所指向的 std::tm 结构体。
首先,通过执行 err = std::ios_base::goodbit 清除 err
中所有错误位。然后从 [beg, end)
读取 '%' 、 modifier
(若非 '\0' )及 format
所组成的 std::time_get 格式指定符所期待的字符。若字符不组成合法转换指定符,则设置 err
中的 failbit
。若读取一个字符后抵达输入流尾,则设置 err
中的 eofbit
。若成功分析输入字符串,则更新 *t 的对应域。
对于复合转换指定符,如 '%x' 或 '%c' ,或使用修饰符 'E' 和 'O' 的指令,函数可能无法确定存储于 *t 的某些值。该情况下设置 err
中的 eofbit
,并将这些域留在未指定状态。
参数
beg | - | 指代要分析的序列起始的迭代器 |
end | - | 要分析的序列的尾后一位置迭代器 |
str | - | 此函数在需要时用以获得 locale 平面的流对象,例如用 std::ctype 跳过空白符或用 std::collate 比较字符串 |
err | - | 此函数所修改以指示错误的流错误标志对象 |
t | - | 指向 std::tm 对象的指针,该对象将保有此函数调用结果 |
fmtbeg | - | 指向指定转换格式的 char_type 字符序列首字符的指针 格式字符串由零或更多转换指定符、空白符和通常字符(除了 |
转换指定符 | 解释 | 写入域 |
---|---|---|
% | 匹配字面 % 。完整转换指定必须是 %% 。 | (无) |
t | 匹配任何空白符。 | (无) |
n | 匹配任何空白符。 | (无) |
年 | ||
Y | 分析完整年为四位十进制数,容许但不要求前导零 | tm_year |
EY | 以替用表示分析年,例如 平成23年 在 ja_JP 本地环境中写 2011 到 tm_year | tm_year |
y | 分析年的后二位为十进制数。范围 [69,99] 生成 1969 至 1999 的值,范围 [00,68] 生成 2000-2068 | tm_year |
Oy | 以替用数值系统分析年的后二位数字,例如 十一 在 ja_JP 本地环境中被分析为 11 | tm_year |
Ey | 分析年为从本地环境的替用日历周期 %EC 的偏移 | tm_year |
C | 分析年的首 2 位数字为十进制数(范围 [00,99] ) | tm_year |
EC | 分析本地环境的替用表示中,年基底(周期)的名称,例如 ja_JP 中的 平成 | tm_year |
月 | ||
b | 分析月份名,完整或缩写,例如 Oct | tm_mon |
h | b 的同义词 | tm_mon |
B | b 的同义词 | tm_mon |
m | 分析月为十进制数(范围 [01,12] ),容许但不要求前导零 | tm_mon |
Om | 用替代数值系统分析月,例如 ja_JP 本地环境中 十二 分析为 12 | tm_mon |
星期 | ||
U | 分析年之星期为十进制数(星期日是星期的首日)(范围 [00,53] ),容许但不要求前导零 | tm_year , tm_wday , tm_yday |
OU | 用替用数值系统,如以 %U 一般分析年之星期,例如 ja_JP 本地环境中 五十二 分析为 52 | tm_year , tm_wday , tm_yday |
W | 分析年之星期为十进制数(星期一是星期的首日)(范围 [00,53] ),容许但不要求前导零 | tm_year , tm_wday , tm_yday |
OW | 用替用数值系统,如以 %W 一般分析年之星期,例如 ja_JP 本地环境中 五十二 分析为 52 | tm_year , tm_wday , tm_yday |
年/月之日 | ||
j | 分析年之日为十进制数(范围 [001,366] ),容许但不要求前导零 | tm_yday |
d | 分析月之日为十进制数(范围 [01,31] ),容许但不要求前导零 | tm_mday |
Od | 用替用数值系统分析月之日,例如 ja_JP 本地环境中 二十七 分析为 27 ,容许但不要求前导零 | tm_mday |
e | d 的同义词 | tm_mday |
Oe | Od 的同义词 | tm_mday |
星期之日 | ||
a | 分析星期的日名,完整或缩写版,例如 Fri | tm_wday |
A | a 的同义词 | tm_wday |
w | 分析星期之日为十进制数,其中星期日为 0 (范围 [0-6] ) | tm_wday |
Ow | 用替用数值系统分析星期之日为十进制数,其中星期日为 0 ,例如 ja_JP 本地环境中 二 分析为 2 | tm_wday |
时、分、秒 | ||
H | 分析时为十进制数,以 24 小时时钟(范围 [00,23] ) ,容许但不要求前导零 | tm_hour |
OH | 用替用数值系统分析来自 24 小时时钟的时,例如 ja_JP 本地环境中 十八 分析为 18 | tm_hour |
I | 分析时为十进制数,以 12 小时时钟(范围 [01,12] ) ,容许但不要求前导零 | tm_hour |
OI | 用替用数值系统分析时,例如 ja_JP 本地环境中 六 分析为 6 | tm_hour |
M | 分析分为十进制数(范围 [00,59] ),容许但不要求前导零 | tm_min |
OM | 用替用数值系统分析分,例如 ja_JP 本地环境中 二十五 分析为 25 | tm_min |
S | 分析秒为十进制数(范围 [00,60] ),容许但不要求前导零 | tm_sec |
OS | 用替用数值系统分析秒,例如 ja_JP 本地环境中 二十四 分析为 24 | tm_sec |
其他 | ||
c | 分析本地环境的标准日期和时间字符串格式,例如 Sun Oct 17 04:41:13 2010 (本地环境依赖) | 所有 |
Ec | 分析本地环境的替用时期和时间字符串格式,例如期待在 ja_JP 本地环境中以 平成23年 取代 2011年 | 所有 |
x | 分析本地环境的标准日期表示 | 所有 |
Ex | 分析本地环境的替用日期表示,例如期待在 ja_JP 本地环境中以 平成23年 取代 2011年 | 所有 |
X | 分析本地环境的标准时间表示 | 所有 |
EX | 分析本地环境的替用时间表示 | 所有 |
D | 等价于 "%m / %d / %y " | tm_mon , tm_mday , tm_year |
r | 等价于本地环境的标准 12 小时时钟时间( POSIX 中为 "%I : %M : %S %p" ) | tm_hour , tm_min , tm_sec |
R | 等价于 "%H : %M" | tm_hour , tm_min |
T | 等价于 "%H : %M : %S" | tm_hour , tm_min , tm_sec |
p | 分析 a.m. 或 p.m. 的本地环境等价版本 | tm_hour |
注意:不写入 |
fmtend | - | 指定转换格式的 char_type 字符序列的末字符后一位置指针 |
format | - | 指名转换指定符的字符 |
modifier | - | 可出现于 % 和转换指定符间的可选修饰符 |
返回值
指向 [beg, end)
中成功分析的末字符后一位置的迭代器。
注意
格式字符串中非空白非 '%' 字符的大小写无关比较,不要求,但典型地使用 str
所提供的 locale 的 std::collate 平面。
若遇到分析错误,则此函数的多数实现完全不接触 *t
。
这些函数是否清零 *t 中其所不直接设置的域是实现定义的:可移植程序应在调用 get()
前初始化每个域为零。
调用示例 windows
#include <iostream>
#include <sstream>
#include <locale>
#include <iomanip>
#include <vector>
#include <algorithm>
#include <iterator>
#include <Windows.h>std::vector<std::wstring> locals;BOOL CALLBACK MyFuncLocaleEx(LPWSTR pStr, DWORD dwFlags, LPARAM lparam)
{locals.push_back(pStr);return TRUE;
}std::string stows(const std::wstring& ws)
{std::string curLocale = setlocale(LC_ALL, NULL); // curLocale = "C";setlocale(LC_ALL, "chs");const wchar_t* _Source = ws.c_str();size_t _Dsize = 2 * ws.size() + 1;char *_Dest = new char[_Dsize];memset(_Dest, 0, _Dsize);wcstombs(_Dest, _Source, _Dsize);std::string result = _Dest;delete[]_Dest;setlocale(LC_ALL, curLocale.c_str());return result;
}int main()
{EnumSystemLocalesEx(MyFuncLocaleEx, LOCALE_ALTERNATE_SORTS, NULL, NULL);for (std::vector<std::wstring>::const_iterator str = locals.begin();str != locals.end(); ++str){std::istringstream istringstream("2024-05-01 23:12:34");istringstream.imbue(std::locale(stows(*str)));std::cout << "The locale " << istringstream.getloc().name() << ' ';auto& use_facet = std::use_facet<std::time_get<char>>(istringstream.getloc());std::tm tm{};std::string string = "%Y-%M-%d %H:%M:%S";std::ios_base::iostate err = std::ios_base::goodbit;auto ret = use_facet.get({istringstream}, {}, istringstream, err,&tm, &string[0], &string[0] + string.size());istringstream.setstate(err);std::istreambuf_iterator<char> last{};if (istringstream){std::cout << "Successfully parsed as " << std::put_time(&tm, "%c");if (ret != last){std::cout << " Remaining content: ";std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));}else{std::cout << " The input was fully consumed";}}else{std::cout << "Parse failed. Unparsed string: ";std::copy(ret, last, std::ostreambuf_iterator<char>(std::cout));}std::cout << std::endl;}return 0;
}