Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all 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 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.

There exists different definitions for the week of the year. The calendar module  contains
a  week of the year implementation which conforms to the ISO 8601 standard. Since the week
number for a given date can fall on the previous, the current or on the next  year  it  is
important  to  provide the information which year is it together with the week number. The
function iso_week_number/0 and iso_week_number/1 returns a tuple of the year and the  week
number.

```

DATATYPES

```       datetime() = {date(), time()}

datetime1970() = {{year1970(), month(), day()}, time()}

date() = {year(), month(), day()}

year() = integer() >= 0

Year  cannot  be  abbreviated.  Example:  93 denotes year 93, not 1993. Valid range
depends on the underlying OS. 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()

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

datetime_to_gregorian_seconds(DateTime) -> Seconds

Types:

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

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) -> daynum()

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

Types:

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

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

Types:

Days = integer() >= 0

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

gregorian_seconds_to_datetime(Seconds) -> datetime()

Types:

Seconds = integer() >= 0

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

is_leap_year(Year) -> boolean()

Types:

Year = year()

This function checks if a year is a leap year.

iso_week_number() -> yearweeknum()

This function returns the tuple {Year, WeekNum} representing the  iso  week  number
for  the actual date. For determining the actual date, the function local_time/0 is
used.

iso_week_number(Date) -> yearweeknum()

Types:

Date = date()

This function returns the tuple {Year, WeekNum} representing the  iso  week  number
for the given date.

last_day_of_the_month(Year, Month) -> LastDay

Types:

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

This function computes the number of days in a month.

local_time() -> datetime()

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

local_time_to_universal_time(DateTime1) -> DateTime2

Types:

DateTime1 = DateTime2 = datetime1970()

This  function  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 since it gets 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()

This  function  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 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) -> datetime1970()

Types:

Now = erlang:timestamp()

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

now_to_universal_time(Now) -> datetime1970()

now_to_datetime(Now) -> datetime1970()

Types:

Now = erlang:timestamp()

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

seconds_to_daystime(Seconds) -> {Days, Time}

Types:

Seconds = Days = integer()
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()

Types:

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

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}

Types:

T1 = T2 = datetime()
Days = integer()
Time = 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

time_to_seconds(Time) -> secs_per_day()

Types:

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

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

universal_time() -> datetime()

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(DateTime) -> datetime()

Types:

DateTime = datetime1970()

This  function  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.

```

LEAPYEARS

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

```

DATEANDTIMESOURCE

```       Local  time  is  obtained from the Erlang BIF localtime/0. Universal time is computed from
the BIF universaltime/0.

The following facts 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.
```