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 函数）。大多数库用户无需构建库即可有效使用该库，只需包含所需的头文件即可。如果需要该库，构建目录中的 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。格里高利系统不使用此宏，因此在构建库时无效。

从 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 年之前的日期将导致异常。遗憾的是，没有简单的解决方法可以解决此问题。请注意，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。