Time and date

Local time

The calendar module answers dates and times as tuples. local_time gives a pair of date and time tuples for the machine's timezone.

universal_time answers the same in UTC, which is the safer default for servers. Both read the wall clock, so their answer changes every second and the session below checks the shape of a date tuple instead.

erl

1> calendar:valid_date({2026, 10, 10}).
true
2> calendar:valid_date({2026, 2, 30}).
false

System time

The erlang:system_time function answers the system time as a count in a unit you choose: seconds, milliseconds, or nanoseconds.

The calendar converts such a count to a UTC tuple, with time zero at the Unix epoch. Use a count for measuring elapsed time, and the tuple form for calendar work.

erl

1> calendar:system_time_to_universal_time(0, second).
{{1970,1,1},{0,0,0}}
2> calendar:system_time_to_universal_time(1000000000, second).
{{2001,9,9},{1,46,40}}

Format and parse

The calendar module converts between dates and day counts, which is the cheapest way to compare dates in plain Erlang. A day count is the number of days since the Gregorian epoch.

For pretty output, print the tuple with tilde p and let the reader see the whole date.

erl

1> calendar:date_to_gregorian_days({2026, 10, 10}).
740264
2> calendar:gregorian_days_to_date(740264).
{2026,10,10}

Date arithmetic

Convert two dates to day counts, subtract, and you have the days between them. The last_day_of_the_month function answers month lengths, and day_of_the_week numbers the days from Monday as 1.

The calendar module also knows leap years, which the day arithmetic handles for free. This module wraps all three questions; save it as dates.erl.

-module(dates). -export([between/2, month_length/2, weekday/1]). between(From, To) -> calendar:date_to_gregorian_days(To) - calendar:date_to_gregorian_days(From). month_length(Year, Month) -> calendar:last_day_of_the_month(Year, Month). weekday(Date) -> calendar:day_of_the_week(Date).

erlc dates.erl
erl

1> dates:between({2026, 10, 10}, {2026, 12, 25}).
76
2> dates:month_length(2026, 2).
28
3> dates:month_length(2024, 2).
29
4> calendar:is_leap_year(2026).
false
5> dates:weekday({2026, 10, 10}).
6

The last answer is 6, a Saturday: day_of_the_week counts from Monday as 1 and Sunday as 7.

Next: JSON and term formats

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. How does calendar represent a date?

    Answer

    {Year, Month, Day}

    A date is {Year, Month, Day} and a time is {Hour, Minute, Second}, in that order.

  2. What does calendar:valid_date({2026, 2, 30}) answer?

    Answer

    false

    February 2026 has 28 days, so the 30th is not a valid date.

  3. Which call answers the current time as a count of seconds?

    Answer

    erlang:system_time(second)

    erlang:system_time/1 takes a unit and answers the system time in it.

  4. What does calendar:system_time_to_universal_time(0, second) answer?

    Answer

    {{1970,1,1},{0,0,0}}

    Time zero is the Unix epoch, 1 January 1970 at midnight UTC.

  5. Why does the lesson avoid printing calendar:local_time()?

    Answer

    It changes every second and depends on the timezone

    A wall-clock answer cannot be replayed, so the examples use fixed dates and counts instead.

  6. What does calendar:date_to_gregorian_days({2026, 10, 10}) answer?

    Answer

    A day count

    It answers the number of days since the Gregorian epoch: 740264 for this date.

  7. How do you get the days between two dates?

    Answer

    Subtract their day counts

    date_to_gregorian_days/1 on both, then subtract: 76 days here.

  8. How many days does February 2024 have?

    Answer

    29

    2024 is a leap year, so last_day_of_the_month(2024, 2) answers 29.

  9. What number does calendar:day_of_the_week/1 give Saturday?

    Answer

    6

    The count starts at Monday as 1, so Saturday is 6 and Sunday is 7.

  10. Why does date arithmetic handle leap years for free?

    Answer

    The day count already includes every day

    Day counts are a plain running total, so subtracting them counts the extra day of a leap year automatically.

The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image