查看源代码 calendar (stdlib v6.2)
本地时间和世界时间、星期几、日期和时间转换。
此模块提供本地时间和世界时间、星期几以及许多时间转换函数的计算。
当时间根据当前时区和夏令时进行调整时，该时间是本地时间。当时间反映经度为零时的时间，而无需对夏令时进行任何调整时，该时间是世界时间。世界协调时间 (UTC) 也称为格林威治标准时间 (GMT)。
此模块中的时间函数 local_time/0 和 universal_time/0 均返回日期和时间。这是因为单独的日期和时间函数可能会导致日期/时间组合错位 24 小时。如果其中一个函数在午夜之前调用，而另一个函数在午夜之后调用，则会发生这种情况。此问题也适用于 Erlang BIF date/0 和 time/0，如果需要可靠的日期/时间戳，则强烈建议不要使用它们。
所有日期均符合公历。此日历由教皇格列高利十三世于 1582 年引入，并从该年起在所有天主教国家使用。德国和荷兰的新教地区于 1698 年采用，英国于 1752 年采用，俄罗斯于 1918 年采用（根据公历，1917 年的十月革命发生在 11 月）。
此模块中的公历扩展回到了公元 0 年。对于给定日期，公历天数是到指定日期（包括该日期）的天数。类似地，指定日期和时间的公历秒数是到指定日期和时间（包括该日期和时间）的秒数。
对于计算时间中不同时期之间的差异，请使用计算公历天数或秒数的函数。如果时期指定为本地时间，则必须将其转换为世界时间，才能获得时期之间经过的正确时间值。不建议使用函数 time_difference/2。
对于一年中的周数，存在不同的定义。此模块包含符合 ISO 8601 标准的一年中的周数实现。由于指定日期的周数可能落入上一年、本年或下一年，因此务必指定年份和周数。函数 iso_week_number/0 和 iso_week_number/1 返回年份和周数的元组。
闰年
每四年一次闰年的概念并不完全正确。根据格里高利规则，如果满足以下规则之一，则年份 Y 是闰年
- Y 可以被 4 整除，但不能被 100 整除。
- Y 可以被 400 整除。
因此，1996 年是闰年，1900 年不是，但 2000 年是。
日期和时间源
本地时间从 Erlang BIF localtime/0 获取。世界时间从 BIF universaltime/0 计算。
以下适用
- 一天有 86400 秒。
- 普通年有 365 天。
- 闰年有 366 天。
- 4 年内有 1461 天。
- 100 年内有 36524 天。
- 400 年内有 146097 天。
- 公元 0 年 1 月 1 日到 1970 年 1 月 1 日之间有 719528 天。
概要
函数
计算从公元 0 年开始到指定日期结束的公历天数。
计算从公元 0 年开始到指定日期和时间结束的公历秒数。
从指定的 Year、Month 和 Day 计算星期几。将星期几作为 1：星期一，2：星期二，依此类推返回。
从指定的公历天数计算日期。
从指定的公历秒数计算日期和时间。
检查指定的年份是否为闰年。
返回表示实际日期的 ISO 周数的元组 {Year, WeekNum}。要确定实际日期，请使用函数 local_time/0。
返回表示指定日期的 ISO 周数的元组 {Year, WeekNum}。
计算一个月中的天数。
返回底层操作系统报告的本地时间。
从本地时间转换为世界协调时间 (UTC)。DateTime1 必须引用 1970 年 1 月 1 日之后的本地日期。
从本地时间转换为世界协调时间 (UTC)。DateTime1 必须引用 1970 年 1 月 1 日之后的本地日期。
返回从 erlang:timestamp/0 的返回值转换的世界协调时间 (UTC)。
返回从 erlang:timestamp/0 的返回值转换的本地日期和时间。
返回从 erlang:timestamp/0 的返回值转换的世界协调时间 (UTC)。
将 RFC 3339 时间戳转换为系统时间。RFC 3339 时间戳的数据格式由 RFC 3339 描述。从 OTP 25.1 开始，时区的分钟部分是可选的。
将指定的秒数转换为天、小时、分钟和秒。Time 始终为非负数，但如果参数 Seconds 为负数，则 Days 为负数。
从指定的秒数计算时间。Seconds 必须小于每天的秒数 (86400)。
将指定的系统时间转换为本地日期和时间。
将系统时间转换为 RFC 3339 时间戳。
将指定的系统时间转换为世界日期和时间。
返回两个 {Date, Time} 元组之间的差异。T2 应该引用比 T1 晚的时期。
返回自午夜到指定时间以来的秒数。
返回底层操作系统报告的世界协调时间 (UTC)。如果世界时间不可用，则返回本地时间。
从世界协调时间 (UTC) 转换为本地时间。DateTime 必须引用 1970 年 1 月 1 日之后的日期。
此函数检查日期是否有效。
类型
使用公历的日期。
所有 API 都期望这是有效的日期。如果日期的来源未知，则在使用前调用 valid_date/1 验证其是否有效。
-type day() :: 1..31.
-type daynum() :: 1..7.
-type hour() :: 0..23.
-type ldom() :: 28 | 29 | 30 | 31.
该月的最后一天。
-type minute() :: 0..59.
-type month() :: 1..12.
-type rfc3339_string() :: [byte(), ...].
-type rfc3339_time_unit() :: microsecond | millisecond | nanosecond | second | native.
rfc3339 转换函数使用的时间单位。
注意
native时间单位已添加到 OTP 25.0 中的rfc3339_time_unit/0。
-type second() :: 0..59.
-type secs_per_day() :: 0..86399.
-type weeknum() :: 1..53.
-type year1970() :: 1970..10000.
-type year() :: non_neg_integer().
使用公历的年份。
年份不能缩写。例如，93 表示年份 93，而不是 1993。有效范围取决于底层操作系统。
函数
-spec date_to_gregorian_days(Date) -> Days when Date :: date(), Days :: non_neg_integer().
计算从公元 0 年开始到指定日期结束的公历天数。
-spec date_to_gregorian_days(Year, Month, Day) -> Days when Year :: year(), Month :: month(), Day :: day(), Days :: non_neg_integer().
-spec datetime_to_gregorian_seconds(DateTime) -> Seconds when DateTime :: datetime(), Seconds :: non_neg_integer().
计算从公元 0 年开始到指定日期和时间结束的公历秒数。
从指定的 Year、Month 和 Day 计算星期几。将星期几作为 1：星期一，2：星期二，依此类推返回。
-spec gregorian_days_to_date(Days) -> date() when Days :: non_neg_integer().
从指定的公历天数计算日期。
-spec gregorian_seconds_to_datetime(Seconds) -> datetime() when Seconds :: non_neg_integer().
从指定的公历秒数计算日期和时间。
检查指定的年份是否为闰年。
-spec iso_week_number() -> yearweeknum().
返回表示实际日期的 ISO 周数的元组 {Year, WeekNum}。要确定实际日期，请使用函数 local_time/0。
-spec iso_week_number(Date) -> yearweeknum() when Date :: date().
返回表示指定日期的 ISO 周数的元组 {Year, WeekNum}。
-spec last_day_of_the_month(Year, Month) -> LastDay when Year :: year(), Month :: month(), LastDay :: ldom().
计算一个月中的天数。
-spec local_time() -> datetime().
返回底层操作系统报告的本地时间。
-spec local_time_to_universal_time(DateTime1) -> DateTime2 when DateTime1 :: datetime1970(), DateTime2 :: datetime1970().
从本地时间转换为世界协调时间 (UTC)。DateTime1 必须引用 1970 年 1 月 1 日之后的本地日期。
警告
此函数已弃用。请改用
local_time_to_universal_time_dst/1，因为它提供了更正确和完整的结果。特别是对于不存在的时段，因为在切换到夏令时期间会被跳过，此函数仍然会返回结果。
-spec local_time_to_universal_time_dst(DateTime1) -> [DateTime] when DateTime1 :: datetime1970(), DateTime :: datetime1970().
从本地时间转换为世界协调时间 (UTC)。DateTime1 必须引用 1970 年 1 月 1 日之后的本地日期。
返回值是一个包含 0、1 或 2 个可能的 UTC 时间的列表
[]- 对于切换到夏令时期间被跳过的时段中的本地{Date1, Time1}，没有对应的 UTC，因为本地时间是非法的（它从未发生过）。[DstDateTimeUTC, DateTimeUTC]- 对于从夏令时切换回来的重复时段中的本地{Date1, Time1}，存在两个对应的 UTC；一个用于夏令时仍然有效时的第一个时段实例，另一个用于第二个实例。[DateTimeUTC]- 对于所有其他本地时间，仅存在一个对应的 UTC。
-spec now_to_datetime(Now) -> datetime1970() when Now :: erlang:timestamp().
返回从 erlang:timestamp/0 的返回值转换的世界协调时间 (UTC)。
-spec now_to_local_time(Now) -> datetime1970() when Now :: erlang:timestamp().
返回从 erlang:timestamp/0 的返回值转换的本地日期和时间。
-spec now_to_universal_time(Now) -> datetime1970() when Now :: erlang:timestamp().
返回从 erlang:timestamp/0 的返回值转换的世界协调时间 (UTC)。
-spec rfc3339_to_system_time(DateTimeString) -> integer() when DateTimeString :: rfc3339_string().
-spec rfc3339_to_system_time(DateTimeString, Options) -> integer() when DateTimeString :: rfc3339_string(), Options :: [Option], Option :: {unit, rfc3339_time_unit()}.
将 RFC 3339 时间戳转换为系统时间。RFC 3339 时间戳的数据格式由 RFC 3339 描述。从 OTP 25.1 开始，时区的分钟部分是可选的。
有效选项
{unit, Unit}- 返回值的时间单位。默认值为second。
1> calendar:rfc3339_to_system_time("2018-02-01T16:17:58+01:00").
1517498278
2> calendar:rfc3339_to_system_time("2018-02-01 15:18:02.088Z",
[{unit, nanosecond}]).
1517498282088000000-spec seconds_to_daystime(Seconds) -> {Days, Time} when Seconds :: integer(), Days :: integer(), Time :: time().
将指定的秒数转换为天、小时、分钟和秒。Time 始终为非负数，但如果参数 Seconds 为负数，则 Days 为负数。
-spec seconds_to_time(Seconds) -> time() when Seconds :: secs_per_day().
从指定的秒数计算时间。Seconds 必须小于每天的秒数 (86400)。
-spec system_time_to_local_time(Time, TimeUnit) -> datetime() when Time :: integer(), TimeUnit :: erlang:time_unit().
将指定的系统时间转换为本地日期和时间。
-spec system_time_to_rfc3339(Time) -> DateTimeString when Time :: integer(), DateTimeString :: rfc3339_string().
-spec system_time_to_rfc3339(Time, Options) -> DateTimeString when Time :: integer(), Options :: [Option], Option :: {offset, offset()} | {time_designator, byte()} | {unit, rfc3339_time_unit()}, DateTimeString :: rfc3339_string().
将系统时间转换为 RFC 3339 时间戳。
RFC 3339 时间戳的数据格式由 RFC 3339 描述。偏移量的数据格式也由 RFC 3339 描述。
有效选项
{offset, Offset}- 要包含在格式化字符串中的偏移量，可以是字符串或整数。空字符串（默认值）被解释为本地时间。非空字符串将按原样包含。整数的时间单位与Time的时间单位相同。{time_designator, Character}- 用作时间指示符的字符，即日期和时间分隔符。默认值为$T。{unit, Unit}-Time的时间单位。默认值为second。如果给出其他单位（millisecond、microsecond、nanosecond或native），则格式化的字符串将包含秒的小数部分。小数秒的位数是三、六或九位，具体取决于选择的时间单位。对于native，包含三位小数。请注意，不会从小数部分删除尾随零。
1> calendar:system_time_to_rfc3339(erlang:system_time(second)).
"2018-04-23T14:56:28+02:00"
2> calendar:system_time_to_rfc3339(erlang:system_time(second),
[{offset, "-02:00"}]).
"2018-04-23T10:56:52-02:00"
3> calendar:system_time_to_rfc3339(erlang:system_time(second),
[{offset, -7200}]).
"2018-04-23T10:57:05-02:00"
4> calendar:system_time_to_rfc3339(erlang:system_time(millisecond),
[{unit, millisecond}, {time_designator, $\s}, {offset, "Z"}]).
"2018-04-23 12:57:20.482Z"-spec system_time_to_universal_time(Time, TimeUnit) -> datetime() when Time :: integer(), TimeUnit :: erlang:time_unit().
将指定的系统时间转换为世界日期和时间。
-spec time_difference(T1, T2) -> {Days, Time} when T1 :: datetime(), T2 :: datetime(), Days :: integer(), Time :: time().
返回两个 {Date, Time} 元组之间的差异。T2 应该引用比 T1 晚的时期。
警告
此函数已过时。请改用格里高利日和秒的转换函数。
-spec time_to_seconds(Time) -> secs_per_day() when Time :: time().
返回自午夜到指定时间以来的秒数。
-spec universal_time() -> datetime().
返回底层操作系统报告的世界协调时间 (UTC)。如果世界时间不可用，则返回本地时间。
-spec universal_time_to_local_time(DateTime) -> datetime() when DateTime :: datetime1970().
从世界协调时间 (UTC) 转换为本地时间。DateTime 必须引用 1970 年 1 月 1 日之后的日期。
此函数检查日期是否有效。