calendar

Local and universal time, day-of-the-week, date and time conversions

This module provides computation of local and universal time,
day-of-the-week, and several time conversion functions.

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

The time functions local_time/0 and
universal_time/0 provided in this module both return date
and time. The reason for this is that separate functions for date
and time may result in a date/time combination which is displaced
by 24 hours. This happens 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 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 given date and time, is
the 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
given as local time, they must be converted to universal time, in
order to get the correct value of the elapsed time between epochs.
Use of the function time_difference/2 is discouraged.

Functions

date_to_gregorian_days(Date) -> Days

date_to_gregorian_days(Year, Month, Day) -> Days

This function computes the number of gregorian days starting
with year 0 and ending at the given date.

datetime_to_gregorian_seconds({Date, Time}) -> Seconds

Date = date()

Time = time()

Seconds = int()

This function computes the number of gregorian seconds
starting with year 0 and ending at the given date and time.

day_of_the_week(Date) -> DayNumber

day_of_the_week(Year, Month, Day) -> DayNumber

Date = date()

DayNumber = 1..7

This function computes the day of the week given Year,
Month and Day. The return value denotes the day
of the week as 1: Monday, 2: Tuesday, and so on.

gregorian_days_to_date(Days) -> Date

Days = int()

Date = date()

This function computes the date given the number of
gregorian days.

gregorian_seconds_to_datetime(Seconds) -> {Date, Time}

Seconds = int()

Date = date()

Time = time()

This function computes the date and time from the given
number of gregorian seconds.

is_leap_year(Year) -> bool()

This function checks if a year is a leap year.

last_day_of_the_month(Year, Month) -> int()

This function computes the number of days in a month.

local_time() -> {Date, Time}

Date = date()

Time = time()

This function returns the local time reported by
the underlying operating system.

local_time_to_universal_time({Date1, Time1}) -> {Date2, Time2}

This function converts from local time to Universal
Coordinated Time (UTC). Date1 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 since it gets skipped during
the switch to daylight saving time, this function
still returns a result.

local_time_to_universal_time_dst({Date1, Time1}) -> [{Date, Time}]

Date1 = Date = date()

Time1 = Time = time()

This function converts from local time to Universal
Coordinated Time (UTC). Date1 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 since the local time
is illegal - it has never happened.

[DstDateTimeUTC, DateTimeUTC]

For a local {Date1, Time1} during the period that
is repeated when switching from daylight saving
time, there are two corresponding UTCs. 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 there is only one
corresponding UTC.

now_to_local_time(Now) -> {Date, Time}

Now -- see erlang:now/0

Date = date()

Time = time()

This function returns local date and time converted from
the return value from erlang:now().

now_to_universal_time(Now) -> {Date, Time}

now_to_datetime(Now) -> {Date, Time}

Now -- see erlang:now/0

Date = date()

Time = time()

This function returns Universal Coordinated Time (UTC)
converted from the return value from erlang:now().

seconds_to_daystime(Seconds) -> {Days, Time}

Seconds = Days = int()

Time = time()

This function transforms a given number of seconds into days,
hours, minutes, and seconds. The Time part is always
non-negative, but Days is negative if the argument
Seconds is.

seconds_to_time(Seconds) -> Time

Seconds = int() < 86400

Time = time()

This function computes the time from the given number of
seconds. Seconds must be less than the number of
seconds per day (86400).

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

This function returns the difference between two {Date, Time} tuples. T2 should refer to an epoch later
than T1.

Warning!

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

time_to_seconds(Time) -> Seconds

Time = time()

Seconds = int()

This function computes the number of seconds since midnight
up to the specified time.

universal_time() -> {Date, Time}

Date = date()

Time = time()

This function returns the Universal Coordinated Time (UTC)
reported by the underlying operating system. Local time is
returned if universal time is not available.

universal_time_to_local_time({Date1, Time1}) -> {Date2, Time2}

Date1 = Date2 = date()

Time1 = Time2 = time()

This function converts from Universal Coordinated Time (UTC)
to local time. Date1 must refer to a date after Jan 1,
1970.

valid_date(Date) -> bool()

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

Date = date()

This function checks if a date is a valid.

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
either of the following rules is valid:

Y is divisible by 4, but not by 100; or

Y is divisible by 400.

Accordingly, 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.