Boost C++ Libraries Home Libraries People FAQ More
PrevUpHomeNext

本地時間

時區(抽像)
Posix 時區
時區數據庫
定制時區
本地日期時間
本地時間段

本地時間系統

簡介 -- 用例

簡介

本庫支持4種對本地時間管理的主要擴展。它們包括：

local_date_time -- 本地調整後的時間點
posix_time_zone -- 由 posix 字符串(如："EST10EDT,M10.5.0,M3.5.0/03")定義的時區
time_zone_database -- 按地區從 .csv 文件(如：America/New York)取出時區
time_zone -- 抽像的時區接口

以上擴展一起定義了一個經調整的時間系統來記錄與特定地理位置相關的時間。該時間系統使用了 posix_time 時間的所有特性和優點(詳情請參見 posix_time)。它使用一個 time_zone 對像來保存按不同時區進行調整所需的數據/規則。這個 time_zone 對像被用在 date_time 中，通過一個 boost::shared_ptr<boost::local_time::time_zone> 來處理。

術語 "wall-clock" 表示在特定時區、特定時間點的時鐘所顯示的時間。Local_time 使用一個 time zone 對像來區分不同的時區以及夏令時的調整。例如：澳大利亞悉尼的2004年10月10日下午5:00相當於美國紐約的2004年10月10日上午3:00, 在兩個 wall-clock 時間之間有14個小時的差距。但是，一天以後的同一個時間點將由於兩個時區不同的夏令時調整而導致兩個 wall-clock 時間之間的差距變為16個小時。local_time 系統可以依靠保存在UTC中的時間點來跟蹤這些，而 time_zone 對像則包含了正確計算 wall-clock 時間所需的所有數據。

用例

例子 說明
簡單的時區 多個使用時區的方法的例子。包括 custom_time_zone 和 posix_time_zone 的示範。
夏令時計算規則 示範創建所有五個 dst_calc_rule 類型的簡單例子。
由 Epoch 起計的秒數 使用 local_date_time 計算自 epoch (1970-Jan-01)起的總秒數的例子。

時區(抽像)

簡介 -- 頭文件 -- 構造 -- 訪問器

簡介

time_zone_base 類是一個表示時區的抽像基類模板。時間是一組數據和規則，它提供了關於時區的信息。date_time 庫用一個 boost::shared_ptr<time_zone_base> 來處理 time_zones. 要在 date_time 庫中使用的定制時區類要使用這個 shared_ptr.

為方便使用，time_zone_base 類被 typedef 為 time_zone. 本文檔中的所有對 time_zone 引用均表示這個 typedef.

頭文件

time_zone_base 類定義在頭文件： 

#include "boost/date_time/time_zone_base.hpp"

構造

在 time_zone_base 類中提供了一個缺省構造函數。在該基類中沒有私有數據成員需要初始化。

模板參數為 time_type (如 posix_time::ptime) 和 CharT (缺省為 char)。

訪問器

下表所列的所有訪問器均為純虛擬函數。

語法 說明 
string_type dst_zone_abbrev();
 返回被表示時區的夏令時縮寫。 
string_type std_zone_abbrev();
 返回被表示時區的標準縮寫。 
string_type dst_zone_name();
 返回被表示時區的夏令時名字。 
string_type std_zone_name();
 返回被表示時區的標準名字。 
bool has_dst();
 返回 true 如果該時區沒有夏令時偏移。 
time_type dst_local_start_time(year_type);
 給定年份的夏令時開始日期和時間。 
time_type dst_local_end_time(year_type);
 給定年份的夏令時結束日期和時間。 
time_duration_type base_utc_offset();
 距UTC的時間偏移量(通常為小時數). 
time_duration_type dst_offset();
 夏令時的時間偏移量。 
std::string to_posix_string();
 返回表示該 time_zone_base 對象的 posix 時區字符串。有關 posix 時區字符串的詳細說明請見 posix_time_zone.

Posix 時區

簡介 -- 重要說明 -- 頭文件 -- 構造 -- 訪問器

簡介

posix_time_zone 對象是一組數據和規則，它提供了與時區有關的信息。這些信息包括：距UTC的偏移、時區的名字和縮寫，以及被稱為 dst_calc_rules 的夏令時規則。這些規則被保存為一個 boost::shared_ptr<dst_calc_rules>.

為方便使用，系統為 shared_ptr<dst_calc_rules> 提供了一個 typedef. 

typedef boost::shared_ptr<dst_calc_rules> local_time::dst_calc_rule_ptr;

posix_time_zone 是唯一的，因為該對像創建自一個 Posix 時區字符串(IEEE Std 1003.1)。POSIX 時區字符串的格式如下：


      "std offset dst [offset],start[/time],end[/time]" (可帶或不帶空格)。

'std' 給出時區的縮寫。'offset' 為距UTC的偏移。'dst' 給出時區在夏令時的縮寫。第二個 offset 表示在DST時要改變的小時數。'start' 和 'end' 為開始(和結束)DST的日期。'offset' 的格式如下：


      [+|-]hh[:mm[:ss]] {h=0-23, m/s=0-59}

'time' 和 'offset' 具有相同的格式。'start' 和 'end' 可以是以下三種格式之一：


      Mm.w.d {month=1-12, week=1-5 (5總是表示最後一周), day=0-6} 
      Jn {n=1-365 Feb29不被計算} 
      n {n=0-365 Feb29 在閏年時被計算}

在以下條件下將拋出異常：

  • 無效的日期表示(請見 date 類)會拋出異常。
  • 以下情況會拋出 boost::local_time::bad_offset 異常：
  • DST開始或結束的偏移量為負或大於24小時。
  • UTC時區大於 +12 或小於 -12 小時。
  • DST調整量為24小時或更多(正的或負的)時將拋出 boost::local_time::bad_adjustment 異常。

如上所述，字符串的 'offset' 和 '/time' 部分不是必須的。如果沒有給出這些部分，則缺省的 'offset' 為 01:00，兩次 '/time' 均為 02:00。

舉例如下：


      "PST-8PDT01:00:00,M4.1.0/02:00:00,M10.1.0/02:00:00"
      "PST-8PDT,M4.1.0,M10.1.0"

這兩個字符串其實是相同的表示(第二個字符串中使用了缺省值)。該時區位於GMT以西8小時，且在夏令時要向前調整1個小時。該時區的夏令時開始於4月第一個星期天的2am, 結束於10月第一個星期天的2am.


      "MST-7"

這個時區非常簡單。它位於GMT以西7個小時且沒有夏令時。


      "EST10EDT,M10.5.0,M3.5.0/03"

該字符串表示了澳大利亞悉尼的時區。它位於GMT以東10個小時，其夏令時要向前調整1個小時。由於它位於南半球，所以夏令時開始於10月最後一個星期天的2am，結束於3月最後一個星期天的3am.


      "FST+3FDT02:00,J60/00,J304/02"

它表示了一個位於GMT以東3個小時的假想的時區。其夏令時要向前調整2個小時，開始於3月1日的午夜，結束於10月31日的2am. 其中的 'J' 指明 start/end 的表示從1起計且不計2月29日。


      "FST+3FDT,59,304"

這個表示中的'59'尤其重要。在 start 和 end 日期的表示中沒有 'J', 表示天數的計數從0起計且結束於365. 如果你算一下，可以算出總天數為366天。如果是閏年這沒有問題，但是在非閏年就不存在 '59' (Feb-29) 這天。所以，它將構造一個有效的 posix_time_zone 對象，但是如果在非閏年訪問 '59' 這天將會拋出異常。如： 

posix_time_zone leap_day(std::string("FST+3FDT,59,304"));
leap_day.dst_local_start_time(2004); // ok
leap_day.dst_local_start_time(2003); // 拋出異常

posix_time_zone 對象是通過一個 boost::shared_ptr<local_time::time_zone_base> 被使用的。為方便使用，系統提供了對 boost::shared_ptr<local_time::time_zone_base> 的 typedef: 

typedef boost::shared_ptr<time_zone_base> local_time::time_zone_ptr;

有關 time_zone 和 posix_time_zone 的用法的例子，請見 簡單的時區。

重要說明

  • posix_time_zone 對像使用標準的和夏令時的縮寫來代替全稱(請見後面的 訪問器)。
  • 'Jn' 和 'n' 日期表示法不能在一個字符串中混用。如："FST+3FDT,59,J304"
  • 'n' 日期表示法中的 59 表示 Feb-29. 不要在非閏年時訪問它，否則將拋出異常。

頭文件

包含單個頭文件即可引入所有 boost::local_time 類型、函數和 IO 操作符。 

#include "boost/date_time/local_time/local_time.hpp"

構造

語法 例子 
posix_time_zone(std::string)
 
std::string nyc("EST-5EDT,M4.1.0,M10.5.0");
time_zone_ptr zone(new posix_time_zone(nyc));

訪問器

語法 說明
例子 
std::string dst_zone_abbrev()
 返回被表示時區的夏令時縮寫。 
nyc_zone_sh_ptr->dst_zone_abbrev(); // "EDT"
 
std::string std_zone_abbrev()
 返回被表示時區的標準縮寫。 
nyc_zone_sh_ptr->std_zone_abbrev(); // "EST"
 
std::string dst_zone_name()
 返回被表示時區的夏令時縮寫。 
nyc_zone_sh_ptr->dst_zone_name(); // "EDT"
 
std::string std_zone_name()
 返回被表示時區的標準縮寫。 
nyc_zone_sh_ptr->std_zone_name(); // "EST"
 
bool has_dst()
 返回 true 如果 time_zone 中指向 dst_calc_rules 的 shared_ptr 非空。 
nyc_zone_sh_ptr->has_dst(); // true
phx_zone_sh_ptr->has_dst(); // false
 
ptime dst_local_start_time(greg_year)
 給定年份的夏令時開始日期和時間。如果該時區沒有夏令時，則返回 not_a_date_time. 
nyc_zone_sh_ptr->dst_local_start_time(2004);
// 2004-Apr-04 02:00
 
ptime dst_local_end_time(greg_year)
 給定年份的夏令時結束日期和時間。如果該時區沒有夏令時，則返回 not_a_date_time. 
nyc_zone_sh_ptr->dst_local_end_time(2004);
// 2004-Oct-31 02:00
 
time_duration base_utc_offset()
 距UTC的偏移量(通常以小時數表示)。 
nyc_zone_sh_ptr->base_utc_offset(); // -05:00
 
posix_time::time_duration dst_offset()
 夏令時的時間偏移量。 
nyc_zone_sh_ptr->dst_offset(); // 01:00
 
std::string to_posix_string()
 返回該 time_zone_base 對象的 posix 時區字符串表示。取決於 time_zone 對象是如何創建的，返回的字符串的日期表示格式可能是 'M' 格式或 'n' 格式。每個可以用 'J' 格式來表示的日期都可以表示為 'n' 格式。反之則不然，所以在這些日期表示法中只使用了 'n' 格式。有關 posix 時區字符串的詳細描述，請見 posix_time_zone. 
nyc_zone_sh_ptr->to_posix_string();
// "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
phx_zone_sh_ptr->to_posix_string();
// "MST-07"

時區數據庫

簡介 -- 頭文件 -- 構造 -- 訪問器 -- 數據文件的細節

簡介

local_time 系統依賴於保存時區信息的能力。我們的時區數據庫(tz_database)就是一個永久保存這些數據的方法。它提供了多個(目前為377個)時間的描述。這些描述基於在 zoneinfo 數據庫 中的數據。這些描述保存在文件：

libs/date_time/data/date_time_zonespec.csv

中。該文件已包含了多個時區的描述；用戶可以對它進行修改，增加(或刪除)一些時區來適應它們的應用程序。 請參看 數據文件的細節，學習如何完成這一工作。

頭文件

包含單個頭文件就可以引入所有 boost::local_time 類型、函數和 IO 操作符。 

#include "boost/date_time/local_time/local_time.hpp"

構造

只有一個構造函數，不帶參數，它創建一個空的數據庫。由用戶來組裝該數據庫。典型的方法是導入所需的數據文件，不過也可以通過 add_record(...) 函數來完成(請見 訪問器表)。如果給定的時區規格文件無法找到，將拋出 local_time::data_not_accessible 異常。如果給定文件的字段數不正確，則拋出 local_time::bad_field_count 異常。

語法 說明 
tz_database()
 構造函數，創建一個空的數據庫。 
tz_database tz_db;
 
bool load_from_file(std::string)
 參數為一個時區規格 csv 文件(有關該文件的內容細節請見 數據文件的細節)的路徑。該函數以時區規格文件中的時區記錄來組裝數據庫。如果給定的時區規格文件無法找到，將拋出 local_time::data_not_accessible 異常。如果給定文件的字段數不正確，則拋出 local_time::bad_field_count 異常。 
tz_database tz_db;
tz_db.load_from_file("./date_time_zonespec.csv");

訪問器

語法 說明
例子 
bool tz_db.add_record(std::string id, 
                      time_zone_ptr tz);
 增加一個 time_zone, 或一個 posix_time_zone, 到數據庫中。ID 為該時區的區域名(如： "America/Phoenix")。 
time_zone_ptr zone(
  new posix_time_zone("PST-8PDT,M4.1.0,M10.1.0")
);
std::string id("America/West_Coast");
tz_db.add_record(id, zone);
 
time_zone_ptr 
  tz_db.time_zone_from_region(string id);
 通過 time_zone_ptr 返回一個 time_zone, 它與數據文件所列的區域名相匹配。如果沒有找到匹配項，則返回空指針。 
time_zone_ptr nyc =
  tz_db.time_zone_from_region("America/New_York");
 
vector<string> tz_db.region_list();
 返回一個字符串 vector，其中保存了來自數據庫的所有區域 ID 字符串。 
std::vector<std::string> regions;
regions = tz_db.region_list();

數據文件的細節

字段描述/細節

存放被 boost::local_time::tz_database 使用的 zone_specs 數據的 csv 文件可以由庫用戶進行定制。在定制該文件(或創建你自己的文件)時，必須遵循特定的格式。

第一行要包含列頭，而且這行不會被 tz_database 處理。

每個記錄(即每行)必須有11個字段。其中有些字段可以為空。每個字段(即使是空的)必須用雙引號括起來。


      例如：
      "America/Phoenix" <- 帶引號的字符串
      ""                <- 空字段
    

有的字段用於表示時間的長度。這些字段的格式必須是：


      "{+|-}hh:mm[:ss]" <- 時間長度的格式
    

其中加號或減號是必須的，而秒數是可選的。

因為有些時區不使用夏令時，所以不是 zone_spec 的每個字段都必須包含有值。所有 zone_specs 必須至少有一個 ID 和 GMT 偏移量。使用夏令時的時區必須走填寫所有字段，除了：STD ABBR, STD NAME, DST NAME. 你要留意，對於使用夏令時的時區，DST ABBR 是必須的(更多詳情請見字段描述)。

字段描述/細節

  • ID

    包含 zone_spec 的標識字符串。可以是任意字符串，只要它是唯一的。不能有兩個ID相同。

  • STD ABBR
  • STD NAME
  • DST ABBR
  • DST NAME

    這四項是時區所用的名字和縮寫。因為這些字段可以為任意字符串，你必須要小心。這些字段的字符串將被用於多個 local_time 類的輸出中。

  • GMT 偏移量

    這是一個小時數，當被加到UTC上後，可以得到未進行夏令時調整前的本地時間。以下是一些例子：美國/紐約的偏移量為-5小時，而非洲/開羅的偏移量則為+2小時。它的格式必須遵循前面所說的時間長度格式。

  • DST 調整量

    這是使用夏令時時要加到 gmt_offset 上的時間數量。其格式必須遵循前面所說的時間長度格式。

    註：需要更多的表示規則的能力 - tz_database 的這部分不夠完善。

  • DST 開始日期規則

    這是一個特定格式的字符串，表示每天哪一天進行夏令時轉換。它本身包含三個字段，由分號分隔。

    1. 第一個字段表示當月中的第n個週日。可取的值為：1(第一周)，2(第二周)，3(第三周)，4(第四周)，5(第五周)，和 -1(最後一周)。
    2. 第二個字段表示周中的第幾天，從0到6(星期天=0)。
    3. 第三個字段表示第幾月，從1到12(一月=1)。

    例如："-1;5;9"="九月最後一個星期五"，"2;1;3"="三月第二個星期一"

  • 開始時間

    開始時間為開始夏令時轉換當天午夜後的小時數。表示該天中開始進行轉換的時間點(以24小時格式表示)。格式必須遵循前文所說的時間長度格式，且必須為正。

  • DST 結束日期規則

    請見 DST 開始日期規則。不同的是，本項表示的是夏令時結束的日期(轉換為 STD)。

  • 結束時間

    與開始時間相同。

定制時區

簡介 -- 頭文件 -- 構造 -- 訪問器 -- 相關類型

簡介

custom_time_zone 對象是一組數據和規則，提供了關於時區的相關信息。這些信息包括有：與UTC的偏移量，時區的名字和縮寫，被稱為 dst_calc_rules 的夏令時規則。這些規則通過一個 boost::shared_ptr<dst_calc_rules> 來處理。不是所有時區都使用夏令時，因此，time_zone 對象可以帶一個空賦值的 shared_ptr.

為方便使用，提供了對 shared_ptr<dst_calc_rules> 的一個 typedef. 

typedef boost::shared_ptr<dst_calc_rules> local_time::dst_calc_rule_ptr;

time_zone 對像通過一個 boost::shared_ptr<local_time::time_zone> 來使用。為方便起見，提供了對 boost::shared_ptr<local_time::time_zone> 的 typedef: 

typedef boost::shared_ptr<time_zone> local_time::time_zone_ptr;

頭文件

包含單個頭文件即可引入所有 boost::local_time 類型、函數和 IO 操作符。 

#include "boost/date_time/local_time/local_time.hpp"

構造

custom_time_zone 的構造依賴於四個對像：一個 time_duration, 一個 time_zone_names, 一個 dst_adjustment_offsets, 和一個指向 dst_calc_rule 的 shared_ptr.

語法 例子 
custom_time_zone(...)
  Parameters:
    names, 
    gmt_offset, 
    dst_offsets, 
    dst_rules
有關 time_zone 的用法請見 簡單的時區。

訪問器

語法 說明
例子 
std::string dst_zone_abbrev()
 返回被表示時區的夏令時縮寫。 
nyc_zone_sh_ptr->dst_zone_abbrev();
// "EDT"
 
std::string std_zone_abbrev()
 返回被表示時區的標準縮寫。 
nyc_zone_sh_ptr->std_zone_abbrev();
// "EST"
 
std::string dst_zone_name()
 返回被表示時區的夏令時名字。 
nyc_zone_sh_ptr->dst_zone_name(); 
// "Eastern Daylight Time"
 
std::string std_zone_name()
 返回被表示時區的標準名字。 
nyc_zone_sh_ptr->std_zone_name();
// "Eastern Standard Time"
 
bool has_dst()
 返回 true 如果 custom_time_zone 中指向 dst_calc_rules 的 shared_ptr 為非空。 
nyc_zone_sh_ptr->has_dst();
// true
phx_zone_sh_ptr->has_dst();
// false
 
dst_local_start_time(...)
  Return Type:
    ptime
  Parameter:
    greg_year
 給定年份的夏令時開始日期和時間。如果該時區無夏令時則返回 not_a_date_time. 
nyc_ptr->dst_local_start_time(2004);
// 2004-Apr-04 02:00
 
dst_local_end_time(...)
  Return Type:
    ptime
  Parameter:
    greg_year
 給定年份的夏令時結束日期和時間。如果該時區無夏令時則返回 not_a_date_time. 
nyc_ptr->dst_local_end_time(2004);
// 2004-Oct-31 02:00
 
