有时候我们会需要写程序去计算两个时间点的差距,以求得年龄、经过了多少的时间,或是否还在某个期限之内等等的信息。日(day)与时、分、秒的差距很好算,因为它们是固定的时间(不考虑闰秒)。但年、月就不一样了,一个月可能有 28 至 31 天,一年可能有 365 或 366 天,我们无法直接将两个时间点(的时间戳记)相减之后去除上一个固定的单位(例如拿相差的秒数去除以 2592000 秒)来算出隔了多少年、月,硬是要这么算肯定是会出错的。

让我们一步一步来吧,从简单的需求开始,再逐步延伸了解怎么正确计算年、月、日和时间的差距。

但我们必须要先厘清我们的输入,也就是「时间点」到底是什么。一般来说我们会使用「时间戳记(timestamp)」来保存时间点,它是一个使用秒、毫秒、奈秒等单位来表示从格林威治标准时间的公元 1970 年 1 月 1 日经过了多少时间的数值,如果这个数是负数,表示这个时间是从格林威治标准时间的公元 1970 年 1 月 1 日再往前算。

举几个例子,时间戳记以毫秒为单位的话,格林威治标准时间的公元 1970 年 1 月 1 日 0 时 0 分 0 秒的时间戳记就是 0,而公元 1970 年 1 月 2 日 0 时 0 分 0 秒的时间戳记就是 86400000。

注意那个「格林威治标准时间」,如果是其他时区的日期时间,必须要先把它换算成格林威治标准时间才能计算时间戳记。例如,台北时区的公元 1970 年 1 月 1 日 0 时 0 分 0 秒的时间戳记就是 -28800000。

参考以下的 JavaScript 程序:

const date = new Date(1970, 1 - 1, 1, 0, 0, 0);

console.log(date.getTimezoneOffset());

const timestamp = date.getTime();

console.log(timestamp); // timestamp in milliseconds

JavaScript 的 Date 对象的「月」是从 0 开始算的。Date 对象提供的 getTime 方法会回传这个 Date 对象的时间戳记(单位:毫秒)。

不考虑年、月和时间,只计算两个时间点相差了几天

把两个时间点相减,再除以一天的时间,就会是天数。十分简单。

const dayDiff = (from: Date, to: Date) => {
    return (to.getTime() - from.getTime()) / 86400000;
};

不考虑年、月,计算两个时间点相差了几天和时分秒

把两个时间点相减,再除以一天的时间,就会是天数。不过这个天数可能会有小数的部份,我们必须要舍弃掉小数,对天取整,再去计算剩下来不足一天的秒数,再把单位换算成时+分+秒。

const dayTimeDiff = (from: Date, to: Date) => {
    let milliseconds = to.getTime() - from.getTime();

    const days = Math.trunc(milliseconds / 86400000);
    milliseconds -= days * 86400000;

    const hours = Math.trunc(milliseconds / 3600000);
    milliseconds -= hours * 3600000;

    const minutes = Math.trunc(milliseconds / 60000);
    milliseconds -= minutes * 60000;

    const seconds = Math.trunc(milliseconds / 1000);
    milliseconds -= seconds * 1000;

    return {
        days,
        hours,
        minutes,
        seconds,
        milliseconds,
    };
};

以上程序需注意到必须要用 trunc(直接取整),而不是 floor(取最接近但小于等于原值的整数)。

考虑年、月,计算两个时间点相差的年、月、日和时间

先介绍一个常见的烂方法,或许它很容易实作,但计算结果肯定是不完全正确的。

这个烂方法是这样的:将格林威治标准时间的公元 1970 年 1 月 1 日 0 时 0 分 0 秒(此时间点的时间戳记为 0)当作是基准值,去计算我们要计算差距的两个时间点的时间戳记的差,再把这个差当作是新的时间戳记,利用编程语言提供的日期函数库再转年、月、日、时、分、秒,然后将它们减去基准值的年、月、日、时、分、秒,此时这组年、月、日、时、分、秒就是原本两个时间点的差距。

// 不要用,这是烂Code!
const dateTimeDiff = (from: Date, to: Date) => {
    const base = new Date(0);

    const newTimestamp = to.getTime() - from.getTime();

    const newDate = new Date(newTimestamp);

    return {
        years: newDate.getFullYear() - base.getFullYear(),
        months: newDate.getMonth() - base.getMonth(),
        days: newDate.getDate() - base.getDate(),
        hours: newDate.getHours() - base.getHours(),
        minutes: newDate.getMinutes() - base.getMinutes(),
        seconds: newDate.getSeconds() - base.getSeconds(),
        milliseconds: newDate.getMilliseconds() - base.getMilliseconds(),
    };
};

这个方法乍看之下好像可行,但稍微细想一下就会发现很不合理。

首先,当 from 比 to 还要更晚时,很明显是完全不能用这个方式运算的。比方说,公元 2001 年 1 月 1 日 0 时 0 分 0 秒至 2000 年 12 月 31 日 0 时 0 分 0 秒,算出来会有 { years: -1, months: 11, days: 30 } 这样诡异的结果,然而正确应是 { days: -1 }。

再来,这个作法显然根本没有考虑到大月、小月和平年闰年的二月的天数各是不一样的。所以像是公元 2000 年 1 月 1 日 0 时 0 分 0 秒至 2000 年 3 月 1 日 0 时 0 分 0 秒,算出来的结果便是 { months: 2, days: 1 },然而正确应是 { months: 2 }。

还有就是使用时间戳记会遇到的夏令时间(Daylight saving time)等会让时间忽快忽慢的问题。以台北时区来说,像是公元 1950 年 1 月 1 日 0 时 0 分 0 秒至 1950 年 6 月 1 日 0 时 0 分 0 秒,算出来的结果是 { months: 5, hours: -1 },但我们想要的答案应该要是 { months: 5 }。

那么该如何才能把日期时间的差距算正确呢?

以下三点极为重要:

  1. 先决定要从哪个时间点开始往前或是往后移动。
  2. 从最大的单位(年)开始移动。当年份和月份移动完,要移动天数的时候,要先判断目前被移动的日期在移动之后的年月下有无超过该月的天数,如果超过就以该月的最后一天算。
  3. 较晚的时间点的当天时间若比较早的时间点的当天时间还要更早。在计算日期的时候,若是要从较早的时间点开始移动,要先把较晚的时间点减 1 天;反之,若是要从较晚的时间点开始移动,要先把较早的时间点加 1 天。最后计算较晚的时间点和较早的时间点的当天时间差时(差会是负数),再把刚才少算的 1 天加回来。

「移动」是什么意思?例如要计算公元 2000年1月1日 至 2001年3月5日 的差距,即公元 2000 年 1 月 1 日要「走」几年、几月、几天才会到 2001 年 3 月 5 日。2000年1月1日 往未来移动 1 年会是 2001年1月1日,2001年1月1日 往未来移动 2 个月会是 2001年3月1日,2001年3月1日 往未来移动 4 天会是 2001年3月5日。所以,公元 2000年1月1日 至 2001年3月5日 的差距为「1 年 2 个月又 4 天」。

即便是同一组的两个时间点,分别从较早的时间点或是较晚的时间点开始移动,也可能会得到不同的差距。

例如公元 2000年8月11日 至 2001年7月10日。2000年8月11日 往未来移动 10 个月会是 2001年6月11日,2001年6月11日 往未来移动 20 天是 2001年7月1日,2001年7月1日 往未来移动 9 天会是 2001年7月10日。所以差距为「10 个月又 29 天」。

但若是反过来,变成公元 2001年7月10日 至 2000年8月11日。2001年7月10日 往过去移动 10 个月会是 2000年9月10日,2000年9月10日 往过去移动 10 天会是 2000年8月31日,2000年8月31日 再往过去移动 20 天会是 2000年8月11日。所以差距为「-10 个月又 -30 天」。有没有,是不是不一样了!

至于以上第二点的「该月最大天数」是在说,假如公元 2013 年 12 月 31 日,往过去移动 1 年又 10 个月,应变成 2 月 29 日,而非 2 月 31 日,也非 2 月 28 日,因为公元 2012 年是闰年。这样的话,目的时间点若是公元 2012 年 2 月 28 日,才能正确地利用 29 减去 28,算出除了 1 年又 10 个月之外还差了 1 天。

第三点是考虑到「当天的时分秒时间」,计算日期的时候把未满一天的差距先扣掉,最后计算时间的时候再加回来,会比较好算。

其实计算时间和日期的差距的方式是有点复杂的,还要判断闰年以及一个月有几天。判断闰年的程序可以参考这篇文章:

所以笔者把这个程序包成了套件,方便重复使用。

Date Differencer

「Date Differencer」是笔者开发的套件,用上面所介绍的方式实作出了正确计算时间和日期的差距的函数,并且还提供把差距加回来的函数。

在 Rust 上使用 Date Differencer

Crates.io

Cargo.toml

date-differencer = "*"
使用方法

date_differencer 这个 crate 提供 date_diff、date_time_diff 两个函数来计算 chrono 这个 crate 的 DateTime 实体的时间差距,也提供 add_date_time_diff 函数计算一个 DateTime 实体加上某个时间差距之后的结果。

use chrono::prelude::*;

use date_differencer::{date_diff, date_time_diff, add_date_time_diff};

let a = Local.with_ymd_and_hms(2022, 4, 6, 0, 0, 0).unwrap();
let b = Local.with_ymd_and_hms(2023, 6, 9, 1, 0, 0).unwrap();

println!("{:?}", date_diff(a, b));
/*
{
    "years": 1,
    "months": 2,
    "days": 3
}
*/

println!("{:?}", date_time_diff(a, b));
/*
{
    "years": 1,
    "months": 2,
    "days": 3,
    "hours": 1,
    "minutes": 0,
    "seconds": 0,
    "nanoseconds": 0
}
*/

println!("{}", add_date_time_diff(a, &date_time_diff(a, b)).unwrap()); // the same as b

在 JavaScript/TypeScript 上使用 Date Differencer

npmjs.com

npm 安装指令

npm install date-differencer
使用方法
import {
    dateDiff, dateTimeDiff, dayDiff, dayTimeDiff,
    addDateTimeDiff, addDayTimeDiff
} from "date-differencer";

const a = new Date(2022, 5, 6, 0);
const b = new Date(2023, 7, 9, 1);

console.log(dateDiff(a, b));
/*
{
    "years": 1,
    "months": 2,
    "days": 3
}
*/

console.log(dateTimeDiff(a, b));
/*
{
    "years": 1,
    "months": 2,
    "days": 3,
    "hours": 1,
    "minutes": 0,
    "seconds": 0,
    "milliseconds": 0
}
*/

console.log(Math.trunc(dayDiff(a, b))); // (365 + 31 + 30 + 3) = 429

console.log(dayTimeDiff(a, b));
/*
{
    "days": 429,
    "hours": 1,
    "minutes": 0,
    "seconds": 0,
    "milliseconds": 0
}
*/

console.log(addDateTimeDiff(a, dateTimeDiff(a, b))); // the same as b
console.log(addDayTimeDiff(a, dayTimeDiff(a, b)));   // the same as b

在网页浏览器上使用 Date Differencer

网页源代码

展示页面