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 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 sepa-
       rate 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  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 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.

DATA TYPES

       date() = {Year, Month, Day}
	 Year = int()
	 Month = 1..12
	 Day = 1..31
       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.

       time() = {Hour, Minute, Second}
	 Hour = 0..23
	 Minute = Second = 0..59

EXPORTS

       date_to_gregorian_days(Date) -> Days
       date_to_gregorian_days(Year, Month, Day) -> Days

	      Types  Date = date()
		     Days = int()

	      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

	      Types  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

	      Types  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

	      Types  Days = int()
		     Date = date()

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

       gregorian_seconds_to_datetime(Seconds) -> {Date, Time}

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

       iso_week_number() -> IsoWeekNumber

	      Types  IsoWeekNumber = {int(), int()}

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

	      Types  Date = date()
		     IsoWeekNumber = {int(), int()}

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

       last_day_of_the_month(Year, Month) -> int()

	      This function computes the number of days in a month.

       local_time() -> {Date, Time}

	      Types  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}]

	      Types  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 corre-
		  sponding 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}

	      Types  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}

	      Types  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}

	      Types  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

	      Types  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

	      Types  Time = time()
		     Seconds = int()

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

       universal_time() -> {Date, Time}

	      Types  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}

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

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

       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.

Ericsson AB							   stdlib 1.17.3						    calendar(3erl)