Provided by: erlang-manpages_25.2.3+dfsg-1_all bug

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. Universal 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 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 specified 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 contains a week  of  the
       year  implementation  conforming  to  the  ISO  8601  standard.  As  the week number for a
       specified date can fall on the previous, 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 system. 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

       rfc3339_time_unit() =
           microsecond | millisecond | nanosecond | second | native

          Note:
              The native time unit was added to rfc3339_time_unit() in OTP 25.0.

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 gregorian 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 system.

       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_universal_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  corresponding UTC, as the local time is
                  illegal (it has never occured).

                [DstDateTimeUTC, DateTimeUTC]:
                  For a local {Date1, Time1} during the period that is  repeated  when  switching
                  from  daylight  saving  time,  two  corresponding UTCs exist; 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 only one corresponding UTC exists.

       now_to_datetime(Now) -> datetime1970()

              Types:

                 Now = erlang:timestamp()

              Returns  Universal  Coordinated  Time  (UTC)  converted  from the return 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 return 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(), ...]

              Converts an RFC 3339 timestamp into system  time.  The  data  format  of  RFC  3339
              timestamps  is  described  by RFC 3339. Starting from OTP 25.1, the minutes part of
              the time zone is optional.

              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, minutes, and seconds. Time
              is always non-negative, but Days is negative 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(), ...]

              Converts a system time into an RFC 3339 timestamp. The  data  format  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,  nanosecond,  or  native),  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. For native three
                  fractional digits are included. 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  gregorian  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 underlying 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 following 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.