time_duration base_utc_offset()
 與UTC之間的時間偏移量(通常以小時表示)。 
nyc_ptr->base_utc_offset();
// -05:00
 
time_duration dst_offset()
 夏令時的調整時間數。 
nyc_zone_sh_ptr->dst_offset();
// 01:00
 
std::string to_posix_string()
 返回表示該 time_zone 對象的 posix 時區字符串。取決於 time_zone 對象是如何創建的，返回的字符串的日期表示格式可能是 'M' 格式或 'n' 格式。每個可以用 'J' 格式來表示的日期都可以表示為 'n' 格式。反之則不然，所以在這些日期表示法中只使用了 'n' 格式。有關 posix 時區字符串的詳細描述，請見 posix_time_zone. 
nyc_ptr->to_posix_string();
// "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"
phx_ptr->to_posix_string();
// "MST-07"

相關類型

時區名 -- Dst 調整量 -- 夏令時計算規則

時區名

time_zone_names_base 類型是帶四個字符串的不可變模板類。每個字符串分別為標準時和夏令時的全稱和縮寫。time_zone_names 類型是 time_zone_names_base<char> 的 typedef.

語法 說明
例子 
time_zone_names(...)
  Parameters:
    string std_name
    string std_abbrev
    string dst_name
    string dst_abbrev
 唯一的構造函數，必須提供所有四個字符串。 
string sn("Eastern Standard Time");
string sa("EST");
string dn("Eastern Daylight Time");
string da("EDT");
time_zone_names nyc_names(sn, sa, 
                          dn, da);
 
std::string std_zone_name()
 返回標準的時區名。 
nyc_names.std_zone_name();
// "Eastern Standard Time"
 
std::string std_zone_abbrev()
 返回標準的時區縮寫。 
nyc_names.std_zone_abbrev();
// "EST"
 
std::string dst_zone_name()
 返回夏令時的時區名。 
nyc_names.std_zone_name();
// "Eastern Daylight Time"
 
std::string dst_zone_abbrev()
 返回夏令時的時區縮寫。 
nyc_names.std_zone_abbrev();
// "EDT"

Dst 調整量

dst_adjustment_offsets 類型是三個 時間長度 對象的集合。

語法 說明
例子 
dst_adjustment_offsets(...)
  Parameters:
    time_duration dst_adjust
    time_duration start_offset
    time_duration end_offset
 第一個 time_duration 是夏令時的調整量。第二個是在夏令時開始當天的夏令時開始時間。第三個為在夏令時結束當天的夏令時結束時間。 
dst_adjustment_offsets(hours(1), 
                       hours(2), 
                       hours(2));

夏令時計算規則

夏令時計算規則，稱為 dst_calc_rules, 是一系列對象，將多個合適的 日期生成器 組合起來以形成規則集。單個規則對像通過 dst_calc_rule_ptr 使用。

有關所有五個 dst_calc_rule 類型的完整例子，請見：計算規則舉例。

語法 說明 
partial_date_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 開始和結束規則均為類型 gregorian::partial_date. 
first_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 DST 開始規則為類型 gregorian::first_day_of_the_week_in_month 而結束規則為類型 gregorian::last_day_of_the_week_in_month. 
last_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 開始和結束規則均為類型 gregorian::last_day_of_the_week_in_month. 
nth_last_dst_rule(...)
  Parameters:
    start_rule
    end_rule
 DST 開始規則為類型 gregorian::nth_day_of_the_week_in_month 而結束規則為類型 gregorian::last_day_of_the_week_in_month. 
nth_kday_dst_rule(...)
  Parameters:
    start_rule
    end_rule)
(see note* below)
 兩個規則均為類型 gregorian::nth_day_of_the_week_in_month.

* 註：名字 "nth_kday_dst_rule" 有點模糊。所以使用了更為清晰的名字 "nth_day_of_the_week_in_month_dst_rule".

本地日期時間

簡介 -- 頭文件 -- 從時鐘構造 -- 構造 -- 訪問器 -- 操作符 -- Struct tm 函數

簡介

local_date_time 對象是一個時間點加上一個相應時區。該時間在內部表示為 UTC.

頭文件

包含單個頭文件即可引入所有 boost::local_time 類型、函數和 IO 操作符。 

      #include "boost/date_time/local_time/local_time.hpp"

從時鐘構造

從時鐘創建一個 local_date_time 對象，精度可以是秒或次秒級。

語法 例子 
local_microsec_clock(...)
  Return Type:
    local_date_time
  Parameter:
    time_zone_ptr
 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time ldt = 
  local_microsec_clock::local_time(
    zone);
 
local_sec_clock(...)
  Return Type:
    local_date_time 
  Parameter:
    time_zone_ptr
 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time ldt = 
  local_sec_clock::local_time(zone);

構造

要構造一個 local_date_time 對象，可以用一個 ptime 加一個 time_zone_ptr 來構造，其中 ptime 表示 UTC 時間。從一個帶有日期、time_duration 和 time_zone_ptr 的 wall-clock 表示進行構造，要解決以下複雜性。

從一個 wall-clock 表示進行構造可能導致對某個時區進行不同的位移，這取決於該時區的夏令時規則。這意味著也可能會創建出一個不存在的或重複的，以UTC表示的 local_date_time. 這種情況會發生在剛好轉入夏令時和從夏令時轉出的時候。用戶有兩個選擇來處理這種情況：用一個 bool 標誌來表示該時間是否為夏令時，或者使用一個 enum 來表示遇到這種情形時要做什麼。

當給定的 time_zone 沒有夏令時規則時，該 bool 標誌將被忽略。當給定的時間標籤的夏令時狀態被計算出來並且與該標誌不匹配時，將拋出一個 local_time::dst_not_valid 異常。如果時間標籤是無效的(即不存在)，則拋出 local_time::time_label_invalid 異常。

在 local_date_time::DST_CALC_OPTIONS enum 是有兩個元素：EXCEPTION_ON_ERROR 和 NOT_DATE_TIME_ON_ERROR. 可能拋出的異常是 local_time::ambiguous_result 或 local_time::time_label_invalid. 如果時間標籤無效或不明確時，NOT_DATE_TIME_ON_ERROR 將時間值設為特定的 local_time::not_a_date_time.

語法 說明
例子 
local_date_time(...)
  Parameters:
    posix_time::ptime
    time_zone_ptr
 給定的時間應為 UTC. 因此給定時間將被根據時區的偏移量來調整。 
// 3am, 2004-Nov-05 本地時間
ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
 
local_date_time(...)
  Parameters:
    date
    time_duration 
    time_zone_ptr
    bool
 傳入的時間信息被理解為在被傳入時區的時間。必須傳入 DST 標誌以表示該時間是否為夏令時。可能拋出 dst_not_valid 或 time_label_invalid 異常。 
date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
  new posix_time_zone(z));
local_date_time nyc(d, td, 
                    zone, false);
 
local_date_time(...)
  Parameters:
    date
    time_duration
    time_zone_ptr
    DST_CALC_OPTIONS
 被傳入的時間信息被理解為在被傳入時區的時間。DST 標誌會根據指定規則計算出來。可能拋出 ambiguous_result 或 time_label_invalid 異常。 
date d(2004,Nov,5);
time_duration td(5,0,0,0);
string z("PST-8PDT,M4.1.0,M10.1.0")
time_zone_ptr zone(
  new posix_time_zone(z));
local_date_time nyc(d, td, zone, 
  NOT_DATE_TIME_ON_ERROR);
 
local_date_time(local_date_time);
 複製構造函數。 
local_date_time az_2(az);
 
local_date_time(...)
  Parameters:
    special_values
    time_zone_ptr
 特殊值構造函數。 
time_zone_ptr zone(
  new posix_time_zone("MST-07")
);
local_date_time nadt(not_a_date_time, 
                     zone);
// 缺省為 NULL time_zone_ptr
local_date_time nadt(pos_infin);

訪問器

語法 說明
例子 
time_zone_ptr zone()
 通過一個 time_zone_ptr 返回相關聯的 time_zone 對象。 











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_dst()











      		











      判斷時間值是否在相關時區的DST中。











    












    











       










    












    












      
      
      
      
      
      
      
      
      
      
      
      
ptime utc_time()











      		











      將本地時間轉為UTC值。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5












            		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
ptime local_time()











      		











      返回該對象的本地時間(Wall-clock)。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
ptime pt(date(2004,Nov,5), 
         hours(10));
time_zone_ptr zone(
  new posix_time_zone("MST-07"));
local_date_time az(pt, zone);
az.utc_time(); // 10am 2004-Nov-5
az.local_time(); // 3am 2004-Nov-5











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_in(...)
  Return Type:
    local_date_time 
  Parameters:
    time_zone_ptr
    time_duration











      		











      給定某個時區，返回該時區與調用對像相同UTC時間的 local_date_time，可能會加上一段 time_duration.











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time nyc = az.local_time_in(nyc_zone);
// nyc == 7am 2004-Nov-5












            		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_infinity() const











      		











      返回 true 如果 local_date_time 為正無限或負無限。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time ldt(pos_infin); 
ldt.is_infinity(); // --> true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_neg_infinity() const











      		











      返回 true 如果 local_date_time 為負無限。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time ldt(neg_infin);
ldt.is_neg_infinity(); // --> true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_pos_infinity() const











      		











      返回 true 如果 local_date_time 為正無限。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time ldt(neg_infin); 
ldt.is_pos_infinity(); // --> true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_not_a_date_time() const











      		











      返回 true 如果該值不是一個有效日期。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time ldt(not_a_date_time);
ldt.is_not_a_date_time(); // --> true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_special() const











      		











      返回 true 如果 local_date_time 為任一 special_value
      











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time ldt(pos_infin); 
local_date_time ldt2(not_a_date_time);
time_zone_ptr 
  mst(new posix_time_zone("MST-07"));
local_date_time 
  ldt3(local_sec_clock::local_time(mst));
ldt.is_special(); // --> true
ldt2.is_special(); // --> true
ldt3.is_special(); // --> false











      		










    












  
  
  
  
  
  
  
  
  
  
  



























  















操作符



























  
  
  












    語法











    說明











  












  











    例子










  












  
  











    












      
      
      
      
      
      
      
      
      
      
      
      
operator<<











      		











      流輸出操作符。該操作符是 v1.33
中所增加的對 date_time 的 IO 的一部分。有關詳情請見 日期時間 IO 一節。缺省的輸出請見下例。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr zone(new posix_time_zone("MST-07");
local_date_time ldt(date(2005,Jul,4),
                    hours(20), 
                    false);
std::cout << ldt << std::endl;
// "2005-Jul-04 20:00:00 MST"
          











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator>>











      		











      流輸入操作符。該操作符是 v1.33
中所增加的對 date_time 的 IO 的一部分。有關詳情請見 日期時間 IO 一節。當前 ，local_date_time
對像只能使用 Posix 時區字符串進行流輸入。有關 Posix 時區字符串的完整描述請見 posix_time_zone 類的相關文檔。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
stringstream ss;
ss.str("2005-Jul-04 20:00:00 MST-07");
ss >> ldt;
          











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator==, operator!=,
operator>, operator<,
operator>=, operator<=











      		











      完整的比較操作符。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
ldt1 == ldt2, 等等











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator+, operator+=,
operator-, operator-=











      		











      local_date_time 和日期長度類型間的加法、減法以及相關簡寫操作符。日期長度類型包括有：days, months, 和 years.











    












    











      
      
      
      
      
      
      
      
      
      
      
      
ldt + days(5), 等等











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator+, operator+=,
operator-, operator-=











      		











      local_date_time 和 time_duration 間的加法、減法以及相關簡寫操作符。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
ldt + hours(5), 等等











      		










    












  
  
  
  
  
  
  
  
  
  
  




























Struct tm 函數













系統提供了將 local_date_time 對像轉換為 tm 結構的函數。



























  
  
  












    語法











    說明











  












  











    例子










  












  
  











    












      
      
      
      
      
      
      
      
      
      
      
      
tm to_tm(local_date_time)











      		











      將 local_date_time 對像轉換為 tm 結構的函數。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 6am, 2005-Jul-05 本地時間
std::string z("EST-05EDT,M4.1.0,M10.1.0");
ptime pt(date(2005,Jul,5), 
         hours(10));
time_zone_ptr zone( new posix_time_zone(z));
local_date_time ldt(pt, zone);
tm ldt_tm = to_tm(ldt);
/* tm_year => 105
   tm_mon  => 6
   tm_mday => 5
   tm_wday => 2 (星期二)
   tm_yday => 185
   tm_hour => 6
   tm_min  => 0
   tm_sec  => 0
   tm_isddst => 1 */












	  		










    












  
  
  
  
  
  
  
  
  
  
  
















































本地時間段
















































簡介 --
  頭文件 --
  構造 --
  訪問器 --
  操作符


簡介













類 boost::local_time::local_time_period
提供了對兩個本地時間之間的範圍的直接表示。時間段可以通過簡化程序的條件邏輯來簡化一些計算類型。 













由相同的開始點與結束點，或者由開始點與長度為零的時間長度所構建的時間段，被稱為零長度時間段。零長度時間段被認為是無效的時間段(但是構建一個無效時間段卻是完全合法的)。對於這些時間段，last 時間點總是比 begin 時間點小一個時間單元。
  















頭文件














    













#include "boost/date_time/local_time/local_time.hpp" //包含所有類型和 i/o
或
#include "boost/date_time/local_time/local_time_types.hpp" //只有類型沒有 i/o














  















構造














    



























  
  
  












    語法











    說明











  












  











    例子










  












  
  











    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period(...)
  Parameters:
    local_date_time beginning
    local_date_time end











      		











       創建一個 [begin, end) 的時間段。如果 end <= begin 則時間段被定義為無效時間段。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg(ptime(date(2005,Jan,1),hours(0)), zone);
local_date_time 
  end(ptime(date(2005,Feb,1),hours(0)), zone);
// period for the entire month of Jan 2005
local_time_period ltp(beg, end);












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period(...)
  Parameters:
    local_date_time beginning
    time_duration length











      		











      創建一個 [begin, begin+len) 時間段，其中 end 為
begin+len. 如果 len <= 0 則時間段被定義為無效時間段。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg(ptime(date(2005,Jan,1),hours(0)), zone);
// period for the whole day of 2005-Jan-01
local_time_period ltp(beg, hours(24));












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period(local_time_period rhs)











      		











      複製構造函數。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_time_period ltp1(ltp);











      		










    












  
  
  
  
  
  
  
  
  
  
  



























  















訪問器














    



























  
  
  












    語法











    說明











  












  











    例子










  












  
  











    












      
      
      
      
      
      
      
      
      
      
      
      
local_date_time begin()











      		











      返回該時間段的第一個 local_date_time.











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1)),hours(0)), zone);
local_time_period ltp(ldt, hours(2));
ltp.begin(); // => 2005-Jan-01 00:00:00












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_date_time last()











      		











      返回該時間段的最後一個 local_date_time 











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.last(); // => 2005-Jan-01 01:59:59.999999999












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_date_time end()











      		











      返回時間段的 last 之後的時間點











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.end(); // => 2005-Jan-01 02:00:00












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
time_duration length()











      		











      返回時間段的長度。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  ldt((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(ldt, hours(2));
ltp.length(); // => 02:00:00












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool is_null()











      		











      返回 True 如果時間段是無效的。例如：end 小於等於 begin.











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg((ptime(date(2005,Feb,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Jan,1),hours(0))), zone);
local_time_period ltp(beg, end);
ltp.is_null(); // => true












	    		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool contains(local_date_time)











      		











      返回 True 如果 local_date_time 位於時間段內。零長度時間段不能包含任何時間點。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
time_zone_ptr 
  zone(new posix_time_zone("MST-07"));
local_date_time 
  beg((ptime(date(2005,Jan,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,1),hours(0))), zone);
local_time_period jan_mst(beg, end);

local_date_time 
ldt((ptime(date(2005,Jan,15),hours(12))), zone);
jan_mst.contains(ldt); // => true

local_time_period zero(beg, beg);
zero.contains(beg); // false











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool contains(local_time_period)











      		











      返回 True 如果給定時間段位於本時間段內。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 使用前例中的 jan_mst 時間段

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_time_period ltp(beg, hours(24));

jan_mst.contains(ltp); // => true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
bool intersects(local_time_period)











      		











      返回 True 如果兩個時間段交叉。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 使用前例中的 jan_mst 時間段

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

jan_mst.intersects(ltp); // => true











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period intersection(local_time_period)











      		











      計算兩個時間段的交集。如果不相交則返回空。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 使用前例中的 jan_mst 時間段

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

local_time_period res(jan_mst.intersection(ltp));
// 結果 => 2005-Jan-07 00:00:00 至
// 2005-Jan-31 23:59:59.999999999 (包含)











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period merge(local_time_period)











      		











      返回兩個時間段的並集。如果不相交則返回空。











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 使用前例中的 jan_mst 時間段

local_date_time 
  beg((ptime(date(2005,Jan,7),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Feb,7),hours(0))), zone);
local_time_period ltp(beg, end);

local_time_period res(jan_mst.merge(ltp));
// 結果 => 2005-Jan-07 00:00:00 至
// 2005-Feb-06 23:59:59.999999999 (包含)











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
local_time_period span(local_time_period)











      		











      合併兩個時間段及其間隔，即 begin = min(p1.begin, p2.begin) 且 end = max(p1.end , p2.end).











    












    











      
      
      
      
      
      
      
      
      
      
      
      
// 使用前例中的 jan_mst 時間段

local_date_time 
  beg((ptime(date(2005,Mar,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Apr,1),hours(0))), zone);
local_time_period mar_mst(beg, end);

local_time_period res(jan_mst.span(mar_mst));
// 結果 => 2005-Jan-01 00:00:00 至
// 2005-Mar-31 23:59:59.999999999 (包含)











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
void shift(time_duration)











      		











      為 begin 和 end 同時加上一個時間長度











    












    











      
      
      
      
      
      
      
      
      
      
      
      
local_date_time 
  beg((ptime(date(2005,Mar,1),hours(0))), zone);
local_date_time 
  end((ptime(date(2005,Apr,1),hours(0))), zone);
local_time_period mar_mst(beg, end);

mar_mst.shift(hours(48));
// mar_mst => 2005-Mar-03 00:00:00 至
// 2005-Apr-02 23:59:59.999999999 (包含)











      		










    












  
  
  
  
  
  
  
  
  
  
  



























  















操作符














    



























  
  
  












    語法











    說明











  












  











    例子










  












  
  











    












      
      
      
      
      
      
      
      
      
      
      
      
operator==, operator!=











      		











      相等性比較操作符。兩個時間段相等，如果 ltp1.begin == ltp2.begin && ltp1.last == ltp2.last











    












    











      
      
      
      
      
      
      
      
      
      
      
      
if (ltp1 == ltp2) {...











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator<











      		











      無交叉的順序比較。返回 True 如果 ltp1.end() 小於 ltp2.begin()











    












    











      
      
      
      
      
      
      
      
      
      
      
      
if (ltp1 < ltp2) {...











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator>











      		











      無交叉的順序比較。返回 True 如果 ltp1.begin() 大於 ltp2.end()











    












    











      
      
      
      
      
      
      
      
      
      
      
      
if (ltp1 > ltp2) {... etc











      		










    












    












      
      
      
      
      
      
      
      
      
      
      
      
operator<=, operator>=











      		











      根據其它操作符定義。











    












    











       










    












  
  
  
  
  
  
  
  
  
  
  



























  


















































  










    












      











      Copyright © 2001-2005 CrystalClear Software, Inc











    











  
  
  
  
  
  
  
  
  
  
  

















PrevUpHomeNext