Date Time Input/Output

日期時間的輸入/輸出

格式化標誌
日期 Facet
日期輸入 Facet
時間 Facet
時間輸入 Facet
日期時間格式化器/分析器對像
日期時間 IO 指南

日期時間 IO 系統

和版本1.33一樣，本 date_time 庫使用了一個新的流IO系統。這個新系統可以讓用戶控制如何表示日期和時間。定制化的選項可分為兩組：格式化標誌和字符串元素。格式化標誌提供了日期各元素順序和類型的靈活性。而對字符串元素進行客戶化可以在IO時替換內建的月份名、星期名和其它字符串。

輸出系統基於一個 date_facet (派生自 std::facet)，而輸入系統則基於一個 date_input_facet (也是派生自 std::facet)。而時間和 local_time 的 facets 則派生自這兩個類型。輸出系統使用了三個格式化器對象，而輸入系統則使用四個分析器對象。這些格式化器和分析器對象都是可定制化的。

有一點很重要，後面所提供的所有例子均使用了窄字符流，而系統同樣提供了寬字符流的 facets (完整的列表請見 IO 對像)。

還要注意的是，不是所有編譯器都能夠使用這個IO系統。對於那些編譯器，以前的 date_time 版本所使用的IO系統依然可用。對於這些編譯器，系統將自動選擇"舊的IO系統"，不過也可以通過定義 USE_DATE_TIME_PRE_1_33_FACET_IO 來人工選擇使用舊IO系統。更多信息請見構建及編譯器信息。

流的異常處理

在進行流輸入時，如果發生了錯誤，那麼流中的 std::ios_base::failbit 將(總是)被置位。也可以在發生錯誤時拋出異常。要"開啟"這些異常的拋出，請以 std::ios_base::failbit 作為參數調用流的 exceptions 函數。

// "開啟"異常
date d(not_a_date_time);
std::stringstream ss;
ss.exceptions(std::ios_base::failbit);
ss.str("204-Jan-01");
ss >> d; // 拋出 bad_year 異常並設置流的 failbit

新系統的一個簡單例子：

//例子：定制輸出為 "LongWeekday LongMonthname day, year"
//                                  "%A %b %d, %Y"
date d(2005,Jun,25);
date_facet* facet(new date_facet("%A %B %d, %Y"));
std::cout.imbue(std::locale(std::cout.getloc(), facet));
std::cout << d << std::endl;
// "Saturday June 25, 2005"

格式化標誌

這個新的IO系統用於輸出的格式化標誌中，多數都是由 strftime(...) 使用的，但不是全部。增加了一些新的標誌，還覆蓋了一些。輸入系統只支持一些特定的標誌，因此，不是所有用於輸出的標誌都可用於輸入(我們正在為改善這一情況而努力)。

下面兩個表列出了 date_time IO 和 strftime 可用的所有標誌。標有星號(*)的格式化標誌只用於 date_time. 標有感歎號(!)的標誌不可用於輸入(目前)。第一個表是用於日期的IO，第二個表則用於時間的IO。

日期 Facet 格式化標誌

格式化符	說明
格式化符	例子
%a	縮寫的星期名
%a	"Mon" => Monday
%A	長星期名
%A	"Monday"
%b	縮寫的月份名
%b	"Feb" => February
%B	長月份名
%B	"February"
%c !	當前 locale 的首選日期時間表示法。
%c !
%C !	世紀數(year/100)為2位數字的整數。
%C !
%d	月份中的天數為十進制的 01 到 31
%d
%D !	等價於 %m/%d/%y
%D !
%e	類似於 %d, 月份中的天數為十進制數，但前導的0換為空格。
%e
%G !	與 %y 具有相同的格式和值，除了當ISO星期數屬於前一個或後一個年份時，替換相應年份。
%G !
%g !	類似於 %G, 但不帶世紀數。
%g !
%h !	等價於 %b
%h !
%j	在年份中的天數為十進制數，閏年時為 001 到 366，非閏年時為 001 - 365。
%j	"060" => Feb-29
%m	月份名為十進制數，從 01 到 12
%m	"01" => January
%u !	在星期中的天數為十進制數，範圍為 1 到 7，星期一為1。
%u !
%U	在當前年份中的周數，以十進製表示，範圍從 00 到 53，第一個星期天作為第01周的第一天。如2005年1月1日為星期六，則這一天屬於2005年的第00周(第00周為 2004-Dec-26 到 2005-Jan-01. 同時這也是2004年的第53周)。
%U	date d(2005, Jan, 1); // 星期六 // 格式化為 %U ss << d; // "00" d += day(1); // 星期天 ss << d; // "01" 第1周的開始
%V !	在當前年份中的 ISO 8601:1988 周數，以十進製表示，範圍從 01 到 53，其中第1周為至少有4天在本年內的第一周，以星期一作為一周的第一天。
%V !
%w	在一周中的天數，為十進制的 0 到 6
%w	"0" => 星期天
%W	周數，從 00 到 53，其中星期一為一周的第一天。
%W	date d(2005, Jan, 2); // 星期天 // 格式化為 %W ss << d; // "00" d += day(1); // 星期一 ss << d; // "01" 第1周的開始
%x	由實現的 locale 所定義的數據格式。
%x	date d(2005,Oct,31); date_facet* f = new date_facet("%x"); locale loc = locale(locale("en_US"), f); cout.imbue(loc); cout << d; // "10/31/2005" loc = locale(locale("de_DE"), f); cout.imbue(loc); cout << d; // "31.10.2005"
%y	兩位數的年份
%y	"05" => 2005
%Y	四位數的年份
%Y	"2005"
%Y-%b-%d	缺省日期格式
%Y-%b-%d	"2005-Apr-01"
%Y%m%d	ISO 格式
%Y%m%d	"20050401"
%Y-%m-%d	ISO 擴展格式
%Y-%m-%d	"2005-04-01"

時間 Facet 格式化標誌

格式化符	說明
格式化符	例子
%- *!	佔位符，表示時間長度的符號。只在時間長度為負時顯示。
%- *!	"-13:15:16"
%+ *!	佔位符，表示時間長度的符號。不論正負都會顯示。
%+ *!	"+13:15:16"
%f	總是顯示秒數的小數部分，即使小數部分為零。
%f	"13:15:16.000000"
%F *	僅在小數部分不為零時顯示秒數的小數部分。
%F *	"13:15:16" "05:04:03.001234"
%I !	小時數為十進制數，使用12小時的時鐘。
%I !
%k !	小時數(24小時時鐘)以十進制數表示(從0到23)；單位數字前加空格。
%k !
%l !	小時數(12小時時鐘)以十進制數表示(從1到12)；單位數字前加空格。
%l !
%p !	根據給定的時間值顯示 `AM' 或 `PM'，或當前 locale 的相應字符串。
%p !
%P !	類似於 %p，但輸出小寫的 `am' 或 `pm' 或當前 locale 的相應字符串。
%P !
%r !	時間帶 a.m. 或 p.m. 符號。在 POSIX locale 中相當於 `%I:%M:%S %p'
%r !
%R !	時間為24-小時格式(%H:%M)
%R !
%s *	秒數帶小數部分。
%s *	"59.000000"
%S	只輸出小數
%S	"59"
%T !	時間為24-小時格式(%H:%M:%S)
%T !
%q	ISO 時區(僅用於輸出)。在對 ptime 使用 time_facet 時忽略該標誌。
%q	"-0700" // Mountain Standard Time
%Q	ISO 擴展時區(僅用於輸出)。在對 ptime 使用 time_facet 時忽略該標誌。
%Q	"-05:00" // Eastern Standard Time
%z *!	時區縮寫(僅用於輸出)。在對 ptime 使用 time_facet 時忽略該標誌。
%z *!	"MST" // Mountain Standard Time
%Z *!	時區全名(僅用於輸出)。在對 ptime 使用 time_facet 時忽略該標誌。
%Z *!	"EDT" // Eastern Daylight Time
%ZP *	Posix 時區字符串(可用於輸入和輸出)。在對 ptime 使用 time_facet 時忽略該標誌。有關 posix 時區字符串的完整細節，請見 posix_time_zone 類。
%ZP *	"EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
%x %X	取自於 locale 的實現定義的日期/時間格式。
%x %X	date d(2005,Oct,31); ptime pt(d, hours(20)); time_facet* f = new time_facet("%x %X"); locale loc = locale(locale("en_US"), f); cout.imbue(loc); cout << pt; // "10/31/2005 08:00:00 PM" loc = locale(locale("de_DE"), f); cout.imbue(loc); cout << pt; // "31.10.2005 20:00:00"
%Y%m%dT%H%M%S%F%q	ISO 格式。
%Y%m%dT%H%M%S%F%q	"20051015T131211-0700" // Oct 15, 2005 13:12:11 MST
%Y-%m-%d %H:%M:%S%F%Q	擴展 ISO 格式。
%Y-%m-%d %H:%M:%S%F%Q	"2005-10-15 13:12:11-07:00"
%Y-%b-%d %H:%M:%S%F %z	輸出 ptime 和 local_date_time 時使用的缺省格式。
%Y-%b-%d %H:%M:%S%F %z	"2005-Oct-15 13:12:11 MST"
%Y-%b-%d %H:%M:%S%F %ZP	輸入 ptime 和 local_date_time 時使用的缺省格式。
%Y-%b-%d %H:%M:%S%F %ZP	"2005-Oct-15 13:12:11 MST-07"
%-%H:%M:%S%F !	用於輸出的缺省 time_duration 格式。僅當時間長度為負時顯示符號。
%-%H:%M:%S%F !	"-13:14:15.003400"
%H:%M:%S%F	用於輸入的缺省 time_duration 格式。
%H:%M:%S%F	"13:14:15.003400"

* 表示該標誌只用於 date_time.

! 表示該標誌不可用於輸入。

下表列出了可用的 facets.

IO 對像

輸出	輸入
`date_facet`	`date_input_facet`
`wdate_facet`	`wdate_input_facet`
`time_facet`	`time_input_facet`
`wtime_facet`	`wtime_input_facet`
`local_time_facet`*	`local_time_input_facet`*
`wlocal_time_facet`*	`wlocal_time_input_facet`*

* 這些鏈接引向 time_facet 和 time_input_facet 參考一節。它們不是真正的類而是 typedefs.

格式化器/分析器對像

為了實現新的 new i/o facets，date-time 庫使用了多個新分析器和格式化器。這些類可以讓用戶實現特定的輸入/輸出程序。

輸出	輸入
`period_formatter`	`period_parser`
`date_generator_formatter`	`date_generator_parser`
`special_values_formatter`	`special_values_parser`
	`format_date_parser`

日期 Facet

簡介 - 構造 - 訪問器

簡介

boost::date_time::date_facet 讓用戶可以對日期(以及其它格里曆對像)的流輸出進行控制。date_facet 被 typedef 為 gregorian 名字空間中的 date_facet 和 wdate_facet.

構造

語法	說明
date_facet()	缺省構造函數。
date_facet(...) Parameters: char_type* format input_collection_type	format 指定了用於日期輸出的格式。其它格式將使用它們的缺省值。Collection 是用於月份的一組縮寫名。其它的名字使用其缺省值。
date_facet(...) Parameters: char_type* format period_formatter_type special_values_formatter_type date_gen_formatter_type	format 指定了用於日期輸出的格式。其餘參數為格式化器對象。有關這些對象的更多詳情請看這裡。這個構造函數為 format 以外的所有參數提供了缺省值。因此，可以使用 `date_facet("%m %d %Y")`.

訪問器

語法	說明
語法	例子
void format(char_type*)	設置日期的格式。
void format(char_type*)	date_facet* f = new date_facet(); f->format("%m %d %Y");
void set_iso_format()	設置 ISO 格式。
void set_iso_format()	f->set_iso_format(); // "%Y%m%d"
void set_iso_extended_format()	設置 ISO 擴展的日期格式。
void set_iso_extended_format()	f->set_iso_extended_format(); // "%Y-%m-%d"
void month_format(char_type*)	設置單獨輸出月份的格式。
void month_format(char_type*)	f->month_format("%B"); ss << greg_month(12); // "December"
void weekday_format(char_type*)	設置單獨輸出週日的格式。
void weekday_format(char_type*)	f->weekday_format("%a"); ss << greg_weekday(2); // "Tue"
void period_formatter(...) Parameter: period_formatter_type	以用戶創建的對象替換時間段格式化器對象。
void period_formatter(...) Parameter: period_formatter_type	完整的例子請見指南。
void special_values_formatter(...) Parameter: special_values_formatter_type	以用戶創建的對象替換 special_values 格式化器對象。
	完整的例子請見指南。
void date_gen_phrase_strings(...) Parameters: input_collection_type date_gen_formatter_type:: phrase_elements	在 date_gen_formatter 中設置新的日期生成器短語串。其中 input collection 是一個字符串 vector(有關這些字符串的具體說明請見日期生成器格式化器/分析器的文檔)。參數 phrase_elements 為枚舉類型，在 date_generator_formatter 對像中定義，其缺省值為 'first'. 它用於表示在 collection 第一個字符串的位置。

void short_weekday_names(...) Parameter: input_collection_type	替換輸出短週日名時使用的字符串。
	完整的例子請見指南。
void long_weekday_names(...) Parameter: input_collection_type	替換輸出長週日名時使用的字符串。
	完整的例子請見指南。
void short_month_names(...) Parameter: input_collection_type	替換輸出短月份名時使用的字符串。
	完整的例子請見指南。
void long_month_names(...) Parameter: input_collection_type	替換輸出長月份名時使用的字符串。
void long_month_names(...) Parameter: input_collection_type	完整的例子請見指南。
OutItrT put(...) Common parameters for all 'put' functions: OutItrT ios_base char_type Unique parameter for 'put' funcs: gregorian object	在 date_facet 中有12個 put 函數。它們的共同參數是：一個指向流中下一項的迭代器，一個 ios_base 對象，以及填充字符。每個格里曆對象都有它自己的 put 函數。每個 put 函數的描述如下。

OutItrT put(..., date)	使用由 `format(...)` 設置的格式或缺省格式將一個日期放入輸出到流中。
OutItrT put(..., date)
OutItrT put(..., days)	將一個 days 對像作為一個數字放入流中。
OutItrT put(..., days)
OutItrT put(..., month)	將一個 month 對像放入流中，使用由 `month_format(...)` 設置的格式或者缺省格式。
OutItrT put(..., month)
OutItrT put(..., day)	將一個 day of month 對像作為一個兩位數放入流中。
OutItrT put(..., day)	"01" // 1月1日
OutItrT put(..., day_of_week)	將一個 day of week 對像放入流中，使用由 `weekday_format(...)` 設置的格式或缺省格式。
OutItrT put(..., day_of_week)
OutItrT put(..., date_period)	將一個 date_period 放入流中。日期的格式使用 `format(..)` 設置的格式或缺省格式。period 的類型(開或閉區間)以及所使用的分隔符就是 period_formatter 所使用的。
OutItrT put(..., date_period)
OutItrT put(..., partial_date)	將一個 partial_date date_generator 對像放入流中。所使用的月份格式為由 `month_format(..)` 所設置的格式或缺省格式。day of month 用兩位數表示。
OutItrT put(..., partial_date)	"01 Jan" // 缺省格式 "01 January" // 長月份名格式
OutItrT put(..., date_generator) Date Generator Type: nth_day_of_the_week_in_month	將一個 nth_day_of_the_week_in_month 對像放入流中。月份的格式由 `month_format(...)` 設置或採用缺省格式。weekday 的格式由 `weekday_format(...)` 設置或採用缺省格式。其它短語元素在 date_generator_formatter 中設置。
	"third Fri in May" // 缺省
OutItrT put(..., date_generator) Date Generator Type: first_day_of_the_week_in_month	將一個 first_day_of_the_week_in_month 對像放入流中。月份的格式由 `month_format(...)` 設置或採用缺省格式。weekday 的格式由 `weekday_format(...)` 設置或採用缺省格式。其它短語元素在 date_generator_formatter 中設置。
	"first Wed of Jun" // 缺省
OutItrT put(..., date_generator) Date Generator Type: last_day_of_the_week_in_month	將一個 last_day_of_the_week_in_month 對像放入流中。月份的格式由 `month_format(...)` 設置或採用缺省格式。weekday 的格式由 `weekday_format(...)` 設置或採用缺省格式。其它短語元素在 date_generator_formatter 中設置。
	"last Tue of Mar" // 缺省
OutItrT put(..., date_generator) Date Generator Type: first_day_of_the_week_after	將一個 first_day_of_the_week_after 對像放入流中。weekday 的格式由 `weekday_format(...)` 設置或採用缺省格式。其它短語元素在 date_generator_formatter 中設置。
	"first Sat after" // 缺省
OutItrT put(..., date_generator) Date Generator Type: first_day_of_the_week_before	將一個 first_day_of_the_week_before 對像放入流中。weekday 的格式由 `weekday_format(...)` 設置或採用缺省格式。其它短語元素在 date_generator_formatter 中設置。
	"first Mon before" // 缺省

日期輸入 Facet

簡介 - 構造 - 訪問器

簡介

boost::date_time::date_input_facet 讓用戶可以控制如果從流中輸入 dates (以及其它格里曆對像)。date_input_facet 被 typedef 為 gregorian 名字空間中的 date_input_facet 和 wdate_input_facet.

構造

語法	說明
date_input_facet()	缺省構造函數。
date_input_facet(string_type format)	給定的 Format 將被用於 date 的輸入。所有其它格式使用缺省值。
date_input_facet(...) Parameters: string_type format format_date_parser_type special_values_parser_type period_parser_type date_gen_parser_type	給定的 Format 將被用於 date 的輸入。其它參數為分析器對象。有關這些對象的更多細節請見這裡。

訪問器

語法	說明
語法	例子
void format(char_type*)	設置日期的格式。
void format(char_type*)	date_input_facet* f = new date_input_facet(); f->format("%m %d %Y");
void set_iso_format()	設置日期格式為 ISO
void set_iso_format()	f->set_iso_format(); // "%Y%m%d"
void set_iso_extended_format()	設置日期格式為 ISO 擴展
void set_iso_extended_format()	f->set_iso_extended_format(); // "%Y-%m-%d"
void month_format(char_type*)	單獨設置月份的輸入格式。
void month_format(char_type*)	f->month_format("%B"); ss.str("March"); ss >> m; // 三月
void weekday_format(char_type*)	單獨設置週日的輸入格式。
void weekday_format(char_type*)	f->weekday_format("%a"); ss.str("Sun"); ss >> wd; // 星期天
void year_format(char_type*)	單獨設置年份的格式。
void year_format(char_type*)	f->weekday_format("%y"); ss.str("04"); ss >> year; // 2004
void period_parser(...) Parameter: period_parser_type	將 period 分析器對像替換為用戶創建的對象。
void period_parser(...) Parameter: period_parser_type	完整的例子請見指南。
void special_values_parser(...) Parameter: special_values_parser_type	將 special_values 分析器替換為用戶創建的對象。
	完整的例子請見指南。
void date_gen_phrase_strings(...) Parameters: input_collection_type	設置 date_gen_parser 中的新日期生成器對象。其中 input collection 為字符串 vector(有關這些字符串的細節請見日期生成器格式器/分析器的文檔)。

void short_weekday_names(...) Parameter: input_collection_type	替換用於輸入短週日名的字符串。
	完整的例子請見指南。
void long_weekday_names(...) Parameter: input_collection_type	替換用於輸入長週日名的字符串。
	完整的例子請見指南。
void short_month_names(...) Parameter: input_collection_type	替換用於輸入短月份名的字符串。
	完整的例子請見指南。
void long_month_names(...) Parameter: input_collection_type	替換用於輸入長月份名的字符串。
void long_month_names(...) Parameter: input_collection_type	完整的例子請見指南。
InItrT get(...) Common parameters for all 'get' functions: InItrT from InItrT to ios_base Unique parameter for 'get' funcs: gregorian object	在 date_input_facet 中有13個 get 函數。它們的共同參數是：一個指向流的開始位置的迭代器，一個指向流的結束位置的迭代器，以及一個 ios_base 對象。每個格里曆對象都有自己的 get 函數。每個 get 函數描述如下。

InItrT get(..., date)	從流中取出一個 date 對象，使用由 `format(...)` 設置的格式或缺省格式。
InItrT get(..., date)	ss.str("2005-Jan-01"); ss >> d; // 缺省格式
InItrT get(..., month)	從流中取出一個 month 對象，使用由 `month_format(...)` 設置的格式或缺省格式。
InItrT get(..., month)	ss.str("Feb"); ss >> m; // 缺省格式
InItrT get(..., day_of_week)	從流中取出一個 day of week 對象，使用由 `weekday_format(...)` 設置的格式或缺省格式。
InItrT get(..., day_of_week)	ss.str("Sun"); ss >> dow; // 缺省格式
InItrT get(..., day)	從流中取出兩位數字作為 day of month 對象。
InItrT get(..., day)	"01" // 1月1日
InItrT get(..., year)	從流中取出一個數字作為 year 對象。該數字的位數取決於年份格式。
InItrT get(..., year)	ss/str("2005"); ss >> y; // 缺省格式
InItrT get(..., days)	從流中取出一個數字作為 days 對象。
InItrT get(..., days)	ss.str("356"); ss >> dys; // 一整年
InItrT get(..., date_period)	從流中取出一個 date_period. dates 的格式使用由 `format(..)` 設置的格式或缺省的日期格式。period 的類型(開或閉區間)以及使用的分隔符為 period_parser 所使用的設置。
InItrT get(..., date_period)	完整的例子請見指南。
InItrT get(..., partial_date)	從流中取出一個 partial_date date_generator 對象。月份格式使用由 `month_format(..)` 設置的格式或缺省格式。day of month 以兩位數字表示。
InItrT get(..., partial_date)	"01 Jan" // 缺省格式 "01 January" // 長月份名格式
InItrT get(..., date_generator) Date Generator Type: nth_day_of_the_week_in_month	從流中取出一個 nth_day_of_the_week_in_month 對象。月份格式使用由 `month_format(..)` 設置的格式或缺省格式。weekday 格式為由 `weekday_format(...)` 設置的格式或缺省格式。其它短語元素在 date_generator_parser 中設置。
	"third Fri in May" // 缺省
InItrT get(..., date_generator) Date Generator Type: first_day_of_the_week_in_month	從流中取出一個 first_day_of_the_week_in_month 對象。月份格式使用由 `month_format(..)` 設置的格式或缺省格式。weekday 格式為由 `weekday_format(...)` 設置的格式或缺省格式。其它短語元素在 date_generator_parser 中設置。
	"first Wed of Jun" // 缺省
InItrT get(..., date_generator) Date Generator Type: last_day_of_the_week_in_month	從流中取出一個 last_day_of_the_week_in_month 對象。月份格式使用由 `month_format(..)` 設置的格式或缺省格式。weekday 格式為由 `weekday_format(...)` 設置的格式或缺省格式。其它短語元素在 date_generator_parser 中設置。
	"last Tue of Mar" // 缺省
InItrT get(..., date_generator) Date Generator Type: first_day_of_the_week_after	從流中取出一個 first_day_of_the_week_after 對象。weekday 格式為由 `weekday_format(...)` 設置的格式或缺省格式。其它短語元素在 date_generator_parser 中設置。
	"first Sat after" // 缺省
InItrT get(..., date_generator) Date Generator Type: first_day_of_the_week_before	從流中取出一個 first_day_of_the_week_before 對象。weekday 格式為由 `weekday_format(...)` 設置的格式或缺省格式。其它短語元素在 date_generator_parser 中設置。
	"first Mon before" // 缺省

時間 Facet

簡介 - 構造 - 訪問器

簡介

boost::date_time::time_facet 是 boost::date_time::date_facet 的一個擴展。time_facet 在 posix_time 名字空間中被 typedef 為 time_facet 和 wtime_facet. 在 local_time 名字空間中被 typedef 為 local_time_facet 和 wlocal_time_facet.

構造

語法	說明
time_facet()	缺省構造函數。
time_facet(...) Parameters: char_type* format period_formatter_type special_values_formatter_type date_gen_formatter_type	給定的 Format 被用於時間的輸出。其它參數為格式化器對象。有關這些對象的更多細節請見這裡。這個構造函數為 format 以外的所有參數提供了缺省值。所以，可以使用 `time_facet("%H:%M:S %m %d %Y")` .

訪問器

time_facet 繼承了 date_facet 的所有公有方法。因此，下面不再列出 date_facet 的方法。你可以從這個鏈接找到它們。

語法	說明
語法	例子
void time_duration_format(...) Parameter: char_type*	設置 time_duration 的格式。time_duration 的格式可以顯示 duration 的符號。標誌 `'%+'` 表示總是顯示符號。而標誌 `'%-'` 則表示僅在負數時顯示符號。當前使用 '-' 和 '+' 字符來表示符號。
void time_duration_format(...) Parameter: char_type*	f->time_duration_format("%+%H:%M"); // 只顯示小時和分鐘，總是顯示符號 time_duration td1(3, 15, 56); time_duration td2(-12, 25, 32); ss << td1; // "+03:15:56" ss << td2; // "-12:25:56"
void set_iso_format()	將日期和時間的格式設為 ISO.
void set_iso_format()	f->set_iso_format(); // "%Y%m%dT%H%M%S%F%q"
void set_iso_extended_format()	將日期和時間的格式設為 ISO 擴展。
void set_iso_extended_format()	f->set_iso_extended_format(); // "%Y-%m-%d %H:%M:%S%F%Q"
OutItrT put(...) Common parameters for all 'put' functions: OutItrT ios_base char_type Unique parameter for 'put' funcs: posix_time object	在 time_facet 中有3個 put 函數。它們的共同參數是：一個指向流中下一項的迭代器，一個 ios_base 對象，以及填充字符。每個 posix_time 對像具有自己的 put 函數。每個 put 函數描述如下。

OutItrT put(..., ptime)	將一個 ptime 對像放入流中，使用由 `format(...)` 設置的格式或缺省格式。
OutItrT put(..., ptime)
OutItrT put(..., time_duration)	將一個 time_duration 對像放入流中，使用由 `time_duration_format(...)` 設置的格式或缺省格式。
OutItrT put(..., time_duration)
OutItrT put(..., time_period)	將一個 time_period 放入流中。日期和時間的格式使用由 `format(..)` 設置的格式或缺省的日期/時間格式。period 的類型(開或閉區間)以及所用的分隔符使用 period_formatter 中的設置。
OutItrT put(..., time_period)

時間輸入 Facet

簡介 - 構造 - 訪問器

簡介

boost::date_time::time_input_facet 是 date_input_facet 的擴展。它在 boost::posix_time 名字空間中被 typedef 為 time_input_facet 和 wtime_input_facet. 在 boost::local_time 名字空間中被 typedef 為 local_time_input_facet 和 wlocal_time_input_facet.

構造

語法	說明
time_input_facet()	缺省構造函數。
time_input_facet(string_type)	給定的 Format 用於日期/時間的輸入。所有其它格式使用它們的缺省值。
time_input_facet(...) Parameters: string_type format format_date_parser_type special_values_parser_type period_parser_type date_gen_parser_type	給定的 Format 用於日期/時間的輸入。其它參數為分析器對象。有關這些對象的更多細節請見這裡。

訪問器

time_input_facet 繼承了 date_input_facet 的所有公有方法。因此，下面不列出 date_input_facet 的訪問。你可以在這個鏈接中找到它們。

語法	說明
語法	例子
void set_iso_format()	設置時間格式為 ISO
void set_iso_format()	f->set_iso_format(); // "%Y%m%dT%H%M%S%F%q" "20051225T132536.789-0700"
void set_iso_extended_format()	設置時間格式為 ISO 擴展。
void set_iso_extended_format()	f->set_iso_extended_format(); // "%Y-%m-%d %H:%M:%S%F %Q" "2005-12-25 13:25:36.789 -07:00"
void time_duration_format(...) Parameter: char_type*	設置 time_duration 格式。
void time_duration_format(...) Parameter: char_type*	f->time_duration_format("%H:%M"); // 只有小時和分鐘
InItrT get(...) Common parameters for all 'get' functions: InItrT from InItrT to ios_base Unique parameter for 'get' funcs: gregorian object	在 time_input_facet 中有3個 get 函數。它們的共同參數是：一個指向流的開始位置的迭代器，一個指向流的結束位置的迭代器，以及一個 ios_base 對象。每個格里曆對象都有自己的 get 函數。每個 get 函數的描述如下。

InItrT get(..., ptime)	從流中取出一個 ptime 對象，使用由 `format(...)` 設置的格式或缺省格式。
InItrT get(..., ptime)	ss.str("2005-Jan-01 13:12:01"); ss >> pt; // 缺省格式
InItrT get(..., time_duration)	從流中取出一個 time_duration 對象，使用由 `time_duration_format(...)` 設置的格式或缺省格式。
InItrT get(..., time_duration)	ss.str("01:25:15.000123000"); ss >> td; // 缺省格式
InItrT get(..., time_period)	從流中取出一個 time_period 對象。日期/時間的格式使用由 `format(..)` 設置的格式或缺省的日期時間格式。 period 的類型(開或閉區間)以及所用的分隔符使用 period_parser 的設置。
InItrT get(..., time_period)	完整的例子請見指南。

日期時間格式化器/分析器對像

時間段 | 日期生成器 | 特殊值 | 格式化日期分析器

時間段

period_formatter 和 period_parser 為 date_periods, time_periods, 以及未來版本中的 local_date_time_periods 的輸入和輸出提供了統一的接口。用戶可以控制所用的定界符、日期/時間組件的格式，以及時間段的表示形式。日期/時間組件的格式通過 date_time 的輸入輸出 facets 來控制。

時間段的表示形式

時間段是以開區間參數來構造的。first 值為開始的時間點，並且包含在時間段中。end 值則不包含在時間段中，它緊隨在 last 值之後：[begin/end). 不過，時間段既可以作為開區間也可以作為閉區間的方式來進行流操作。

[2003-Jan-01/2003-Dec-31] <-- 包含365天的時間段
[2003-Jan-01/2004-Jan-01) <-- 包含365天的時間段

定界符

共有四個定界符。它們的缺省值是：

"\" - 分隔符

"[" - 開始定界符

")" - 開區間的結束定界符

"]" - 閉區間的結束定界符

用戶可以提供定制的定界符。用戶定制的定界符可以包含空格。

定制

時間段的形式和定界符可以通過構造參數或訪問器函數來設置。而定制的時間段分析器/格式化器則可以作為構造參數來構造新的 facet, 或者通過訪問器函數設置到已有的 facet 中。

時間段格式化器/分析器的參考

完整的類參考請見：Period Formatter Doxygen Reference 和 Period Parser Doxygen Reference

時間段格式化器構造

語法說明

語法	說明
period_formatter(...) Parameters: range_display_options char_type* char_type* char_type* char_type*	註：所有五個構造函數都具有缺省值，所以這個構造函數也可用為缺省構造函數。`range_display_options` 是 `period_formatter` 類的一個公有枚舉類型。可能的選擇為 AS_OPEN_RANGE 或 AS_CLOSED_RANGE. 缺省值是閉區間。時間段有三個主要的時間點：begining, last, 和 end. 閉區間時間段格式為 [begin,end), 而開區間時間格式為 [begin,last]. 四個 char_type* 參數分別是：時間段分隔符，開始定界符，開區間結束定界符，和閉區間結束定界符。

period_formatter(...)
  Parameters:
    range_display_options
    char_type*
    char_type*
    char_type*
    char_type*

註：所有五個構造函數都具有缺省值，所以這個構造函數也可用為缺省構造函數。range_display_options 是 period_formatter 類的一個公有枚舉類型。可能的選擇為 AS_OPEN_RANGE 或 AS_CLOSED_RANGE. 缺省值是閉區間。時間段有三個主要的時間點：begining, last, 和 end. 閉區間時間段格式為 [begin,end), 而開區間時間格式為 [begin,last]. 四個 char_type* 參數分別是：時間段分隔符，開始定界符，開區間結束定界符，和閉區間結束定界符。

時間段格式化器訪問器

語法	說明
語法	例子
range_display_options range_option()	返回區間顯示的當前設置(AS_OPEN_RANGE 或 AS_CLOSED_RANGE).
range_display_options range_option()
void range_option(...) Parameter: range_display_options	設置區間顯示選項(AS_OPEN_RANGE 或 AS_CLOSED_RANGE).
void range_option(...) Parameter: range_display_options
void delimiter_strings(...) Parameters: string_type string_type string_type string_type	設置格式化器中的定界符字符串。
	string beg("->\| "); string sep(" \|\| "); string opn(" ->\|"); string clo(" \|<-"); pf.delimiter_strings(beg, sep, opn, clo);
put_period_start_delimeter(...) Return Type: OutItrT Parameter: OutItrT	將開始定界符放入到流中由 OutItrT 參數所指的位置。

put_period_sepatator(...) Return Type: OutItrT Parameter: OutItrT	將分隔符放入到流中由 OutItrT 參數所指的位置。

put_period_end_delimeter(...) Return Type: OutItrT Parameter: OutItrT	將結束定界符放入到流中由 OutItrT 參數所指的位置。

OutItrT put_period(...) Parameters: OutItrT ios_base char_type period_type facet_type	將一個時間段放入流中，使用設置的定界符，分隔符和區間表示法。參數 facet 用於輸出時間段中的日期(或時間)。

時間段分析器構造

語法說明

語法	說明
period_parser(...) Parameters: period_range_option char_type* char_type* char_type* char_type*	註：所有五個構造函數都具有缺省值，所以這個構造函數也可用為缺省構造函數。`period_range_option` 是 `period_parser` 類的一個公有枚舉類型。可能的選擇為 AS_OPEN_RANGE 或 AS_CLOSED_RANGE. 缺省值是閉區間。時間段有三個主要的時間點：begining, last, 和 end. 閉區間時間段格式為 [begin,end), 而開區間時間格式為 [begin,last]. 四個 char_type* 參數分別是：時間段分隔符，開始定界符，開區間結束定界符，和閉區間結束定界符。
period_parser(period_parser)	複製構造函數

period_parser(...)
  Parameters:
    period_range_option
    char_type*
    char_type*
    char_type*
    char_type*

註：所有五個構造函數都具有缺省值，所以這個構造函數也可用為缺省構造函數。period_range_option 是 period_parser 類的一個公有枚舉類型。可能的選擇為 AS_OPEN_RANGE 或 AS_CLOSED_RANGE. 缺省值是閉區間。時間段有三個主要的時間點：begining, last, 和 end. 閉區間時間段格式為 [begin,end), 而開區間時間格式為 [begin,last]. 四個 char_type* 參數分別是：時間段分隔符，開始定界符，開區間結束定界符，和閉區間結束定界符。

period_parser(period_parser)

複製構造函數

時間段分析器訪問器

語法	說明
語法	例子
period_range_option range_option()	返回時間段區間表示的當前設置(AS_OPEN_RANGE 或 AS_CLOSED_RANGE).
period_range_option range_option()
void range_option(...) Parameter: period_range_option	設置時間段區間的表示選項(AS_OPEN_RANGE 或 AS_CLOSED_RANGE).
void range_option(...) Parameter: period_range_option
void delimiter_strings(...) Parameters: string_type string_type string_type string_type	為分析器設置新的定界符字符串。
	string beg("->\| "); string sep(" \|\| "); string opn(" ->\|"); string clo(" \|<-"); pp.delimiter_strings(beg, sep, opn, clo);
collection_type delimiter_strings()	返回分析器中當前的定界符字符串。
collection_type delimiter_strings()
period_type get_period(...) Parameters: stream_itr_type stream_itr_type ios_base period_type duration_type facet_type	從流中分析出一個時間段。兩個迭代器參數分別指向流的開始位置和結束位置。duration_type 與 period 的類型相關，例如：`date_period` 以 `days` 作為 duration_type. 根據 facet 參數中的格式和字符串來分析得取時間段。

_____________________________________________________

日期生成器

date_generator 格式化器和分析器提供了靈活性，允許用戶使用定制的"短語元素"。這些短語元素是 date_generators 中的"分隔"單詞。例如，在 date_generator "Second Monday of March" 中，"Second" 和 "of" 都是短語元素，而 "Monday" 和 "March" 就是日期元素。日期元素的定制由 facet 負責。日期元素和短語元素的順序是不能改變的。在進行分析時，date_generator 的所有元素必須都能正確分析，否則將拋出一個 ios_base::failure 異常。

定制

缺省的 "phrase_strings" 為：

"first"

"second"

"third"

"fourth"

"fifth"

"last"

"before"

"after"

"of"

一組定制的 phrase_strings 必須保持以下順序(如："1st", "2nd", "3rd", "4th", "5th", "last", "prior", "past", "in")。

例如，使用缺省的 phrase_strings 以及缺省 facet 格式的 weekday & month:

"first Tue of Mar"

而使用定制的 phrase_strings:

"1st Tue in Mar"

短語元素的定制可以在構造參數中設置，也可以通過訪問器函數來設置。一個定制的 date_generator 分析器/格式化器可以用作一個新的 facet 的構造參數，或者通過訪問器函數設置到已有的 facet 中。

重要說明：在版本1.33以前，partial_date 的輸出形如 "1 Jan"，其中日期是用一位或兩位數字來表示的。而新的版本中則總是以兩位數字表示日期 - "01 Jan"。

日期生成器參考

完整的類參考請見：Date Generator Formatter Doxygen Reference 和 Date Generator Parser Doxygen Reference

日期生成器的格式化器構造

語法	說明
date_generator_formatter()	使用缺省的日期生成器元素。
date_generator_formatter(...) Parameters: string_type first_element string_type second_element string_type third_element string_type fourth_element string_type fifth_element string_type last_element string_type before_element string_type after_element string_type of_element	使用給定的元素字符串構造一個 date_generator_formatter.

語法

說明

date_generator_formatter()

使用缺省的日期生成器元素。

date_generator_formatter(...)
  Parameters:
    string_type first_element
    string_type second_element
    string_type third_element
    string_type fourth_element
    string_type fifth_element
    string_type last_element
    string_type before_element
    string_type after_element
    string_type of_element

使用給定的元素字符串構造一個 date_generator_formatter.

日期生成器的格式化器訪問器

語法	說明
語法	例子
void elements(...) Parameters: collection_type phrase_elements	替換當前的短語元素。參數 `phrase_elements` 為枚舉值，表示新的短語集中的第一個元素(缺省為 first)。
	// col 中存有 "final", "prior", "following", 和 "in" typedef date_generator_formatter dgf; dgf formatter(); formatter.elements(col, dgf::last); // 現在 dgf 的完整元素為： // "first", "second", "third", "fourth", "fifth", // "final", "prior", "following", 和 "in"
put_partial_date(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill partial_date facet_type	用於 partial_date 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 partial_date => "dd Month".
put_nth_kday(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill nth_kday_type facet_type	用於 nth_kday_type 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 nth_day_of_the_week_in_month => "nth weekday of month".
put_first_kday(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill first_kday_type facet_type	用於 first_kday_type 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 first_day_of_the_week_in_month => "first weekday of month".
put_last_kday(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill last_kday_type facet_type	用於 last_kday_type 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 last_day_of_the_week_in_month => "last weekday of month".
put_kday_before(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill kday_before_type facet_type	用於 kday_before_type 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 first_day_of_the_week_before => "weekday before"
put_kday_after(...) Return Type: facet_type::OutItrT Parameters: OutItrT next ios_base char_type fill kday_after_type facet_type	用於 kday_after_type 的 put 函數。這是一個以 facet_type 為參數的模板函數。
	輸出一個 first_day_of_the_week_after => "weekday after".

日期生成器的分析器構造

語法	說明
date_generator_parser()	使用缺省的日期生成器元素。
date_generator_parser(...) Parameter: date_generator_parser	複製構造函數。
date_generator_parser(...) Parameters: string_type first_element string_type second_element string_type third_element string_type fourth_element string_type fifth_element string_type last_element string_type before_element string_type after_element string_type of_element	使用給定的元素字符串構造一個 date_generator_parser.

語法

說明

date_generator_parser()

使用缺省的日期生成器元素。

date_generator_parser(...)
  Parameter:
    date_generator_parser

複製構造函數。

date_generator_parser(...)
  Parameters:
    string_type first_element
    string_type second_element
    string_type third_element
    string_type fourth_element
    string_type fifth_element
    string_type last_element
    string_type before_element
    string_type after_element
    string_type of_element

使用給定的元素字符串構造一個 date_generator_parser.

日期生成器的分析器訪問器

語法	說明
語法	例子
void element_strings(...) Parameter: collection_type	為日期生成器替換一組新的元素字符串。
void element_strings(...) Parameter: collection_type
void element_strings(...) Parameters: string_type first string_type second string_type third string_type fourth string_type fifth string_type last string_type before string_type after string_type of	為日期生成器元素替換一組新值。

get_partial_date_type(...) Return Type: facet_type::partial_date_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 partial_date => "dd Month".
get_nth_kday_type(...) Return Type: facet_type::nth_kday_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 nth_day_of_the_week_in_month => "nth weekday of month".
get_first_kday_type(...) Return Type: facet_type::firat_kday_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 first_day_of_the_week_in_month => "first weekday of month".
get_last_kday_type(...) Return Type: facet_type::last_kday_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 last_day_of_the_week_in_month => "last weekday of month".
get_kday_before_type(...) Return Type: facet_type::kday_before_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 first_day_of_the_week_before => "weekday before"
get_kday_after_type(...) Return Type: facet_type::kday_after_type Parameters: stream_itr_type next stream_itr_type str_end ios_base facet_type	模板函數，從流中分析出一個 date_generator.
	分析一個 first_day_of_the_week_after => "weekday after".

_____________________________________________________

特殊值

date_time 庫中使用了五個 special_values. 它們是：

not_a_date_time

neg_infin

pos_infin

min_date_time

max_date_time

用於表示這些類型的缺省字符串是："not-a-date-time", "-infinity", "+infinity", "minimum-date-time", "maximum-date-time". 在輸出時，min_date-time 和 max_date_time以普通的日期/時間表示來顯示，分別為："1400-Jan-01" 和 "9999-Dec-31".

定制

特殊值分析器/格式化器允許用戶為這些特殊值設置定制的字符串。這些字符串可以用為構造參數設置給一個新的 facet, 或者可以通過訪問器函數設置給一個已有的 facet.

特殊值的分析器/格式化器參考

完整的類參考請見：Special Values Formatter Doxygen Reference 以及 Special Values Parser Doxygen Reference

特殊值的格式化器構造函數

語法	說明
special_values_formatter()	使用缺省的特殊值字符串的構造函數。
special_values_formatter(...) Parameters: collection_type::iterator collection_type::iterator	使用 collection 中的值進行構造。註：只使用 collection 中的前三個字符串。minimum_date_time 和 maximum_date_time 的字符串被忽略，因為這兩個特殊值以普通的日期/時間來輸出。
special_values_formatter(...) Parameters: char_type* char_type*	從一個字符串數組構造特殊值格式化器。

特殊值格式化器的訪問器

語法	說明
OutItrT put_special(...) Parameters: OutItrT next special_values value	將給定的特殊值放入到流中。
date d1(not_a_date_time); date d2(minimum_date_time); special_values_formatter formatter; formatter.put_special(itr, d1); // 放入: "not-a-date-time" formatter.put_special(itr, d2); // 放入: "1400-Jan-01"

語法

說明

例子

OutItrT put_special(...)
  Parameters:
    OutItrT next
    special_values value

將給定的特殊值放入到流中。

date d1(not_a_date_time);
date d2(minimum_date_time);
special_values_formatter formatter;
formatter.put_special(itr, d1); 
// 放入: "not-a-date-time"
formatter.put_special(itr, d2); 
// 放入: "1400-Jan-01"

特殊值分析器的構造函數

語法	說明
special_values_parser()
special_values_parser(...) Parameters: collection_type::iterator collection_type::iterator	使用 collection 中的字符串構造一個特殊值分析器。
special_values_parser(...) Parameter: scpecial_values_parser	複製構造函數。
special_values_parser(...) Parameters: string_type nadt_str string_type neg_inf_str string_type pos_inf_str string_type min_dt_str string_type max_dt_str	使用給定的字符串構造一個特殊值分析器。

特殊值分析器的訪問器

語法	說明
語法	例子
void sv_strings(...) Parameters: string_type nadt_str string_type neg_inf_str string_type pos_inf_str string_type min_dt_str string_type max_dt_str	以給定的字符串替換特殊值字符串。

bool match(...) Parameters: stream_itr_type beg stream_itr_type end match_results	返回 true 如果分析成功。對於一次成功的分析，`mr.current_match` 被設置為一個 int 值，對應於等價的 special_value.
	// 流中有 "maximum_date_time" typedef special_values_parser svp; svp parser; svp::match_results mr; if(parser.match(itr, str_end, mr)) { d = date(static_cast<special_values>( mr.match_results)) } else { // 錯誤，分析失敗 } // d == "9999-Dec-31"

_____________________________________________________

格式化日期分析器

格式化日期分析器是一個保存有月份名和週日的全名及其縮寫名的字符串的對象。可以在構造時對字符串進行定制，或者通過訪問器函數替換已有 format_date_parser 中的字符串。構造函數以及訪問器函數均以一個字符串 vector 作為其參數。

格式化日期分析器的參考

完整的類參考請見：Doxygen Reference

格式化日期分析器的構造函數

語法	說明
format_date_parser(...) Parameters: string_type format std::locale	創建一個分析器，以給定的格式來分析日期(在那些函數中沒有格式化參數)。所使用的名字及縮寫從給定的 locale 中取出。
format_date_parser(...) Parameters: string_type format input_collection_type input_collection_type input_collection_type input_collection_type	創建一個分析器，使用給定的組件。參數 input_collection_type 為：短月份名，長月份名，短週日名，長週日名(按順序)。這些 collections 必須包含每個月份和每個週日(從一月和星期天開始)的值。
format_date_parser(...) Parameters: format_date_parser	複製構造函數。

格式化日期分析器的訪問器

語法	說明
語法	例子
string_type format()	返回在那些不帶格式化參數的函數中進行日期分析時所使用的格式。
string_type format()
void format(string_type)	設置在那些不帶格式化參數的函數中進行日期分析時所使用的格式。
void format(string_type)
void short_month_names(...) Parameter: input_collection_type names	替換分析器所用的短月份名。collection 必須包含每個月份的值，從一月開始。

void long_month_names(...) Parameter: input_collection_type names	替換分析器所用的長月份名。collection 必須包含每個月份的值，從一月開始。

void short_weekday_names(...) Parameter: input_collection_type names	替換分析器所用的短週日名。collection 必須包含每個週日的值，從星期天開始。

void long_weekday_names(...) Parameter: input_collection_type names	替換分析器所用的長週日名。collection 必須包含每個週日的值，從星期天開始。

date_type parse_date(...) Parameters: string_type input string_type format special_values_parser	以給定格式從給定的輸入中分析日期。
	string inp("2005-Apr-15"); string format("%Y-%b-%d"); date d; d = parser.parse_date(inp, format, svp); // d == 2005-Apr-15
date_type parse_date(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end special_values_parser	使用分析器的格式從流中分析日期。

date_type parse_date(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end string_type format special_values_parser	使用給定格式從流中分析日期。
	// 流中有 "2005-04-15" string format("%Y-%m-%d"); date d; d = parser.parse_date(itr, str_end, format, svp); // d == 2005-Apr-15
month_type parse_month(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end string_type format	使用給定的格式從流中分析月份。如果無法分析則拋出 bad_month.
	// 流中有 "March" string format("%B"); greg_month m; m = parser.parse_month(itr, str_end, format); // m == March
day_type parse_day_of_month(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end	從流中分析一個 day_of_month. 日期必須以兩位數字出現(01-31)，否則拋出 bad_day_of_month.
	// 流中有 "01" greg_day d; d = parser.parse_day_of_month(itr, str_end); // d == 1st
day_type parse_var_day_of_month(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end	從流中分析一個 day_of_month. 日期必須以一位或兩位數字出現(1-31)，否則拋出 bad_day_of_month.
	// 流中有 "1" greg_day d; d = parser.parse_var_day_of_month(itr, str_end); // d == 1st
day_of_week_type parse_weekday(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end string_type format	以給定格式從流中分析一個週日。如果無法分析則拋出 bad_weekday.
	// 流中有 "Tue" string format("%a"); greg_weekday wd; wd = parser.parse_weekday(itr, str_end, format); // wd == Tuesday
year_type parse_year(...) Parameters: istreambuf_iterator input istreambuf_iterator str_end string_type format	以給定格式從流中分析一個年份。如果無法分析則拋出 bad year.
	// 流中有 "98" string format("%y"); greg_year y; y = parser.parse_year(itr, str_end, format); // y == 1998

日期時間 IO 指南

基本用法

在調用 '>>' 和 '<<' 時，會自動使用 Facets. 可以進行流輸入輸出的 date_time 對像列舉如下：

格里曆

date, days, date_period, greg_month, greg_weekday, greg_year, partial_date, nth_day_of_the_week_in_month, first_day_of_the_week_in_month, last_day_of_the_week_in_month, first_day_of_the_week_after, first_day_of_the_week_before

Posix_time

ptime, time_period, time_duration

本地時間

local_date_time

以下是使用新的 IO 代碼的簡單例子，全部使用缺省值。(這個例子可以在 libs/date_time/examples/tutorial 目錄下找到)

    
  date d(2004, Feb, 29);
  time_duration td(12,34,56,789);
  stringstream ss;
  ss << d << ' ' << td;
  ptime pt(not_a_date_time);
  cout << pt << endl; // "not-a-date-time"
  ss >> pt;
  cout << pt << endl; // "2004-Feb-29 12:34:56.000789"
  ss.str("");
  ss << pt << " EDT-05EDT,M4.1.0,M10.5.0";
  local_date_time ldt(not_a_date_time);
  ss >> ldt;
  cout << ldt << endl; // "2004-Feb-29 12:34:56.000789 EDT"

這個例子使用了輸入和輸出 facets 的缺省值。缺省的格式正如上例所示。注意：local_date_time 的流輸入只能用一個 posix 時區字符串來完成。缺省的輸出格式將使用時區縮寫。這個格式可以被改變，以使得輸入和輸出相匹配(在本指南稍後將會看到)。

格式化串

格式化串控制著所用的日期/時間元素的順序、類型和風格。facets 提供了一些預定義的格式(iso_format_specifier, iso_format_extended_specifier, 和 default_date_format)，不過用戶也可以很容易地創建自己的格式。

(繼續前一個例子)

    
  local_time_facet* output_facet = new local_time_facet();
  local_time_input_facet* input_facet = new local_time_input_facet();
  ss.imbue(locale(locale::classic(), output_facet));
  ss.imbue(locale(ss.getloc(), input_facet));
  
  output_facet->format("%a %b %d, %H:%M %z");
  ss.str("");
  ss << ldt;
  cout << ss.str() << endl; // "Sun Feb 29, 12:34 EDT"

  output_facet->format(local_time_facet::iso_time_format_specifier);
  ss.str("");
  ss << ldt;
  cout << ss.str() << endl; // "20040229T123456.000789-0500"
 
  output_facet->format(local_time_facet::iso_time_format_extended_specifier);
  ss.str("");
  ss << ldt;
  cout << ss.str() << endl; // "2004-02-29 12:34:56.000789-05:00"

格式化串前不僅限於日期/時間元素。可以往格式化串中放入其它內容。注意：如果在輸入格式化串中存在其它內容，那麼輸入的數據中也必須包含這些內容。

(繼續前一個例子)

    
  // 格式中的額外單詞
  string my_format("The extended ordinal time %Y-%jT%H:%M can also be \
  represented as %A %B %d, %Y");
  output_facet->format(my_format.c_str());
  input_facet->format(my_format.c_str());
  ss.str("");
  ss << ldt;
  cout << ss.str() << endl;

  // 在輸入中必須要有相匹配的單詞
  ss.str("The extended ordinal time 2005-128T12:15 can also be \
  represented as Sunday May 08, 2005");
  ss >> ldt;
  cout << ldt << endl;

內容字符串

前面我們示範了如何通過格式化以極少量的工作量來達到大量的定制化。更進一步的定制化可以通過用戶自定義元素(即字符串)來完成。可以被定制的元素包括：特殊值的名字、月份名、月份縮寫、週日名、週日縮寫、日期/時間段的定界符，以及 date_generators 的短語元素。

以上元素的缺省值如下：

特殊值

not-a-date-time, -infinity, +infinity, minimum-date-time, maximum-date-time

月份

英語名字及三字母的縮寫

週日

英語名字及三字母縮寫

日期生成器的短語元素

first, second, third, fourth, fifth, last, before, after, of

注意：我們在前面曾經示範過日期/時間表示中的組件可以通過格式化串來重新排序。但是對於 date_generators 來說則不可以。其中的元素可以定制但順序不可改變。

內容字符串

為了示範定制化的可能性，我們將為月份和週日使用定制的字符串(我們在這個例子中只使用長名字，且全為小寫)。

(繼續前一個例子)

    
  // 設置定制字符串的 collections.
  // 為簡短起見，只修改全名
  string month_names[12] = { "january", "february", "march", 
                             "april", "may", "june", 
                             "july", "august", "september", 
                             "october", "november", "december" };
  vector<string> long_months(&month_names[0], &month_names[12]);
  string day_names[7] = { "sunday", "monday", "tuesday", "wednesday", 
                          "thursday", "friday", "saturday" };
  vector<string> long_days(&day_names[0], &day_names[7]);
  
  //  使用缺省值創建 date_facet 和 date_input_facet
  date_facet* date_output = new date_facet();
  date_input_facet* date_input = new date_input_facet();
  ss.imbue(locale(ss.getloc(), date_output)); 
  ss.imbue(locale(ss.getloc(), date_input));

  // 替換輸出 facet 中的名字
  date_output->long_month_names(long_months);
  date_output->long_weekday_names(long_days);
  
  // 替換輸入 facet 中的名字
  date_input->long_month_names(long_months);
  date_input->long_weekday_names(long_days);
  
  // 定制月份、週日和日期的格式
  date_output->format("%Y-%B-%d");
  date_input->format("%Y-%B-%d");
  date_output->month_format("%B"); // 全名
  date_input->month_format("%B"); // 全名
  date_output->weekday_format("%A"); // 全名
  date_input->weekday_format("%A"); // 全名

  ss.str("");
  ss << greg_month(3);
  cout << ss.str() << endl; // "march"
  ss.str("");
  ss << greg_weekday(3);
  cout << ss.str() << endl; // "tuesday"
  ss.str("");
  ss << date(2005,Jul,4);
  cout << ss.str() << endl; // "2005-july-04"

特殊值

定制輸入和輸出用的特殊值，最好的方法是創建一個新的 special_values_parser 和 special_values_formatter. 新的字符串在構造的時候進行設置(如下例所示)。

(繼續前一個例子)

    
  // 將格式重置為缺省
  output_facet->format(local_time_facet::default_time_format);
  input_facet->format(local_time_input_facet::default_time_input_format);

  // 創建定制的 special_values 分析器和格式化器對像
  // 並將它們加入到 facets
  string sv[5] = {"nadt","neg_inf", "pos_inf", "min_dt", "max_dt" };
  vector<string> sv_names(&sv[0], &sv[5]);
  special_values_parser sv_parser(sv_names.begin(), sv_names.end());
  special_values_formatter sv_formatter(sv_names.begin(), sv_names.end());
  output_facet->special_values_formatter(sv_formatter);
  input_facet->special_values_parser(sv_parser);

  ss.str("");
  ldt = local_date_time(not_a_date_time);
  ss << ldt;
  cout << ss.str() << endl; // "nadt"
  
  ss.str("min_dt");
  ss >> ldt;
  ss.str("");
  ss << ldt;
  cout << ss.str() << endl; // "1400-Jan-01 00:00:00 UTC"

注意：雖然我們將 min 和 max 的字符串也傳遞給了格式化器，但是它們會被忽略，因為這兩個特殊值是以真實的日期來構造的(如上所示)。

日期/時間段

定制時間段的輸入輸出，最好的方法是創建一個新的 period_parser 和 period_formatter. 新的字符串在構造的時候進行設置(如下例所示)。

(繼續前一個例子)

    
  // 將所有格式設置回缺省值(為簡短起見，不再列出)

  // 創建我們的 date_period
  date_period dp(date(2005,Mar,1), days(31)); // 整個三月份

  // 定制時間段格式化器和分析器
  period_formatter per_formatter(period_formatter::AS_OPEN_RANGE, 
                                 " to ", "from ", " exclusive", " inclusive" );
  period_parser per_parser(period_parser::AS_OPEN_RANGE, 
                           " to ", "from ", " exclusive" , "inclusive" );
  
  // 缺省輸出
  ss.str("");
  ss << dp;
  cout << ss.str() << endl; // "[2005-Mar-01/2005-Mar-31]"
 
  // 將我們的定制分析器和格式化器加入到 facets
  date_output->period_formatter(per_formatter);
  date_input->period_parser(per_parser);
  
  // 定制化輸出
  ss.str("");
  ss << dp;
  cout << ss.str() << endl; // "from 2005-Feb-01 to 2005-Apr-01 exclusive"

日期生成器

定制 date_generators 的輸入輸出可以通過將(在 facet 中的)已有字符串替換為新字符串來完成。

注意：前面我們曾經示範過日期/時間表示中的組件可以通過格式化串變更順序。但是對於 date_generators 則不可以。其中的元素可以定制，但順序不可改變。

(繼續前一個例子)

    
  // 定制 date_generator 短語
  string dg_phrases[9] = { "1st", "2nd", "3rd", "4th", "5th", 
                           "final", "prior to", "following", "in" };
  vector<string> phrases(&dg_phrases[0], &dg_phrases[9]);

  // 創建我們的 date_generator
  first_day_of_the_week_before d_gen(Monday);

  // 缺省輸出
  ss.str("");
  ss << d_gen;
  cout << ss.str() << endl; // "Mon before"
 
  // 將我們的定制字符串加入到日期 facets
  date_output->date_gen_phrase_strings(phrases);
  date_input->date_gen_element_strings(phrases);
  
  // 定制化的輸出
  ss.str("");
  ss << d_gen;
  cout << ss.str() << endl; // "Mon prior to"