File: calendar.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (615 lines) | stat: -rw-r--r-- 16,816 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>calendar</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>calendar</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
calendar
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Local and universal time, day-of-the-week, date and time
conversions
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>This module provides computation of local and universal time,
day-of-the-week, and several time conversion functions.


<P>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).


<P>The time functions <CODE>local_time/0</CODE> and <CODE>universal_time/0</CODE>
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
<CODE>date/0</CODE> and <CODE>time/0</CODE>, and their use is strongly
discouraged if a reliable date/time stamp is required.


<P>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).
<P>The Gregorian calendar in this module is extended back to year 0.
For a given date, the <STRONG>gregorian days</STRONG> is the number of days
up to and including the date specified. Similarly, the <STRONG>gregorian
seconds</STRONG> for a given date and time, is the the number of seconds
up to and including the specified date and time.


<P>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 
<CODE>time_difference/2</CODE> is discouraged.


</DIV>

<H3>EXPORTS</H3>

<P><A NAME="date_to_gregorian_days/3"><STRONG><CODE>date_to_gregorian_days(Year, Month, Day) -&#62; Days</CODE></STRONG></A><BR>
<A NAME="date_to_gregorian_days/1"><STRONG><CODE>date_to_gregorian_days(Date) -&#62; Days</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Days = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="datetime_to_gregorian_seconds/1"><STRONG><CODE>datetime_to_gregorian_seconds(DateTime) -&#62; Seconds</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>DateTime = {date(), time()}</CODE></STRONG><BR>
<STRONG><CODE>date() = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = Seconds = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the number of gregorian seconds starting
        with year 0 and ending at the given date and time.

</DIV>

<P><A NAME="day_of_the_week/1"><STRONG><CODE>day_of_the_week(Date) -&#62; DayNumber</CODE></STRONG></A><BR>
<A NAME="day_of_the_week/3"><STRONG><CODE>day_of_the_week(Year, Month, Day) -&#62; DayNumber</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = DayNumber = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the day of the week given
        <CODE>Year</CODE>, <CODE>Month</CODE>
and <CODE>Day</CODE>. The return value denotes the day of the week as
follows: 
<PRE>
Monday = 1, Tuesday = 2, ..., Sunday = 7
</PRE>

<P><CODE>Year</CODE> cannot be abbreviated and a value of 93 denotes
         the year 93, and not the year 1993. <CODE>Month</CODE> is the month
         number with January = 1. <CODE>Day</CODE> is an integer in the range
1 and the number of days in the month <CODE>Month</CODE> of the
year <CODE>Year</CODE>.


</DIV>

<P><A NAME="gregorian_days_to_date/1"><STRONG><CODE>gregorian_days_to_date(Days) -&#62; Date</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Days = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the date given the number of gregorian
        days.

</DIV>

<P><A NAME="gregorian_seconds_to_datetime/1"><STRONG><CODE>gregorian_seconds_to_datetime(Secs) -&#62; DateTime</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>DateTime = {date(), time()}</CODE></STRONG><BR>
<STRONG><CODE>date() = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = Days = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="is_leap_year/1"><STRONG><CODE>is_leap_year(Year) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Year = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function checks if a year is a leap year.

</DIV>

<P><A NAME="last_day_of_the_month/2"><STRONG><CODE>last_day_of_the_month(Year, Month) -&#62; int()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Year = Month = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the number of days in a month.

</DIV>

<P><A NAME="local_time/0"><STRONG><CODE>local_time() -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

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

</DIV>

<P><A NAME="local_time_to_universal_time/2"><STRONG><CODE>local_time_to_universal_time({Date, Time}) -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function converts from local time to Universal 
         Coordinated Time (UTC). <CODE>Date</CODE> must refer to a local date 
         after Jan 1, 1970.
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Warning!" SRC="warning.gif"></TD>
    <TD>

<P>This function is deprecated. Use 
         <CODE>local_time_to_universal_time_dst/1</CODE> 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 <STRONG>to</STRONG> daylight saving time, this
         function still returns a result.    </TD>
  </TR>
</TABLE>

</DIV>

<P><A NAME="local_time_to_universal_time_dst/1"><STRONG><CODE>local_time_to_universal_time_dst(DateTime) -&#62; [DateTimeUTC]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>DateTime = DateTimeUTC{Date, Time}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function converts from local time to Universal 
         Coordinated Time (UTC). <CODE>Date</CODE> must refer to a local date 
         after Jan 1, 1970.
<P>The return value is a list of 0, 1 or 2 possible UTC times:
        
<P>
<DL>

<DT>
<CODE>[]</CODE>
</DT>

<DD>
For a local <CODE>DateTime</CODE> during the period that
         is skipped when switching <STRONG>to</STRONG> daylight saving
         time, there is no corresponding UTC since the local time
         is illegal - it has never happened.<BR>

</DD>

<DT>
<CODE>[DstDateTimeUTC,DateTimeUTC]</CODE>
</DT>

<DD>
For a local <CODE>DateTime</CODE> during the period that
         is repeated when switching <STRONG>from</STRONG> 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.<BR>

</DD>

<DT>
<CODE>[DateTimeUTC]</CODE>
</DT>

<DD>
For all other local times there is only one
         corresponding UTC.<BR>

</DD>

</DL>

</DIV>

<P><A NAME="now_to_local_time/1"><STRONG><CODE>now_to_local_time(Now) -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Now = {MegaSecs, Secs, MicroSecs}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>MegaSecs = Secs = MilliSecs = int()</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function returns local date and time 
        converted from the return value from <CODE>erlang:now()</CODE>.

</DIV>

<P><A NAME="now_to_universal_time/1"><STRONG><CODE>now_to_universal_time(Now) -&#62; {Date, Time}</CODE></STRONG></A><BR>
<A NAME="now_to_datetime/1"><STRONG><CODE>now_to_datetime(Now) -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Now = {MegaSecs, Secs, MicroSecs}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>MegaSecs = Secs = MilliSecs = int()</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function returns Universal Coordinated Time (UTC)
        converted from the return value from <CODE>erlang:now()</CODE>.

</DIV>

<P><A NAME="seconds_to_daystime/1"><STRONG><CODE>seconds_to_daystime(Secs) -&#62; {Days, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Days = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function transforms a given number of seconds into
        days, hours, minutes, and seconds. The <CODE>Time</CODE> part 
        is always non-negative, but <CODE>Days</CODE> is negative
        if the argument <CODE>Secs</CODE> is. 

</DIV>

<P><A NAME="seconds_to_time/1"><STRONG><CODE>seconds_to_time(Secs) -&#62; Time</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Secs = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the time from the given number of
        seconds. <CODE>Secs</CODE> must be less than the number of seconds
        per day.

</DIV>

<P><A NAME="time_difference/2"><STRONG><CODE>time_difference(T1, T2) -&#62; Tdiff</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>T1 = T2 = {Date, Time}</CODE></STRONG><BR>
<STRONG><CODE>Tdiff = {Day, {Hour, Minute, Second}}</CODE></STRONG><BR>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function returns the difference between two <CODE>{Date,
        Time}</CODE> structures. <CODE>T2</CODE> should refer to an epoch later
        than <CODE>T1</CODE>.

        
<P>This function is obsolete. Use the conversion functions for
        gregorian days and seconds instead.
</DIV>

<P><A NAME="time_to_seconds/1"><STRONG><CODE>time_to_seconds(Time) -&#62; Secs</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Time() = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Hour = Minute = Second = Secs = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function computes the number of seconds since midnight
        up to the specified time. 
</DIV>

<P><A NAME="universal_time/0"><STRONG><CODE>universal_time() -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function returns the Universal Coordinated Time (UTC)
        reported by the underlying operating system. Local time is
        returned if universal time is not available.

</DIV>

<P><A NAME="universal_time_to_local_time/2"><STRONG><CODE>universal_time_to_local_time({Date, Time}) -&#62; {Date, Time}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Time = {Hour, Minute, Second}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = Hour = Minute = Second = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function converts from Universal Coordinated Time (UTC)
        to local time. <CODE>Date</CODE> must refer to a date after Jan 1, 
        1970.
</DIV>

<P><A NAME="valid_date/1"><STRONG><CODE>valid_date(Date) -&#62; bool()</CODE></STRONG></A><BR>
<A NAME="valid_date/3"><STRONG><CODE>valid_date(Year, Month, Day) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Date = {Year, Month, Day}</CODE></STRONG><BR>
<STRONG><CODE>Year = Month = Day = int()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function checks if a date is a valid.

</DIV>

<H3>Leap Years</H3>
<DIV CLASS=REFBODY>

<P>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:


<P>
<UL>

<LI>
Y is divisible by 4, but not by 100; or
<BR>

</LI>


<LI>
Y is divisible by 400.
<BR>

</LI>


</UL>

<P>Accordingly, 1996 is a leap year, 1900 is not, but 2000 is.


</DIV>

<H3>Date and Time Source</H3>
<DIV CLASS=REFBODY>

<P>Local time is obtained from the Erlang BIF <CODE>localtime/0</CODE>.
Universal time is computed from the BIF <CODE>universaltime/0</CODE>.


<P>The following facts apply:
<P>
<UL>

<LI>
there are 86400 seconds in a day
</LI>


<LI>
there are 365 days in an ordinary year
</LI>


<LI>
there are 366 days in a leap year
</LI>


<LI>
there are 1461 days in a 4 year period
</LI>


<LI>
there are 36524 days in a 100 year period
</LI>


<LI>
there are 146097 days in a 400 year period
</LI>


<LI>
there are 719528 days between Jan 1, 0 and Jan 1, 1970.
</LI>


</UL>

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Peter Hgfeldt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.13.2<BR>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>