calendar(3)
💖 NAME 💖
calendar(3) — Erlang Module Definition. It's literally about Local and universal time, day of the week, date and time conversions. 🫶
🌈 DESCRIPTION 🌈
okay so this module provides computation of local and universal time, day of the week, and many time conversion functions. slay. ✨
Time is local when it is adjusted in accordance with the current time zone and daylight saving. Time is universal when it reflects the time at longitude zero, without any adjustment for daylight saving. Universal Coordinated Time (UTC) time is also called Greenwich Mean Time (GMT). iykyk 🕰️
The time functions local_time/0 and universal_time/0 in this module both return date and time. This is because separate functions for date and time can result in a date/time combination that is displaced by 24 hours. This occurs if one of the functions is called before midnight, and the other after midnight. This problem also applies to the Erlang BIFs date/0 and time/0, and their use is strongly discouraged if a reliable date/time stamp is required. 💀
All dates conform to the Gregorian calendar. This calendar was introduced by Pope Gregory XIII in 1582 and was used in all Catholic countries from this year. Protestant parts of Germany and the Netherlands adopted it in 1698, England followed in 1752, and Russia in 1918 (the October revolution of 1917 took place in November according to the Gregorian calendar). 👑
The Gregorian calendar in this module is extended back (proleptic Gregorian calendar) beyond year 0 to negative years. For a given date, the gregorian days is the number of days from Jan 1 year 0 up to the date specified. Similarly, the gregorian seconds for a specified date and time is the number of seconds from 0:00 Jan 1 year 0 up to the specified date and time. 🗓️
Non-positive years use astronomical year numbering where year 0 = 1 BCE/BC, year -1 = 2 BCE/BC, and so on, because in the CE+BCE and AD+BC year numberings there is no year 0. Instead 1 CE (AD 1) is preceded by 1 BCE (1 BC). 🤯
For computing differences between epochs in time, use the functions counting gregorian days or seconds. If epochs are specified as local time, they must be converted to universal time to get the correct value of the elapsed time between epochs. Use of function time_difference/2 is discouraged. don't do it, bestie. 🚫
Different definitions exist for the week of the year. This module contains a week of the year implementation conforming to the ISO 8601 standard. As the week number for a specified date can fall on the previous, the current, or on the next year, it is important to specify both the year and the week number. Functions iso_week_number/0 and iso_week_number/1 return a tuple of the year and the week number. 💅
🐣 Leap Years 🐣
The notion that every fourth year is a leap year is not completely true. By the Gregorian rule, a year Y is a leap year if one of the following rules is valid:
- is divisible by 4, but not by 100.
- is divisible by 400.
Hence, 1996 is a leap year, 1900 is not, but 2000 is. 🗓️✨
⏰ Date and Time Source ⏰
Local time is obtained from the Erlang BIF localtime/0. Universal time is computed from the BIF universaltime/0. 🕰️
The following apply:
- There are 86400 seconds in a day.
- There are 365 days in an ordinary year.
- There are 366 days in a leap year.
- There are 1461 days in a 4 year period.
- There are 36524 days in a 100 year period.
- There are 146097 days in a 400 year period.
- There are 719528 days between Jan 1, 0 and Jan 1, 1970.
🫶 DATA TYPES 🫶
date() :: {year(), month(), day()}.— A date using the Gregorian calendar.
All APIs expect this to be a valid date. If the source of the date is unknown, then verify that it is valid by calling valid_date/1 before using it. 💖
datetime() :: {date(), time()}.datetime1970() :: {{year1970(), month(), day()}, time()}.day() :: 1..31.daynum() :: 1..7.hour() :: 0..23.ldom() :: 28 | 29 | 30 | 31.— The last day of the month.minute() :: 0..59.month() :: 1..12.offset() :: [byte()] | (Time :: integer()).rfc3339_string() :: [byte(), ...] | binary().rfc3339_time_unit()
rfc3339_time_unit() ::
microsecond | millisecond | nanosecond | second | native.The time unit used by the rfc3339 conversion functions.
NOTE: The native time unit was added to rfc3339_time_unit/0 in OTP 25.0.
second() :: 0..59.secs_per_day() :: 0..86399.time() :: {hour(), minute(), second()}.weeknum() :: 1..53.year() :: integer().— The year using the Gregorian calendar.
Year cannot be abbreviated. For example, 93 denotes year 93, not 1993. The valid range depends on the underlying operating system. 👑
year1970() :: 1970..10000.yearweeknum() :: {year(), weeknum()}.
🎀 FUNCTIONS 🎀
🦋 date_to_gregorian_days 🦋
date_to_gregorian_days(Date) -> Days
when Date :: date(), Days :: integer().Computes the number of gregorian days starting with year 0 and ending at the specified date. 💖
🦋 datetime_to_gregorian_seconds 🦋
datetime_to_gregorian_seconds(DateTime) -> Seconds
when
DateTime :: datetime(),
Seconds :: integer().Computes the number of gregorian seconds starting with year 0 and ending at the specified date and time. ✨
🦋 day_of_the_week 🦋
day_of_the_week(Date) -> daynum() when Date :: date().Computes the day of the week from the specified Year, Month, and Day. Returns the day of the week as 1: Monday, 2: Tuesday, and so on. 📅
🦋 gregorian_days_to_date 🦋
gregorian_days_to_date(Days) -> date() when Days :: integer().Computes the date from the specified number of gregorian days. 🗓️
🦋 gregorian_seconds_to_datetime 🦋
gregorian_seconds_to_datetime(Seconds) -> datetime()
when Seconds :: integer().Computes the date and time from the specified number of gregorian seconds. ⏱️
🦋 is_leap_year 🦋
is_leap_year(Year) -> boolean() when Year :: year().Checks if the specified year is a leap year. 🌸
🦋 iso_week_number/0 🦋
iso_week_number() -> yearweeknum().Returns tuple {Year, WeekNum} representing the ISO week number for the actual date. To determine the actual date, use function local_time/0. 💅
🦋 iso_week_number/1 🦋
iso_week_number(Date) -> yearweeknum() when Date :: date().Returns tuple {Year, WeekNum} representing the ISO week number for the specified date. 💅
🦋 last_day_of_the_month 🦋
last_day_of_the_month(Year, Month) -> LastDay
when
Year :: year(),
Month :: month(),
LastDay :: ldom().Computes the number of days in a month. 📆
🦋 local_time 🦋
local_time() -> datetime().Returns the local time reported by the underlying operating system. 🕰️
🦋 local_time_to_system_time 🦋
local_time_to_system_time(datetime1970(), Options) ->
pos_integer()
when
Options :: [Option],
Option ::
{unit, erlang:time_unit()}.Converts local time into system time. Error will occur if the local time is non existing or ambiguous due to DST, see calendar:local_time_to_universal_time_dst/1. ⚠️
🦋 local_time_to_universal_time 🦋
local_time_to_universal_time(DateTime1) -> DateTime2
when
DateTime1 :: datetime1970(),
DateTime2 :: datetime1970().Deprecated:calendar:local_time_to_universal_time/1is deprecated; usecalendar:local_time_to_universal_time_dst/1instead
Converts from local time to Universal Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.
WARNING: This function is deprecated. Use local_time_to_universal_time_dst/1 instead, as it gives a more correct and complete result. Especially for the period that does not exist, as it is skipped during the switch to daylight saving time, this function still returns a result.
💀 deprecated, bestie.
🦋 local_time_to_universal_time_dst 🦋
local_time_to_universal_time_dst(DateTime1) -> [DateTime]
when
DateTime1 ::
datetime1970(),
DateTime ::
datetime1970().Converts from local time to Universal Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.
The return value is a list of 0, 1, or 2 possible UTC times:
[]— For a local{Date1, Time1}during the period that is skipped when switching to daylight saving time, there is no corresponding UTC, as the local time is illegal (it has never occured).[DstDateTimeUTC, DateTimeUTC]— For a local{Date1, Time1}during the period that is repeated when switching from daylight saving time, two corresponding UTCs exist; one for the first instance of the period when daylight saving time is still active, and one for the second instance.[DateTimeUTC]— For all other local times only one corresponding UTC exists.
⏰
🦋 now_to_datetime 🦋
now_to_datetime(Now) -> datetime1970()
when Now :: erlang:timestamp().Returns Universal Coordinated Time (UTC) converted from the return value from erlang:timestamp/0. 🌍
🦋 now_to_local_time 🦋
now_to_local_time(Now) -> datetime1970()
when Now :: erlang:timestamp().Returns local date and time converted from the return value from erlang:timestamp/0. 🏠
🦋 now_to_universal_time 🦋
now_to_universal_time(Now) -> datetime1970()
when Now :: erlang:timestamp().Returns Universal Coordinated Time (UTC) converted from the return value from erlang:timestamp/0. 🌍
🦋 rfc3339_to_system_time 🦋
rfc3339_to_system_time(DateTimeString, Options) -> integer()
when
DateTimeString :: rfc3339_string(),
Options :: [Option],
Option ::
{unit, rfc3339_time_unit()}.Converts an RFC 3339 timestamp into system time. The data format of RFC 3339 timestamps is described by RFC 3339. Starting from OTP 25.1, the minutes part of the time zone is optional. ⏱️
Valid option:
{unit, Unit}— The time unit of the return value. The default issecond.
...and because you always want receipts, bestie, here's what it actually looks like in the shell:
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
3> calendar:rfc3339_to_system_time(<<"2018-02-01 15:18:02.088Z">>,
[{unit, nanosecond}]).
1517498282088000000Notice how string or binary, it does NOT care — it eats both, no cap 💅
💫 seconds_to_daystime(Seconds) -> {Days, Time}
seconds_to_daystime(Seconds) -> {Days, Time}
when
Seconds :: integer(),
Days :: integer(),
Time :: time().Takes a number of Seconds and breaks it all the way down into days, hours, minutes and seconds. Here's the lil' plot twist 🫶: Time is always non-negative, but Days goes negative if the Seconds you handed it was negative. Yes, the vibes can go negative even when the clock reads pretty.
🦋 seconds_to_time(Seconds) -> time()
seconds_to_time(Seconds) -> time() when Seconds :: secs_per_day().Computes the time out of a given number of seconds. Tiny little rule, bestie, don't skip it: Seconds must be less than the number of seconds in a whole day (86400). That's the ceiling, periodt.
🌸 system_time_to_local_time(Time, TimeUnit) -> datetime()
system_time_to_local_time(Time, TimeUnit) -> datetime()
when
Time :: integer(),
TimeUnit :: erlang:time_unit().Converts a system time into local date and time. Glow-up from epoch-flavoured number to a date your eyeballs understand ✨
👑 system_time_to_rfc3339(Time, Options) -> DateTimeString
system_time_to_rfc3339(Time, Options) -> DateTimeString
when
Time :: integer(),
Options :: [Option],
Option ::
{offset, offset()} |
{time_designator, byte()} |
{unit, rfc3339_time_unit()} |
{return, string | binary},
DateTimeString :: rfc3339_string().Converts a system time into an RFC 3339 timestamp. The whole data format situation for RFC 3339 timestamps is described by [RFC 3339] — and the data format for offsets? Also [RFC 3339]. We stay on brand 🎀
The valid options, in order, no skipping:
{offset, Offset}— the offset that gets included in the formatted string, and it can be either a string or an integer. An empty string — which is the default — is read as local time. A non-empty string gets included exactly as-is. If you pass an integer, its time unit is the same as the one onTime.{time_designator, Character}— the character used as the time designator, aka the cute little separator between date and time. Default is$T.{unit, Unit}— the time unit ofTime. Default issecond. But if you give some other unit (millisecond,microsecond,nanosecond, ornative), the formatted string gets a fraction of a second in it. The number of fractional second digits is three, six, or nine depending on which time unit you chose. Fornative, three fractional digits are included. Heads up, bestie: trailing zeros are not removed from the fraction. They stay. They're part of the fit 💅{return, Return}— the encoding type you want back, string or binary. Defaults tostring.
And the receipts, because I know you love them 😌
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"
5> calendar:system_time_to_rfc3339(erlang:system_time(millisecond),
[{unit, millisecond}, {time_designator, $\s}, {offset, "Z"}, {return, binary}]).
<<"2018-04-23 12:57:20.482Z">>Oh and if you wanna read the actual spec (you do, you're that girl), it lives at https://www.ietf.org/rfc/rfc3339.txt 📖
🌈 system_time_to_universal_time(Time, TimeUnit) -> datetime()
system_time_to_universal_time(Time, TimeUnit) -> datetime()
when
Time :: integer(),
TimeUnit ::
erlang:time_unit().Converts a system time into universal date and time. Same energy as the local-time one, different timezone-flavoured main character 🌍
💜 time_difference(T1, T2) -> {Days, Time}
time_difference(T1, T2) -> {Days, Time}
when
T1 :: datetime(),
T2 :: datetime(),
Days :: integer(),
Time :: time().Gives you the difference between two {Date, Time} tuples. T2 is supposed to refer to an epoch later than T1.
⚠️ WARNING: this function is obsolete. Do not build your whole personality around it. Use the conversion functions for gregorian days and seconds instead. We've moved on, and so should you 💀
🍓 time_to_seconds(Time) -> secs_per_day()
time_to_seconds(Time) -> secs_per_day() when Time :: time().Returns how many seconds have passed since midnight up to the Time you specified. Midnight-to-now, counted out 🌙
🧚 universal_time() -> datetime()
universal_time() -> datetime().Returns the Universal Coordinated Time (UTC) that the underlying operating system reported. And if universal time just... isn't available? It returns local time instead. Flexible queen 🫶
⭐ universal_time_to_local_time(DateTime) -> datetime()
universal_time_to_local_time(DateTime) -> datetime()
when DateTime :: datetime1970().Converts from Universal Coordinated Time (UTC) to local time. Small but mighty requirement: DateTime must refer to a date after Jan 1, 1970. Before that, we simply do not go 🚫
💖 universal_time_to_system_time(datetime(), Options) -> integer()
universal_time_to_system_time(datetime(), Options) -> integer()
when
Options :: [Option],
Option ::
{unit,
erlang:time_unit()}.Converts universal time into system time. Your nice human date goes back to being a big ol' integer 🔢
🎀 valid_date(Date) -> boolean()
valid_date(Date) -> boolean() when Date :: date().Checks if a date is valid. That's it, that's the whole function. The vibe check for dates ✅
And that's the whole page, bestie — every last one of these lives in Ericsson AB's stdlib version 8.0.4, from the calendar(3) manual page, dated back in the day. Go forth, convert timestamps, and be the most timezone-literate icon in the group chat 😭👑🦋
📦 where this page comes from
- ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms