calendar(3erl)

✨ NAME ✨

Okay so bestie, this is calendar(3erl) 💖 — the Erlang module for local and universal time, day of the week, date and time conversions. It’s literally the time-and-date main character of this manual, no cap. 🕰️✨

---

🦋 DESCRIPTION 🦋

This module gives you computation of local and universal time, day of the week, and a whole bunch of time conversion functions. It’s giving “time math but make it Erlang.” 💅

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) is also called Greenwich Mean Time (GMT). 🌍⏱️

The time functions local_time/0 and universal_time/0 in this module both return date and time. Why? 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. So like… don’t do that if you need a trustworthy timestamp, fr fr. 🚫🕛

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. History is wild, bestie. 🎀📅

The Gregorian calendar in this module is extended back to year 0. For a given date, the gregorian days is the number of days up to and including the date specified. Similarly, the gregorian seconds for a specified date and time is the number of seconds up to and including the specified date and time. ⭐

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. 👀⚠️

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. 🗓️👑

---

💅 DATA TYPES 💅

• datetime() = {date(), time()} — your classic date + time combo. 🫶
• datetime1970() = {{year1970(), month(), day()}, time()} — same energy, but with the year1970() range in the date slot. ✨
• date() = {year(), month(), day()} — date tuple, iconic. 🎀
• year() = integer() >= 0 — year as a non-negative integer.

Year cannot be abbreviated. For example, 93 denotes year 93, not 1993. The valid range depends on the underlying operating system. The date tuple must denote a valid date. 🗓️💀

• year1970() = 1970..10000 — the 1970 to 10000 year range. 🌈
• month() = 1..12 — months, 1 through 12, as expected. 💖
• day() = 1..31 — days, 1 through 31. 🌸
• time() = {hour(), minute(), second()} — time tuple, periodt. ⏰
• hour() = 0..23 — hours, 0 through 23. 🕛
• minute() = 0..59 — minutes, 0 through 59. 🕧
• second() = 0..59 — seconds, 0 through 59. 🕐
• daynum() = 1..7 — day number range, 1 through 7. 📆
• ldom() = 28 | 29 | 30 | 31 — last day of month possibilities, lowkey iconic. 🗓️
• yearweeknum() = {year(), weeknum()} — year + week number tuple. 👑
• weeknum() = 1..53 — week number range, 1 through 53. 🗓️✨
• rfc3339_time_unit() = microsecond | millisecond | nanosecond | second | native — the RFC 3339 time units. 💅

Note: The native time unit was added to rfc3339_time_unit() in OTP 25.0. 🫶

✨ EXPORTS ✨

okay bestie, here’s the whole export list — every one, in order, zero skips, no cap. 💅

💖 date_to_gregorian_days

date_to_gregorian_days(Date) -> Days

date_to_gregorian_days(Year, Month, Day) -> Days

Types:

Date = date()
Year = year()
Month = month()
Day = day()

Computes the number of gregorian days starting with year 0 and ending at the specified date. It’s giving calendar math main character energy. ✨

💖 datetime_to_gregorian_seconds

datetime_to_gregorian_seconds(DateTime) -> Seconds

Types:

DateTime = datetime()
Seconds = integer() >= 0

Computes the number of gregorian seconds starting with year 0 and ending at the specified date and time. Yes, that’s a whole lotta seconds. 😭

💖 day_of_the_week

day_of_the_week(Date) -> daynum()

day_of_the_week(Year, Month, Day) -> daynum()

Types:

Date = date()
Year = year()
Month = month()
Day = day()

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. Slay, now you know what day it is. 🗓️

💖 gregorian_days_to_date

gregorian_days_to_date(Days) -> date()

Types:

Days = integer() >= 0

Computes the date from the specified number of gregorian days. Reverse math, iconic. 💫

💖 gregorian_seconds_to_datetime

gregorian_seconds_to_datetime(Seconds) -> datetime()

Types:

Seconds = integer() >= 0

Computes the date and time from the specified number of gregorian seconds. So many seconds, so little time. ⏳

💖 is_leap_year

is_leap_year(Year) -> boolean()

Types:

Year = year()

Checks if the specified year is a leap year. Leap year check: passed or not passed, no in-between. 🐸

💖 iso_week_number

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(Date) -> yearweeknum()

Types:

Date = date()

Returns tuple {Year, WeekNum} representing the ISO week number for the specified date. Week number realness. 🎀

💖 last_day_of_the_month

last_day_of_the_month(Year, Month) -> LastDay

Types:

Year = year()
Month = month()
LastDay = ldom()

Computes the number of days in a month. Some months really said “I have 31 days and I’m not sorry.” 💀

💖 local_time

local_time() -> datetime()

Returns the local time reported by the underlying operating system. Your OS said “here’s the local vibe.” 🕰️

💖 local_time_to_universal_time

local_time_to_universal_time(DateTime1) -> DateTime2

Types:

DateTime1 = DateTime2 = datetime1970()

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 queen, we still respect her, but use the other one, bestie. 🫶

💖 local_time_to_universal_time_dst

local_time_to_universal_time_dst(DateTime1) -> [DateTime]

Types:

DateTime1 = 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.

DST said “time is a social construct” and this function is just coping beautifully. 🌀

💖 now_to_datetime

now_to_datetime(Now) -> datetime1970()

Types:

Now = erlang:timestamp()

Returns Universal Coordinated Time (UTC) converted from the return value from erlang:timestamp/0. UTC glow-up. ✨

💖 now_to_local_time

now_to_local_time(Now) -> datetime1970()

Types:

Now = erlang:timestamp()

Returns local date and time converted from the return value from erlang:timestamp/0. Local time, local vibes. 🌸

💖 now_to_universal_time

now_to_universal_time(Now) -> datetime1970()

Types:

Now = erlang:timestamp()

Returns Universal Coordinated Time (UTC) converted from the return value from erlang:timestamp/0. Another UTC baddie, periodt. 👑

💖 rfc3339_to_system_time

rfc3339_to_system_time(DateTimeString) -> integer()

rfc3339_to_system_time(DateTimeString, Options) -> integer()

Types:

DateTimeString = rfc3339_string()
Options = [Option]
Option = {unit, rfc3339_time_unit()}
rfc3339_string() = [byte(), ...]

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. Glow-up for time zones, honestly. 🌈

Valid option:

• {unit, Unit} — The time unit of the return value. The default is 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

💖 seconds_to_daystime

seconds_to_daystime(Seconds) -> {Days, Time}

Types:

Seconds = Days = integer()
Time = time()

Converts a specified number of seconds into days, hours, minutes, and seconds. Time is always non-negative, but Days is negative if argument Seconds is. Negative seconds really said “I contain multitudes.” 😭

💖 seconds_to_time

seconds_to_time(Seconds) -> time()

Types:

Seconds = secs_per_day()
secs_per_day() = 0..86400

Computes the time from the specified number of seconds. Seconds must be less than the number of seconds per day (86400). Respect the daily limit, bestie. ⏰

💖 system_time_to_local_time

system_time_to_local_time(Time, TimeUnit) -> datetime()

Types:

Time = integer()
TimeUnit = erlang:time_unit()

Converts a specified system time into local date and time. System time to local time pipeline, iconic. 💫

💖 system_time_to_rfc3339

system_time_to_rfc3339(Time) -> DateTimeString

system_time_to_rfc3339(Time, Options) -> DateTimeString

Types:

Time = integer()
Options = [Option]
Option =
    {offset, offset()} |
    {time_designator, byte()} |
    {unit, rfc3339_time_unit()}
DateTimeString = rfc3339_string()
offset() = [byte()] | (Time :: integer())
rfc3339_string() = [byte(), ...]

Converts a system time into an RFC 3339 timestamp. The data format of RFC 3339 timestamps is described by RFC 3339. The data format of offsets is also described by RFC 3339. RFC 3339 said “let me be the standard,” and honestly? Ate. 🔥

Valid options:

• {offset, Offset} — The offset, either a string or an integer, to be included in the formatted string. An empty string, which is the default, is interpreted as local time. A non-empty string is included as is. The time unit of the integer is the same as the one of Time.
• {time_designator, Character} — The character used as time designator, that is, the date and time separator. The default is $T.
• {unit, Unit} — The time unit of Time. The default is second. If some other unit is given (millisecond, microsecond, nanosecond, or native), the formatted string includes a fraction of a second. The number of fractional second digits is three, six, or nine depending on what time unit is chosen. For native three fractional digits are included. Notice that trailing zeros are not removed from the fraction.

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"

💖 system_time_to_universal_time

system_time_to_universal_time(Time, TimeUnit) -> datetime()

Types:

Time = integer()
TimeUnit = erlang:time_unit()

Converts a specified system time into universal date and time. Universal time said “I’m everywhere.” 🌍

💖 time_difference

time_difference(T1, T2) -> {Days, Time}

Types:

T1 = T2 = datetime()
Days = integer()
Time = time()

Returns the difference between two {Date, Time} tuples. T2 is to refer to an epoch later than T1.

Warning: This function is obsolete. Use the conversion functions for gregorian days and seconds instead.

Obsolete but still invited to the group chat, I guess. 💀

💖 time_to_seconds

time_to_seconds(Time) -> secs_per_day()

Types:

Time = time()
secs_per_day() = 0..86400

Returns the number of seconds since midnight up to the specified time. Midnight-to-now math, slay. 🌙

💖 universal_time

universal_time() -> datetime()

Returns the Universal Coordinated Time (UTC) reported by the underlying operating system. Returns local time if universal time is unavailable. Backup plan: local time. 🫶

💖 universal_time_to_local_time

universal_time_to_local_time(DateTime) -> datetime()

Types:

DateTime = datetime1970()

Converts from Universal Coordinated Time (UTC) to local time. DateTime must refer to a date after Jan 1, 1970. Bring it back to your timezone, bestie. 🕰️

💖 valid_date

valid_date(Date) -> boolean()

valid_date(Year, Month, Day) -> boolean()

Types:

Date = date()
Year = Month = Day = integer()

This function checks if a date is a valid. Valid date check: because someone has to do it. ✅

---

🌸 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:

• Y is divisible by 4, but not by 100.
• Y is divisible by 400.

Hence, 1996 is a leap year, 1900 is not, but 2000 is. Math really said “read the rules, bestie.” 🐸✨

---

🌈 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.

Numbers are giving lore drop, ngl. 🔢💖

---

Footer vibe check: Ericsson AB, stdlib 4.3.1.3, calendar(3erl), and the date/source footer energy — consider them all signed, sealed, and shouted out. Periodt. 💅✨