时间格式转换轻松搞定

• 下载源代码 - 27.2 KB

引言

Windows 使用不同的时间格式，并且它们之间的转换路径有限。本文提供了最常见的时间格式之间的全面转换，并讨论了日期和时间为什么如此复杂以及如何保持理智。本文不包含日期和时间的文本表示。

• 时间是最简单的事情
  • 闰年
  • 闰秒
  • 夏令时
  • UTC 偏移量
  • 日历
  • 这意味着什么以及该怎么做？
• 日期和时间处理清单  (2011年11月) 
• 转换库
  • 支持的类型
  • OLE 日期/时间特别棘手
  • 选择存储格式  (2012年4月)  
  • API 参考  (2012年4月) 
• 更多数据
• 链接
• 测试 
• 历史 

isLeapYear = (year % 400 == 0) || ( (year % 4 == 0) && !(year % 100 == 0) )

时间转换库

支持的类型

1) 可以表示的最小单位。获取当前时间的方法可能依赖于以更大步长增加的底层计数器。例如，GetSystemTimeAsFileTime 可能以大约 15 毫秒的时间间隔返回当前时间。
2) 通常是日历开始的那一天。对于连续格式，这是 UTC 中表示为 0 的日期/时间。请注意，有些允许负值，表示在纪元之前。
3) 在一个由 2 个 32 位无符号整数组成的结构中
4) 某些 API 可能有更严格的限制，例如，某些转换函数不接受负的 time_t 值，64 位 time_t 通常限制在 3000 年 12 月 31 日。
5) OLE 日期/时间有点疯狂，详见下文。

OLE 日期特别棘手

OLE 日期 (VT_DATE) 本来可能很棒：它们指定了自纪元（1899 年 12 月 30 日）以来的天数，小数部分表示一天的小数部分（例如，0.5 表示中午）。浮点数允许在纪元附近进行计算以换取长期计算的精度。

与其他线性格式一样，夏令时和闰秒被忽略了。前者可以通过只存储 UTC 来避免，后者是所有格式的问题。但是，在实现中存在两个需要注意的奇怪之处：

负值需要拆分成整数和小数部分：例如，-2.5 表示自纪元以来倒数两天，再加上**向前**半天（即符号应用于整数部分，但不应用于小数部分）。这使得数值错误尤其麻烦，-2 表示“自纪元以来倒数两天”，最终是 1899 年 12 月 28 日。-1.9999999 表示倒回一天，然后几乎向前走一整天，最终停在 1899 年 12 月 30 日之前一点——相差近两天。

纪元的选择是为了使 Excel 与 Lotus 1-2-3 中的一个错误兼容，导致 1900 年 1 月和 2 月出现一些不准确的转换。有关详细信息，请参见下面的链接列表。

选择存储时间戳的格式

对于典型需求，FILETIME 似乎很有前途：高分辨率、足够的范围，并且使用 int64 进行转换和时间跨度计算非常简单。通过简单的 time_t 转换或到 time_t 的转换，可移植性足够好。

time_t (64 位)是默认选择，但您只有一秒的分辨率，这可能不足以满足某些应用程序的需求。它可能是最便携的。某些 API 将范围限制在 3000 年。不惜一切代价避免使用 32 位 time_t。

我建议避免 SYSTEMTIME，因为它是一个平台相关的结构。OLE DATE/TIME——尽管概念上很有趣——只提供半秒分辨率，对负值进行算术运算有误，而且您必须准备好应对数值精度问题。

另一个选择是将字符串存储为一种不区分文化格式。这需要可变长度，并且对于大量数据来说，额外的格式化和解析成本可能是禁止的，但您对实际支持的日期/时间 API 和格式的依赖性会更小。

我目前的赌注是 FILETIME。API 显示了一种将 FILETIME 和 UTC 偏移量打包到 int64 中而没有明显损失的方法，从而可以轻松处理。

API 参考

time_ref, time_const_ref 

此结构充当参数适配器，允许编写接受上述类型引用的函数。通常仅用于参数列表，您不应创建此类型的实例。请参阅TimeConvert中的一个使用它的方法。

struct time_ref
{
   ETimeFmt fmt;

   union
   {
      __time32_t * m_time32_t;
      __time64_t * m_time64_t;
      ...
   }; 

   time_const_ref(__time32_t & m)       : fmt(tftUnix32), m_time32_t(&m) {}
   time_const_ref(__time64_t & m)       : fmt(tftUnix64), m_time64_t(&m) {}
   ...
}

time_const_ref的实现类似，但接受const引用并保存const指针。

TimeConvert  

HRESULT TimeConvert(time_const_ref src, time_ref dst)

将src中传递的时间转换为dst中传递的时间。如果转换失败，dst将保持不变。

Returns

• S_OK 如果转换成功
• E_INVALIDARG 如果自定义转换由于源值超出目标值范围而失败
• 系统转换函数出错代码，如果该方法失败

FileTime, FileTime64

inline unsigned __int64 FileTime64(FILETIME ft)
inline FILETIME FileTime(unsigned __int64 ft64)

在FILETIME结构和 64 位整数之间进行转换。

GetUTCOffset 

GetUTCOffset 计算当前本地时间和 UTC 之间的差值。这包括时区和夏令时（如果适用）。  

没有官方的标准方法可以检索这些数据，我使用的是以下算法：  

• 获取 time_t 作为 UTC 
• 使用 gmtime 将其转换为 struct tm  
• 将此结构传递给 mktime，它假定它是本地时间，减去 UTC 偏移量并转换回 time_t 
• 结果与 UTC 之间的差值就是 UTC 偏移量，只是符号相反。  

(我肯定希望这个算法没有任何问题。)

不过，这有一个烦人的小问题：在获取 UTC 和 UTC 偏移量之间，UTC 偏移量可能会发生变化。我不确定这在实践中有多重要，我可以想象在夏令时变化期间存在一个小的竞争条件，但我不会冒险。

因此，GetUTCOffset 可以选择性地返回用于此偏移量的 UTC 时间。为了保证一致性，计算至少重复两次，如果最后两次计算之间的 UTC 偏移量发生变化，则重复次数更多。当time_t * pNow_utc参数为 NULL 时，不进行重复。

如果您需要当前时间和 UTC 偏移量，但格式不同怎么办？  使用循环，如下例所示（针对 SYSTEMTIME）： 

BOOL ok = FALSE;
SYSTEMTIME st = { 0 };
int utcOffset = 0, utcOffset2 = 0;

do
{
   utcOffset = GetUTCOffset();
   ok = GetSystemTime(&st);
   utcOffset2 = GetUTCOffset();
} while(ok && utcOffset != utcOffset2);

// !ok: GetSystemTime failed, otherwise, you can use st and utcOffset

FmtUTCOffset  

将 UTC 偏移量（以秒为单位，从 GetUTCOffset 返回）格式化为字符串。 当偏移量为 0 时，字符串为空，当分钟为 0 时，则省略分钟。秒始终被忽略。 

它打算与本地时间后的 UTC 前缀一起使用： 

string.Format(_T("%s UTC%s"),  myDateTimeString, FmtUTCOffset(utcOffset)); 

PackFileTime64, UnpackFileTime

典型的编码人员在处理文件格式几次后会发生什么？他会发明一种新的！这正是我在撰写本文时想要避免的。

PackFileTime64 将 FILETIME 值和 UTC 偏移量合并成一个单一的 64 位无符号整数

• FILETIME 的分辨率从 100ns 降低到 12.8µs  (四舍五入到最接近的值)
• UTC 偏移量四舍五入到最接近的 15 分钟倍数，并且必须在 -15..+16h 的范围内（目前，时区范围从 -12h 到 +14h）。

UTC 偏移量直接存储在低位，因为高分辨率很少需要甚至不可用。（在我的系统上，GetSystemTimeAsFileTime 以 15.6 毫秒的步长递增）。

GetPackedFileTimeNow

检索当前的 UTC 时间和 UTC 偏移量作为“打包的 int64”（如上所述）。

更多数据

典型增量

下表显示了连续类型在

时间增量（不包括闰秒、闰日）

1) 经验法则：一年大约有 PI 乘以 10⁷ 秒 
2) 对于非常长的时间范围，您可以按每年 365.25 天计算，以考虑闰年

不同格式下的 UTC 与本地时间

处理夏令时规则变化

为了处理不断变化的夏令时规则，Windows 提供了以下附加 API：

• GetTimeZoneInformationForYear
• GetDynamicTimeZoneInformation
• SetDynamicTimeZoneInformation

我还没有评估它们在多大程度上涵盖了所有变化，不要指望有奇迹。

更多信息

• Raymond Chen 关于时间格式转换
• Eric Lippert 关于 OLE DATE 的事实
• Joel Spolsky 关于 OLE DATE 纪元
• 各种日期计算错误导致的现实生活问题
• Zune 为什么会休眠

测试和实现细节

最困难的不是实际的转换，而是编写测试、找出可靠的转换路径，以及用它们来检查不可靠的路径。这是我使用的转换矩阵：

转换矩阵

使用了以下转换矩阵。绿色表示安全的转换（简单的复制或由系统库提供），红色表示自定义计算。连续格式（time_t、FILETIME、OLE DATE / TIME）之间的转换是线性的，即：
 timeB = timeA * factor + offset.
因此，对每次转换在两个点进行了检查。

(表格也包含在下载的 OpenCalc 文档中)。

历史

这段代码的触发是因为遇到了一个棘手的错误，该错误在一年中的一半时间里才会通过单元测试发现（设置了struct tm的isdst成员）。

• 2011 年 1 月 - 首次发布
• 2011 年 11 月 - 修正了文本中的一个错误值，增加了对 UTC 偏移量的支持
• 2011 年 12 月 - 稍微整理了一下文本流程
• 2012 年 4 月 - 当你让一个程序员处理半打时间格式时会发生什么？他会发明一种新的！
  添加了 PackFileTime64、UnpackFileTime、GetPackedFileTimeNow

最后

这是一个非常枯燥的话题，所以我引用了电影中一句我喜欢的关于时间的台词（为了国际观众已适当修改）。

让我解释几件事。

时间是短暂的。这是第一件事。

对于黄鼠狼来说，时间是黄鼠狼。
对于英雄来说，时间是英雄式的。
如果你温柔，你的时间就是温柔的。
如果你匆忙，时间就飞逝。
如果你是它的主人，时间就是仆人。
如果你是它的狗，时间就是你的神。
我们是时间的创造者
时间的受害者
以及时间的杀手。

时间是永恒的。
这是第二件事。

你就是时钟，卡西尔。
出自：温·温德斯 1993 年电影《直到世界尽头》