calendar(3erl) Erlang Module Definition calendar(3erl)
NAME
calendar - Local and universal time, day of the week, date and time
conversions.
DESCRIPTION
This module provides computation of local and universal time, day of
the week, and many 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. Univer-
sal Coordinated Time (UTC) time 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. 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 re-
liable date/time stamp is required.
All dates conform to the Gregorian calendar. This calendar was intro-
duced by Pope Gregory XIII in 1582 and was used in all Catholic coun-
tries 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 Gre-
gorian 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 includ-
ing the date specified. Similarly, the gregorian seconds for a speci-
fied 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 con-
tains a week of the year implementation conforming to the ISO 8601
standard. As the week number for a specified date can fall on the pre-
vious, 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()}
datetime1970() = {{year1970(), month(), day()}, time()}
date() = {year(), month(), day()}
year() = integer() >= 0
Year cannot be abbreviated. For example, 93 denotes year 93, not
1993. The valid range depends on the underlying operating sys-
tem. The date tuple must denote a valid date.
year1970() = 1970..10000
month() = 1..12
day() = 1..31
time() = {hour(), minute(), second()}
hour() = 0..23
minute() = 0..59
second() = 0..59
daynum() = 1..7
ldom() = 28 | 29 | 30 | 31
yearweeknum() = {year(), weeknum()}
weeknum() = 1..53
EXPORTS
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.
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.
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.
gregorian_days_to_date(Days) -> date()
Types:
Days = integer() >= 0
Computes the date from the specified number of gregorian days.
gregorian_seconds_to_datetime(Seconds) -> datetime()
Types:
Seconds = integer() >= 0
Computes the date and time from the specified number of grego-
rian seconds.
is_leap_year(Year) -> boolean()
Types:
Year = year()
Checks if the specified year is a leap year.
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.
last_day_of_the_month(Year, Month) -> LastDay
Types:
Year = year()
Month = month()
LastDay = ldom()
Computes the number of days in a month.
local_time() -> datetime()
Returns the local time reported by the underlying operating sys-
tem.
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_univer-
sal_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.
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 corre-
sponding UTC, as the local time is illegal (it has never oc-
cured).
[DstDateTimeUTC, DateTimeUTC]:
For a local {Date1, Time1} during the period that is re-
peated when switching from daylight saving time, two corre-
sponding UTCs exist; one for the first instance of the pe-
riod 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) -> datetime1970()
Types:
Now = erlang:timestamp()
Returns Universal Coordinated Time (UTC) converted from the re-
turn value from erlang:timestamp/0.
now_to_local_time(Now) -> datetime1970()
Types:
Now = erlang:timestamp()
Returns local date and time converted from the return value from
erlang:timestamp/0.
now_to_universal_time(Now) -> datetime1970()
Types:
Now = erlang:timestamp()
Returns Universal Coordinated Time (UTC) converted from the re-
turn value from erlang:timestamp/0.
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(), ...]
rfc3339_time_unit() =
microsecond | millisecond | nanosecond | second
Converts an RFC 3339 timestamp into system time. The data format
of RFC 3339 timestamps is described by RFC 3339.
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) -> {Days, Time}
Types:
Seconds = Days = integer()
Time = time()
Converts a specified number of seconds into days, hours, min-
utes, and seconds. Time is always non-negative, but Days is neg-
ative if argument Seconds is.
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).
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_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(), ...]
rfc3339_time_unit() =
microsecond | millisecond | nanosecond | second
Converts a system time into an RFC 3339 timestamp. The data for-
mat of RFC 3339 timestamps is described by RFC 3339. The data
format of offsets is also described by RFC 3339.
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, or nanosecond), 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. 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(Time, TimeUnit) -> datetime()
Types:
Time = integer()
TimeUnit = erlang:time_unit()
Converts a specified system time into universal date and time.
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 gre-
gorian days and seconds instead.
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.
universal_time() -> datetime()
Returns the Universal Coordinated Time (UTC) reported by the un-
derlying operating system. Returns local time if universal time
is unavailable.
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.
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.
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 fol-
lowing 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.
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.
Ericsson AB stdlib 3.13 calendar(3erl)