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 时间点和本地时间点。

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

近似值

这些限制是有问题的，因为像 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 代码中引入了内存泄漏。Date-time 代码已进行了更改以尽可能避免此问题，但如果您使用的是遗留 IO 选项（VC8 的默认选项不是），则该问题仍然可能发生。更多详情请参见邮件列表存档。

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

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

特别是，对标准 locale 的支持不足限制了库支持 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, and George Heintzelman。