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 = 负无穷大，我们说类型 T 是 可预测的。

如果对于某些 x_i，t_i = 正无穷大，我们说类型 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 函数）。大多数库用户可以有效地使用该库，而无需构建库，只需包含所需的头文件即可。如果需要该库，则 build 目录中的 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 代码中。日期时间代码已更改为尽可能避免这种情况，但如果您使用旧版 IO 选项（VC8 的非默认选项），则问题仍然可能出现。有关更多详细信息，请参见邮件列表存档。

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

这些编译器支持该库的所有方面，除了 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 涉及将 /Zc:wchar_t 放在 STLPort makefile 中。然后应使用以下命令从 $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 类（请参阅 日期算法）的接口已更改。 构造参数的顺序已更改，这将导致某些代码执行失败。 此更改是为了方便更通用的本地时间调整代码。 因此，代码需要从指定 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。