時間點 -- 時長 -- 時間間隔(時間段) -- 特殊值的處理

時間點

本節描述一些用於時間點的基本算術規則。通常，時間點支持以下與時長的基本算術操作：

      時間點 + 時長  --> 時間點
      時間點 - 時長  --> 時間點
      時間點 - 時間點 --> 時長
    

和普通的算術類型不同，以下操作是未定義的：

      時長 + 時間點  --> 未定義
      時長 - 時間點  --> 未定義
      時間點 + 時間點 --> 未定義
    

時長

時長表示一段時間的長度，它的值可正可負。它通常會與另一個時長或者簡單的整數值進行運算。以下描述了這些運算：

      時長 + 時長  --> 時長
      時長 - 時長  --> 時長
      
      時長 * 整數   --> 時長
      整數  * 時長  --> 時長
      時長 / 整數   --> 時長  (整數除法規則)
    

時間間隔 (時間段)

時間間隔對於簡化日期和時間的很多'運算'是非常有用的。下面描述了基於半開區間的時間段所提供的操作。以下操作基於兩個輸入時間段計算得到新的時間段：

時間段與時間段的交集運算 --> 時間段 
  (如果不相交則為空時間段)
時間段與時間段的合併運算 --> 時間段 
  (如果不相交則為空時間段)
時間段位移一定時長      --> 時間段 
  (將開始時間點和結束時間點位移一定時長)
    

另外，時間段支持多種查詢操作，返回布爾類型的結果。第一組操作是與另一個時間段進行運算：

  時間段 == 時間段      --> bool
  時間段 < 時間段       --> bool (true 如果 lhs.last <= rhs.begin)
  時間段 與 時間段 相交  --> bool
  時間段 包含 時間段     --> bool
  時間段 與 時間段 相鄰  --> bool 
    

以下是與時間點之間的運算：

  時間段 包含 時間點     --> bool
  時間段 早於 時間點     --> bool
  時間段 晚於 時間點     --> bool 
    

特殊值的處理

讓時長和時間點類型支持象無效日期時間(NADT)和無限時長這樣的特殊值，對於很多時間運算的問題來說是很有用的。通常，像無效日期時間(NADT)和無限時長這樣的特殊值同樣遵循浮點數的規則。注意，你可以將系統配置為以拋出異常來替代 NADT 的結果。

  時間點(NADT) + 時長 --> 時間點(NADT)
  時間點(∞) + 時長    --> 時間點(∞)
  時間點 + 時長(∞)    --> 時間點(∞)
  時間點 - 時長(∞)    --> 時間點(-∞)
    

同時對正無限和負無限進行運算時，本庫將產生以下結果：

  時間點(+∞) + 時長(-∞) --> NADT
  時長(+∞) + 時長(-∞)   --> NADT
  時長(±∞) * 零時長     --> NADT
  
  時長(∞) * 整數(非零)  --> 時長(∞)
  時長(+∞) * -整數     --> 時長(-∞)
  時長(∞) / 整數       --> 時長(∞)
    

不可避免的折衷

本庫盡最大努力提供用戶可能想要的所有東西，但是還是存在一些任何時間程序庫都會遇到的固有的限制。尤其是，用戶必須在任何應用都想得到的以下三種能力中選擇兩個：

有的程序庫可能暗中許諾提供所有三種能力，但是如果你真的對它們進行測試，就會發現同時只能有兩個為真。這種限制不是任何特定程序庫的設計或實現上的不足；而是由國際標準所定義的不同時間系統所造成的結果。我們來看看以下三種情形：

如果你想精確吻合 wall-clock 時間，你就必須使用 UTC 或本地時間。如果你通過將兩個 UTC 時間相減來計算得到一個時長，並且希望結果精確到秒，那麼這兩個時間必須不能是很遠的未來，因為閏秒會影響結果而只能確定未來大約6個月的時間。對於本地 時間，未來時長的計算應該限制在一個小時內，因為相關機構可以在未來改變 DST 規則。

如果你想處理未來的 wall-clock 時間，你就不能(一般而言)精確計算時長，原因同上。

如果你想精確計算未來時間，你就必須使用 TAI 或其它等價物，但是從 TAI 到 UTC 或本地時間的映射是依賴於閏秒的，所以你無法與 wall-clock 時間精確吻合。

穩定性、可預言性和近似值

以下是一些基本理論，有助於解釋到底發生了什麼事。記住，一個表示時間的類型，就像任何抽像數據類型(ADT)一樣，是一組值加上在這些值上的操作。

穩定性

如果對應於某個給定值的位組合不會隨時間而變化，就說這個類型的表示法是穩定的。一個具有不穩定表示法的類型對於任何人都不會有太大用處，所以我們應該強調，任何時間類的程序庫都應該只使用穩定的表示法。

如果對於特定操作數進行操作所得到的結果不會隨時間而變化，就說這個類型的操作是穩定的，。

可預言性

集合通常被分為兩類：良好定義的和不良定義的。由於類型也是一種集合，所以我們將這些定義擴展用於類型。對於任意類型 T, 必須存在一個謂詞 is_member( x ) 用於判定某個值 x 是否為類型 T 的成員。這個謂詞必須返回 true, false, 或 dont_know.

如果對於所有 x, is_member( x ) 的返回值要麼是 true 要麼是 false, 那麼我們就說集合 T 是良好定義的。

如果對於某個 x, is_member( x ) 返回 dont_know, 則我們說集合 T 是不良定義的。

這些是在數學上常用的規則。但是，由於時間類型的特殊性質，需要改進這一觀點並創建以下第三種類別：

對於時間類型 T, 必須存在一個謂詞 is_member( x, t ) 用於判定某個值 x 是否為 T 的成員。參數 t 表示對該謂詞進行求值時的時間。對於每個 x_i, 必然存在一個時間 t_i 和一個值 v 滿足：

t_i 是我們可以「找出」 x_i 是否為 T 的成員的時間。現在我們可以為時間類型定義第三種類別：

如果對於所有 x_i, t_i = 負無限，則我們說類型 T 是可預言的。

如果對於某些 x_i, t_i = 正無限，則我們說類型 T 是不良形式的。

否則，我們說類型 T 是不可預言的(這意味著對於某些 x_i, t_i 是一個有限值)。

不良形式的集合實際上沒有什麼用，所以我們後面將不再討論它。坦白地說，以上定義表明了，可預言類型的所有值都是提前可知的，而不可預言類型的某些值則在某個特定時間之前是不可知的。

操作的穩定性

可預言類型有幾個重要的特點：

這些特性的實際效果是，可以用簡單的整數減法來實現時長的運算。可預言類型的例子有：TAI 時間點和格里曆日期。

不可預言類型則剛好具有相反的特點：

不可預言類型的例子有：UTC 時間點和本地時間時間點。

我們可以進一步說，由不可預言類型組成的區間可以是可預言的，而對於在此區間內的值進行操作也將是穩定的。例如，從1970-01-01到現在的 UTC 時間點所組成的區間就是可預言的，所以在此區間內的時長運算也是穩定的。

近似值

以上限制是一個要解決的問題，因為象 UTC 和本地時間這些時間類型實際上是不可預言的，因而對它們的操作有時候是不穩定的。而實際上我們經常需要執行這類操作，如計算用本地時間表示的未來兩個時間點之間的長度。

本庫可以做到的最好情況是提供一個近似值，這一點通常都是可能的，而且對於大多數用途而言也已足夠。當然文檔中必須要指明什麼時候得到的結果是一個 近似值(因而是不穩定的)，並說明可能的誤差有多大。不可預言類型集合上的運算，在很多方面上類似於浮點數的運算，得到的結果只是精確值的一個近似。而可 預言類型集合上的運算則類似於整數運算，其結果總是精確的。

在需要精確結果或不能容忍不穩定性的情形下，用戶必須能夠指明這一點，然後程序庫會在用戶請求一個運算而無法得到精確、穩定的結果時拋出異常。

以下是一些與日期時間領域相關的術語。

時間類型的分類：

其它術語：

一些標準的日期-時間術語：

一些更實驗性的術語：

以下是設計類的術語：

本庫的設計當前正在通過 Wiki 和郵件討論不斷改進。你可以在 Boost Wiki GDTL Start Page 上找到更多的信息。

日期和曆法參考

時間

其它 C/C++ 程序庫

JAVA 日期時間庫速查

腳本語言的程序庫

相關的商業和奇特的網頁

解析度，精度和準確度

簡介 -- 編譯選項 -- 編譯器/可移植性說明 -- 目錄結構 -- 所需的 Boost 庫

簡介

本庫中有少量函數需要創建庫文件(主要是 to_string, from_string 函數)。大多數庫用戶無需構建庫文件就可以正確地使用本庫，只需要包含所需的頭文件即可。如果需要庫文件，位於 build 目錄下的 Jamfile 將生成一個"靜態"庫(libboost_date_time)以及一個"動態/共享"庫(boost_date_time)，其中包含了這些函數。

編譯選項

缺省情況下，posix_time 系統內部使用一個64位整數來提供微秒級的解析度。作為另一個選擇，使用一個64位整數加一個32位整數(共96位精度)，可以提供納秒級的解析度。缺省實現可以提供更好的性能和最小的內存佔用，多數應用程序並不需要納秒級的解析度。

要使用更高的解析度(96位納秒級別)，必須在庫用戶的工程文件(如 Makefile, Jamfile, 等等)中定義變量 BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG. 該宏並不被格里曆系統使用，因此在構建本庫時沒有作用。

和版本1.33一樣，date_time 庫引入了一個新的IO流系統。有些編譯器不能使用這個新系統。對於這些編譯器，早期的("遺留")IO系統仍然可用。不被支持的編譯器將自動選擇遺留系統，但用戶也可以通過定義 USE_DATE_TIME_PRE_1_33_FACET_IO 來強制使用遺留系統。

為方便使用，date_time 提供了一些 額外的時間長度類型。使用這些類型可能會由於「保持為月末」的行為而導致意外結果(完整細節和例子請見 操作可逆性的缺陷)。缺省情況下，這些類型都是可用的。要禁止這些類型，只需在你的工程文件中去定義 BOOST_DATE_TIME_OPTIONAL_GREGORIAN_TYPES 即可。

另一個方便的用法是 date 和 ptime 的缺省構造函數。缺省情況下這些構造函數是可用的。要禁止它們，只需在你的工程文件中定義 DATE_TIME_NO_DEFAULT_CONSTRUCTOR 即可。

編譯器/可移植性說明

Boost Date-Time 庫已經在多個編譯器和平台上進行了構建和測試。但是，有些編譯器和標準庫存在問題。而這些問題中有些可以繞過，其它一些則很難繞過。以下編譯器已知完全支持本庫：

不幸的是，VC8 編譯器對於 date-time 代碼有些問題。其中最嚴重的問題是，在引入VC8標準庫的 basic_stream 代碼時存在內存洩漏。Date-time 的代碼已經盡可能作出修改以避免這一問題，但如果你使用遺留IO選項(這不是VC8的缺省選項)，那麼問題仍會出現。更多細節請見 郵件列表存檔。

除了以上問題，有些版本的VC8庫限制了 std::tm 結構中的值為正值。這是VC8中新增的限制。產生的影響是，1900年以前的日期將引發異常。不幸的是，這一問題沒有替代方案。注意，新的64位版本VC8編譯器不再存在這一限制。

以下編譯器支持本庫除 wstring/wstream 輸出以外的所有功能。

特別地，缺乏標準 locales 支持將會限制本庫的能力，無法支持基於 iostream 的輸入輸出。對於這些編譯器，我們提供一組更為有限的基於字符串的輸入輸出。具有這種限制的編譯器/標準庫包括：

對一些較老的編譯器的官方支持現在已被停止。它們包括：

Visual Studio & STLPort

對於 Visual Studio (7.0 & 7.1) 和 STLPort，有一個著名的問題。構建錯誤通常會指向一個類型問題或 'no acceptable conversion' 以及試圖以 wchar_t 實例化一個模板。STLPort 的缺省構建並不支持 wchar_t. 這個問題有兩個解決方法。最簡單的方法是，用法可以構建不帶寬字符流/寬字符串的 date_time. 另一個方法是，重建 STLPort 以支持 wchar_t.

要構建不帶寬字符流/寬字符串的 date_time, 在 $BOOST_ROOT 下執行以下命令：

bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=<define>BOOST_NO_STD_WSTRING"           \
     --stagedir=... --with-date_time stage

(將省略號換為構建系統的正確路徑，有需要時將 TOOLS 調整為正確的工具集)

要重建 STLPort 以支持 wchar_t，只需在 STLPort 的 makefile中指定 /Zc:wchar_t. 然後從 $BOOST_ROOT 執行以下命令以構建 Date_time:

bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=&native-wchar_t>on"                     \
     --stagedir=... --with-date_time stage

(將省略號換為構建系統的正確路徑，有需要時將 TOOLS 調整為正確的工具集)

目錄結構

目錄樹結構如下：

/boost/date_time                    -- 公用頭文件和模板代碼
/boost/date_time/gregorian          -- 格里曆系統頭文件
/boost/date_time/posix_time         -- Posix 時間系統頭文件
/boost/date_time/local_time         -- 本地時間系統頭文件
/libs/date_time/build               -- 構建文件和輸入目錄
/libs/date_time/test                -- 泛型代碼的測試程序
/libs/date_time/test/gregorian      -- 格里曆系統的測試程序
/libs/date_time/test/posix_time     -- posix_time 系統的測試程序
/libs/date_time/test/local_time     -- local_time 系統的測試程序
/libs/date_time/examples/gregorian  -- dates 的例子程序
/libs/date_time/examples/posix_time -- time 的例子程序
/libs/date_time/examples/local_time -- nifty 的例子程序
/libs/date_time/src/gregorian       -- libboost_date_time 的 cpp 文件
/libs/date_time/src/posix_time      -- 空 (有一個文件，但無源代碼...)

所需的 Boost 庫

date-time 的各個部分依賴於某些 boost 庫。它們包括：

所以這些庫必須被安裝。

本庫提供了大量測試程序，它們位於：

      libs/date_time/test
      libs/date_time/test/gregorian
      libs/date_time/test/posix_time
      libs/date_time/test/local_time
    

目錄中。構建並執行這些測試，以確認庫的安裝是正確的且功能正常。此外，這些測試有利於將庫移植到新的編譯器。最後，這些測試提供了很多在用法舉例一節中沒有明確描述的函數的例子。

從 Boost 1.33 到 1.34 (date_time 1.04 到 1.05)的變更

從 Boost 1.32 到 1.33 的變更(date_time 1.03 到 1.04)

template<class archive_type, class temporal_type>
void save_to(archive_type& ar,
             const temporal_type& tt)
{
  ar << tt;
}

從 Boost 1.31 到 1.32 的變更(date_time 1.02 到 1.03)

days days_until_weekday(date, greg_weekday);
days days_before_weekday(date, greg_weekday);
date next_weekday(date, greg_weekday);
date previous_weekday(date, greg_weekday);

months m(12);
years y(1);
m == y; // true
days d(7);
weeks w(1);
d == w; // true
ptime t(...);
t += months(3);
date d(2004,Jan,30);
d += months(1); //2004-Feb-29
d -= months(1); //2004-Jan-29

ptime p_nadt(not_a_date_time);
ptime p_posinf(pos_infin);
ptime p; // p == NADT
date d;  // d == NADT

std::wstringstream wss;
date d(2003,Aug,21);
wss << d;

date d(not_a_date_time);
std::stringstream ss("2000-FEB-29");
ss >> d; //Feb 29th, 2000
std::wstringstream ws("2000-FEB-29");
ws >> d; //Feb 29th, 2000

從 Boost 1.30 到 1.31 的變更(date_time 1.01 到 1.02)

seconds(1).total_milliseconds() == 1000
seconds(1).total_microseconds() == 1000000
hours(1).total_milliseconds() == 3600*1000 //3600 秒/小時
seconds(1).total_nanoseconds() == 1000000000

time_duration td(5,0,0); //5 小時
td = -td; //-5 小時

從 Boost 1.29 到 1.30 的變更(date_time 1.00 到 1.01)

說明：partial_date 類的接口(見 日期算法) 有所改變。 構造函數的參數順序有所變化，這會導致某些代碼執行失敗。這個改變是為了便於提供更多的本地時間調整泛型代碼。因此，要將使用 partial_date pd(Dec,25) 的代碼改為 partial_date pd(25, Dec);

Many people have contributed to the development of this library. In particular Hugo Duncan and Joel de Guzman for help with porting to various compilers. For initial development of concepts and design Corwin Joy and Michael Kenniston deserve special thanks. Also extra thanks to Michael for writing up the theory and tradeoffs part of the documentation. Dave Zumbro for initial inspiration and sage thoughts. Many thanks to boost reviewers and users including: William Seymour, Kjell Elster, Beman Dawes, Gary Powell, Andrew Maclean, William Kempf, Peter Dimov, Chris Little, David Moore, Darin Adler, Gennadiy Rozental, Joachim Achtzehnter, Paul Bristow, Jan Langer, Mark Rodgers, Glen Knowles, Matthew Denman, and George Heintzelman.