檢視原始碼 calendar (stdlib v6.2)
本地和世界時間、星期幾、日期和時間轉換。
這個模組提供了本地和世界時間的計算、星期幾的計算，以及許多時間轉換函數。
當時間根據當前時區和日光節約時間調整時，時間是本地時間。當時間反映經度零的時間，且未針對日光節約時間進行任何調整時，時間是世界時間。世界協調時間 (UTC) 也稱為格林威治標準時間 (GMT)。
此模組中的時間函數 local_time/0 和 universal_time/0 都會回傳日期和時間。這是因為獨立的日期和時間函數可能會產生相差 24 小時的日期/時間組合。如果其中一個函數在午夜之前呼叫，而另一個函數在午夜之後呼叫，就會發生這種情況。這個問題也適用於 Erlang BIFs 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 轉換函數使用的時間單位。
注意
在 OTP 25.0 中，將
native時間單位新增至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 日之後的日期。
此函數檢查日期是否有效。