Boost C++ 库

时间点 -- 持续时间 -- 区间（周期） -- 特殊值处理

时间点

本节介绍时间点可以执行的一些基本算术规则。通常，时间点与持续时间结合使用时支持基本算术，如下所示：

      Timepoint + Duration  --> Timepoint
      Timepoint - Duration  --> Timepoint
      Timepoint - Timepoint --> Duration
    

与常规数值类型不同，以下操作是未定义的：

      Duration + Timepoint  --> Undefined
      Duration - Timepoint  --> Undefined
      Timepoint + Timepoint --> Undefined
    

持续时间

持续时间表示一段时间的长度，可以为正值或负值。能够与其他持续时间和简单的整数值进行计算通常很有用。以下描述了这些计算：

      Duration + Duration  --> Duration
      Duration - Duration  --> Duration
      
      Duration * Integer   --> Duration
      Integer  * Duration  --> Duration
      Duration / Integer   --> Duration  (Integer Division rules)
    

区间（周期）

区间逻辑在简化许多日期和时间的“计算”方面非常有用。以下描述了周期提供的基于半开区间的操作。以下操作会根据两个输入时间周期计算新的时间周期：

Timeperiod intersection Timeperiod --> Timeperiod 
  (null interval if no intersection)
Timeperiod merge Timeperiod        --> Timeperiod 
  (null interval if no intersection)
Timeperiod shift Duration          --> Timeperiod 
  (shift start and end by duration amount)
    

此外，周期支持各种计算布尔结果的查询。第一组是与其他时间周期的计算：

  Timeperiod == Timeperiod           --> bool
  Timeperiod < Timeperiod            --> bool (true if lhs.last <= rhs.begin)
  Timeperiod intersects Timeperiod   --> bool
  Timeperiod contains Timeperiod     --> bool
  Timeperiod is_adjacent Timeperiod  --> bool 
    

以下计算是相对于时间点进行的：

  Timeperiod contains Timepoint      --> bool
  Timeperiod is_before Timepoint     --> bool
  Timeperiod is_after Timepoint      --> bool 
    

特殊值处理

对于许多时间问题，持续时间和时间点类型支持特殊值（例如，日期时间无效（NADT）和无穷大）非常有用。通常，日期时间无效（NADT）和无穷大等特殊值应遵循浮点值的规则。请注意，应可能配置基于 NADT 的系统以抛出异常，而不是产生 NADT。

  Timepoint(NADT) + Duration --> Timepoint(NADT)
  Timepoint(∞) + Duration    --> Timepoint(∞)
  Timepoint + Duration(∞)    --> Timepoint(∞)
  Timepoint - Duration(∞)    --> Timepoint(-∞)
    

在对正无穷大和负无穷大执行操作时，库将产生与以下一致的结果。

  Timepoint(+∞) + Duration(-∞) --> NADT
  Duration(+∞) + Duration(-∞)  --> NADT
  Duration(±∞) * Zero          --> NADT
  
  Duration(∞) * Integer(Not Zero) --> Duration(∞)
  Duration(+∞) * -Integer         --> Duration(-∞)
  Duration(∞) / Integer           --> Duration(∞)
    

不可避免的权衡

该库尽最大努力提供用户想要的一切，但存在某些固有的限制，这些限制限制了任何时间库可以做什么。具体来说，用户必须选择在任何特定应用程序中需要以下三个功能中的哪两个：

一些库可能隐式承诺提供所有三项，但如果您实际测试它们，一次只能实现两项。此限制不是任何特定库的设计或实现缺陷；而是国际标准定义不同时间系统方式的结果。让我们看这三种情况：

如果您希望与实际时钟时间完全一致，则必须使用 UTC 或本地时间。如果您通过从一个 UTC 时间减去另一个 UTC 时间来计算持续时间，并且您希望答案精确到秒，那么这两个时间不应相距太远，因为闰秒会影响计数，但它们仅提前约 6 个月确定。使用本地时间，未来的持续时间计算可能会相差一个小时，因为立法者可以并且确实会随意更改 DST 规则。

如果您希望处理未来的实际时钟时间，那么（在一般情况下）您将无法计算精确的持续时间，原因与上面描述的相同。

如果您希望对未来时间进行准确计算，则必须使用 TAI 或等效项，但 TAI 到 UTC 或本地时间的映射取决于闰秒，因此您将无法与实际时钟时间完全一致。

稳定性、可预测性和近似值

以下是一些有助于解释正在发生的事情的底层理论。请记住，时间类型，就像任何抽象数据类型 (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 = negative infinity，则我们称类型 T 是可预测的。

如果对于某些 x_i，t_i = positive infinity，则我们称类型 T 是格式不正确。

否则，我们称类型 T 是不可预测的（这意味着对于某些 x_i，t_i是有限的）。

格式不正确的集合没有实际用途，因此我们不再讨论它们。通俗地说，上面的意思只是一个可预测类型的所有值都是提前已知的，但一个不可预测类型的一些值要到某个特定时间才会被知道。

操作的稳定性

可预测的类型具有几个重要属性：

其实际效果是，持续时间计算可以通过简单的整数减法来实现。可预测类型的示例如 TAI 时间点和公历日期。

不可预测的类型具有完全相反的属性：

不可预测类型的示例如 UTC 时间点和本地时间时间点。

我们可以稍微细化一下，说一个不可预测类型中的一个范围可以是可预测的，并且在那个范围内的值上执行的操作将是稳定的。例如，从 1970-01-01 到现在的 UTC 时间点范围是可预测的，因此在该范围内的持续时间计算将是稳定的。

近似值

这些限制存在问题，因为像 UTC 和本地时间这样重要的时间类型实际上是不可预测的，因此对它们进行的操作有时是不稳定的。然而，作为实际情况，我们经常希望执行这类操作，例如计算未来两个以本地时间指定的时间点之间的持续时间。

库所能做的最好的是提供一个近似值，这通常是可能的，并且对于大多数目的来说已经足够了。当然，文档必须说明答案何时是近似的（因此不稳定）以及误差可能有多大。在许多方面，使用不可预测集合进行计算类似于使用浮点数，其中结果预计只能近似正确。使用可预测集合进行计算则类似于使用整数，其中结果预计是精确的。

对于需要精确答案或无法容忍不稳定性这种情况，用户必须能够指定这一点，然后如果用户请求一个无法获得精确、稳定答案的计算，库应抛出异常。

以下是一些与日期时间域相关的术语：

时间类型的分类

以及其他一些术语：

一些标准的日期时间术语

一些更具实验性的

这些是设计方面的术语

该库的设计目前正在通过 Wiki 和电子邮件讨论进行演变。您可以在以下位置找到更多信息：Boost Wiki GDTL 首页。

日期日历参考

时间

其他 C/C++ 库

JAVA 日期和时间库快速参考

脚本语言库

相关的商业和奇幻页面

分辨率、精确度和准确性

概述 -- 编译选项 -- 编译器/可移植性说明 -- 目录结构 -- 所需的 Boost 库

概述

该库有几个函数需要创建库文件（主要是 to_string、from_string 函数）。大多数库用户可以通过仅包含必需的头文件来有效地使用该库，而无需构建库。如果需要该库，构建目录中的 Jamfile 将生成一个“静态”库（libboost_date_time）和一个包含这些函数的“动态/共享”库（boost_date_time）。请注意，在 Windows 等平台上，无需库即可使用该库可能需要将 BOOST_DATE_TIME_NO_LIB 标志用于编译选项。

编译选项

默认情况下，posix_time 系统在内部使用单个 64 位整数来提供微秒级分辨率。作为替代方案，可以使用 64 位整数和 32 位整数（96 位分辨率）的组合来提供纳秒级分辨率。对于许多不需要纳秒分辨率的应用程序，默认实现可能提供更好的性能和更紧凑的内存使用。

要使用备用分辨率（96 位纳秒），必须在库用户的项目文件中（即 Makefile、Jamfile 等）定义变量BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG。此宏不被 Gregorian 系统使用，因此在构建库时没有影响。

从 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 编译器在日期时间代码方面存在一些问题。最严重的问题是 VC8 标准库 basic_stream 代码中引入的内存泄漏。Date-time 代码已进行了修改以尽可能避免此问题，但如果您使用的是旧版 IO 选项（VC8 上的非默认选项），则问题仍然可能出现。有关更多详细信息，请参阅邮件列表存档。

除了上述问题外，VC8 库的某些版本还限制了std::tm结构中允许值的范围为正值。这是 VC8 中新增的限制。效果是 1900 年之前的日期将导致异常。不幸的是，这个问题没有简单的解决方法。请注意，VC8 的新 64 位版本似乎没有此限制。

这些编译器支持该库的所有方面，但不支持wstring/wstream输出。

特别是，对标准区域设置支持的缺乏限制了该库支持 iostream 输入输出的能力。对于这些编译器，提供了一组更有限的基于字符串的输入输出。一些具有此限制的编译器/标准库包括：

现已放弃对某些旧编译器的官方支持。这包括：

Visual Studio & STLPort

Visual Studio（7.0 和 7.1）和 STLPort 存在一个已知问题。构建错误通常会引用类型问题或“无可用转换”，并尝试使用wchar_t实例化模板。STLPort 的默认构建不支持wchar_t。此问题有两种可能的解决方法。最简单的方法是用户可以构建不带宽流/字符串等的 date_time。另一种方法是使用wchar_t支持重新构建 STLPort。

要构建不带宽流/字符串等的 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以使用正确的工具集）

使用wchar_t支持重新构建 STLPort 涉及在 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                   -- common headers and template code
/boost/date_time/gregorian         -- Gregorian date system header files
/boost/date_time/posix_time        -- Posix time system headers
/boost/date_time/local_time        -- Local time system headers
/libs/date_time/build              -- build files and output directory
/libs/date_time/test               -- test battery for generic code
/libs/date_time/test/gregorian     -- test battery for the Gregorian system
/libs/date_time/test/posix_time    -- test battery for the posix_time system
/libs/date_time/test/local_time    -- test battery for the local_time system
/libs/date_time/example/gregorian  -- example programs for dates
/libs/date_time/example/posix_time -- time example programs
/libs/date_time/example/local_time -- nifty example programs
/libs/date_time/src/gregorian      -- cpp files for libboost_date_time
/libs/date_time/src/posix_time     -- empty (one file, but no source code...)

所需的 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.73 到 1.74 的更改

从 Boost 1.72 到 1.73 的更改

从 Boost 1.41 到 1.44 的更改 (date_time 1.08 到 1.09)

从 Boost 1.40 到 1.41 的更改 (date_time 1.07 到 1.08)

Boost 1.38至1.40（date_time 1.06至1.07）的更改

Boost 1.34至1.38（date_time 1.05至1.06）的更改

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 sec/hour
seconds(1).total_nanoseconds() == 1000000000

time_duration td(5,0,0); //5 hours
td = -td; //-5 hours

Boost 1.29至1.30（date_time 1.00至1.01）的更改

注意：partial_date类的接口（请参阅date_algorithms）已更改。构造参数的顺序已更改，这将导致某些代码执行失败。此更改是为了支持更通用的本地时间调整代码。因此，不再是指定partial_date pd(Dec,25)，代码需要更改为partial_date pd(25, Dec)；

许多人对这个库的发展做出了贡献。特别是Hugo Duncan和Joel de Guzman在移植到各种编译器方面提供了帮助。对于概念和设计的初步开发，Corwin Joy和Michael Kenniston值得特别感谢。还要特别感谢Michael撰写了文档中的理论和权衡部分。Dave Zumbro提供了初步的灵感和明智的建议。非常感谢Boost的审稿人和用户，包括：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和George Heintzelman。