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.
date_to_gregorian_days(Year, Month, Day) -> Days
date_to_gregorian_days(Date) -> Days
Date = {Year, Month, Day}
Year = Month = Day = Days = int()
This function computes the number of gregorian days starting with year 0 and ending at the given date.
datetime_to_gregorian_seconds(DateTime) -> Days
DateTime = {date(), time()}
date() = {Year, Month, Day}
time() = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = Days = 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 = {Year, Month, Day}
Year = Month = Day = DayNumber = int()
This function computes the day of the week given
Year
, Month
and Day
. The return value denotes the day of the week as
follows:
Monday = 1, Tuesday = 2, ..., Sunday = 7
Year
cannot be abbreviated and a value of 93 denotes
the year 93, and not the year 1993. Month
is the month
number with January = 1. Day
is an integer in the range
1 and the number of days in the month Month
of the
year Year
.
gregorian_days_to_date(Days) -> Date
Date = {Year, Month, Day}
Year = Month = Day = Days = int()
This function computes the date given the number of gregorian days.
gregorian_seconds_to_datetime(Secs) -> DateTime
DateTime = {date(), time()}
date() = {Year, Month, Day}
time() = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = Days = int()
This function computes the date and time from the given number of gregorian seconds.
Year = int()
This function checks if a year is a leap year.
last_day_of_the_month(Year, Month) -> int()
Year = Month = int()
This function computes the number of days in a month.
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
This function returns the local time reported by the underlying operating system.
local_time_to_universal_time({Date, Time}) -> {Date, Time}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
This function converts from local time to Universal
Coordinated Time (UTC). Date
must refer to a local date
after Jan 1, 1970.
now_to_local_time(Now) -> {Date, Time}
Now = {MegaSecs, Secs, MicroSecs}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
MegaSecs = Secs = MilliSecs = int()
Year = Month = Day = Hour = Minute = Second = int()
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 = {MegaSecs, Secs, MicroSecs}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
MegaSecs = Secs = MilliSecs = int()
Year = Month = Day = Hour = Minute = Second = int()
This function returns Universal Coordinated Time (UTC)
converted from the return value from erlang:now()
.
seconds_to_daystime(Secs) -> {Days, Time}
Time() = {Hour, Minute, Second}
Hour = Minute = Second = Days = int()
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 Secs
is.
Time() = {Hour, Minute, Second}
Hour = Minute = Second = Secs = int()
This function computes the time from the given number of
seconds. Secs
must be less than the number of seconds
per day.
time_difference(T1, T2) -> Tdiff
T1 = T2 = {Date, Time}
Tdiff = {Day, {Hour, Minute, Second}}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
This function returns the difference between two {Date,
Time}
structures. T2
should refer to an epoch later
than T1
.
This function is obsolete. Use the conversion functions for gregorian days and seconds instead.
Time() = {Hour, Minute, Second}
Hour = Minute = Second = Secs = int()
This function computes the number of seconds since midnight up to the specified time.
universal_time() -> {Date, Time}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
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({Date, Time}) -> {Date, Time}
Date = {Year, Month, Day}
Time = {Hour, Minute, Second}
Year = Month = Day = Hour = Minute = Second = int()
This function converts from Universal Coordinated Time (UTC)
to local time. Date
must refer to a date after Jan 1,
1970.
valid_date(Date) -> bool()
valid_date(Year, Month, Day) -> bool()
Date = {Year, Month, Day}
Year = Month = Day = int()
This function checks if a date is a valid.
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:
Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.
Local time is obtained from the Erlang BIF localtime/0
.
Universal time is computed from the BIF universaltime/0
.
The following facts apply: