<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
 <reference id="ref.calendar">
  <title>Calendar functions</title>
  <titleabbrev>Calendar</titleabbrev>
  <partintro>
   <section>
    <title>Introduction</title>
    <para>
     The calendar extension presents a series of functions to simplify
     converting between different calendar formats.  The intermediary
     or standard it is based on is the Julian Day Count.  The Julian
     Day Count is a count of days starting way earlier than any date
     most people would need to track (somewhere around 4000bc).  To
     convert between calendar systems, you must first convert to Julian
     Day Count, then to the calendar system of your choice.  Julian Day
     Count is very different from the Julian Calendar!  For more
     information on calendar systems visit <ulink
     url="&url.calendar;">&url.calendar;</ulink>.  Excerpts from this
     page are included in these instructions, and are in quotes.
    </para>
   </section>
   <section>
    <title>Installation</title>
    <para>
     To get these functions to work, you have to compile PHP with
     <option role="configure">--enable-calendar</option>.
    </para>
   </section>
  </partintro>

  <refentry id="function.jdtogregorian">
   <refnamediv>
    <refname>JDToGregorian</refname>
    <refpurpose>Converts Julian Day Count to Gregorian date</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>jdtogregorian</methodname>
      <methodparam><type>int</type><parameter>julianday</parameter></methodparam>
     </methodsynopsis>
    <para>
     Converts Julian Day Count to a string containing the Gregorian
     date in the format of "month/day/year".
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.gregoriantojd">
   <refnamediv>
    <refname>GregorianToJD</refname> 
    <refpurpose>
     Converts a Gregorian date to Julian Day Count
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>gregoriantojd</methodname>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Valid Range for Gregorian Calendar 4714 B.C. to 9999 A.D.</para>
    <para>
     Although this function can handle dates all the way back to 4714
     B.C., such use may not be meaningful. The Gregorian calendar was
     not instituted until October 15, 1582 (or October 5, 1582 in the
     Julian calendar). Some countries did not accept it until much
     later. For example, Britain converted in 1752, The USSR in 1918
     and Greece in 1923. Most European countries used the Julian
     calendar prior to the Gregorian.
     <example>
      <title>Calendar functions</title>
      <programlisting role="php">
<![CDATA[
<?php
$jd = GregorianToJD (10,11,1970);
echo "$jd\n";
$gregorian = JDToGregorian ($jd);
echo "$gregorian\n";
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.jdtojulian">
   <refnamediv>
    <refname>JDToJulian</refname> 
    <refpurpose>
     Converts a Julian Day Count to a Julian Calendar Date
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>jdtojulian</methodname>
      <methodparam><type>int</type><parameter>julianday</parameter></methodparam>
     </methodsynopsis>
    <para>
     Converts Julian Day Count to a string containing the Julian
     Calendar Date in the format of "month/day/year".
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.juliantojd">
   <refnamediv>
    <refname>JulianToJD</refname> 
    <refpurpose>
     Converts a Julian Calendar date to Julian Day Count
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>juliantojd</methodname>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Valid Range for Julian Calendar 4713 B.C. to 9999 A.D.
    </para>
    <para>
     Although this function can handle dates all the way back to 4713
     B.C., such use may not be meaningful. The calendar was created in
     46 B.C., but the details did not stabilize until at least 8 A.D.,
     and perhaps as late at the 4th century. Also, the beginning of a
     year varied from one culture to another - not all accepted
     January as the first month.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.jdtojewish">
   <refnamediv>
    <refname>JDToJewish</refname>
    <refpurpose>
     Converts a Julian Day Count to the Jewish Calendar
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>jdtojewish</methodname>
      <methodparam><type>int</type><parameter>julianday</parameter></methodparam>
     </methodsynopsis>
    <para>
     Converts a Julian Day Count the the Jewish Calendar.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.jewishtojd">
   <refnamediv>
    <refname>JewishToJD</refname> 
    <refpurpose>
     Converts a date in the Jewish Calendar to Julian Day Count
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>jewishtojd</methodname>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Although this function can handle dates all the way back to the year 1
     (3761 B.C.), such use may not be meaningful.  The Jewish calendar has
     been in use for several thousand years, but in the early days there was
     no formula to determine the start of a month. A new month was started
     when the new moon was first observed.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.jdtofrench">
   <refnamediv>
    <refname>JDToFrench</refname>
    <refpurpose>
     Converts a Julian Day Count to the French Republican Calendar
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>jdtofrench</methodname>
      <methodparam><type>int</type><parameter>juliandaycount</parameter></methodparam>
     </methodsynopsis>
    <para>
     Converts a Julian Day Count to the French Republican Calendar.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.frenchtojd">
   <refnamediv>
    <refname>FrenchToJD</refname>
    <refpurpose>
     Converts a date from the French Republican Calendar to a Julian
     Day Count
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>frenchtojd</methodname>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Converts a date from the French Republican Calendar to a Julian
     Day Count.
    </para>
    <para>
     These routines only convert dates in years 1 through 14
     (Gregorian dates 22 September 1792 through 22 September
     1806). This more than covers the period when the calendar was in
     use.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.jdmonthname">
   <refnamediv>
    <refname>JDMonthName</refname>
    <refpurpose>Returns a month name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>jdmonthname</methodname>
      <methodparam><type>int</type><parameter>julianday</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a string containing a month name.
     <parameter>mode</parameter> tells this function which calendar to
     convert the Julian Day Count to, and what type of month names are
     to be returned.
     <table>
      <title>Calendar modes</title>
      <tgroup cols="3">
       <thead>
        <row>
         <entry>Mode</entry>
         <entry>Meaning</entry>
         <entry>Values</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>0</entry>
         <entry>Gregorian - abbreviated</entry>
         <entry>Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</entry>
        </row>
        <row>
         <entry>1</entry>
         <entry>Gregorian</entry>
         <entry>January, February, March, April, May, June, July, August, September, October, November, December</entry>
        </row>
        <row>
         <entry>2</entry>
         <entry>Julian - abbreviated</entry>
         <entry>Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec</entry>
        </row>
        <row>
         <entry>3</entry>
         <entry>Julian</entry>
         <entry>January, February, March, April, May, June, July, August, September, October, November, December</entry>
        </row>
        <row>
         <entry>4</entry>
         <entry>Jewish</entry>
         <entry>Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul</entry>
        </row>
        <row>
         <entry>5</entry>
         <entry>French Republican</entry>
         <entry>Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.jddayofweek">
   <refnamediv>
    <refname>JDDayOfWeek</refname>
    <refpurpose>Returns the day of the week</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>jddayofweek</methodname>
      <methodparam><type>int</type><parameter>julianday</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the day of the week.  Can return a string or an integer
     depending on the mode.
     <table>
      <title>Calendar week modes</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Mode</entry>
         <entry>Meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>0</entry> 
         <entry>
          Returns the day number as an int (0=sunday, 1=monday, etc)
         </entry>
        </row>
        <row>
         <entry>1</entry> 
         <entry>
          Returns string containing the day of week
          (english-gregorian)
         </entry>
        </row>
        <row>
         <entry>2</entry> 
         <entry>
          Returns a string containing the abbreviated day of week
          (english-gregorian)
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.easter-date">
   <refnamediv>
    <refname>easter_date</refname>
    <refpurpose>
     Get UNIX timestamp for midnight on Easter of a given year
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>easter_date</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the UNIX timestamp corresponding to midnight on Easter of
     the given year.  If no year is specified, the current year is
     assumed.
    </para>
    <para>
     <emphasis>Warning:</emphasis> This function will generate
     a warning if the year is outside of the range for UNIX
     timestamps (i.e. before 1970 or after 2037).
     <example>
      <title><function>easter_date</function> example</title>
      <programlisting role="php">
<![CDATA[
echo date ("M-d-Y", easter_date(1999));        /* "Apr-04-1999" */
echo date ("M-d-Y", easter_date(2000));        /* "Apr-23-2000" */
echo date ("M-d-Y", easter_date(2001));        /* "Apr-15-2001" */
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The date of Easter Day was defined by the Council of Nicaea in
     AD325 as the Sunday after the first full moon which falls on or
     after the Spring Equinox.  The Equinox is assumed to always fall
     on 21st March, so the calculation reduces to determining the date
     of the full moon and the date of the following Sunday.  The
     algorithm used here was introduced around the year 532 by
     Dionysius Exiguus.  Under the Julian Calendar (for years before
     1753) a simple 19-year cycle is used to track the phases of the
     Moon.  Under the Gregorian Calendar (for years after 1753 -
     devised by Clavius and Lilius, and introduced by Pope Gregory
     XIII in October 1582, and into Britain and its then colonies in
     September 1752) two correction factors are added to make the
     cycle more accurate.
    </para>
    <para>
     (The code is based on a C program by Simon Kershaw,
     &lt;webmaster@ely.anglican.org&gt;)
    </para>
    <para>
     See <function>easter_days</function> for calculating Easter
     before 1970 or after 2037.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.easter-days">
   <refnamediv>
    <refname>easter_days</refname>
    <refpurpose>
     Get number of days after March 21 on which Easter falls for a
     given year
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>easter_days</methodname>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the number of days after March 21 on which Easter falls
     for a given year.  If no year is specified, the current year is
     assumed.
    </para>
    <para>
     This function can be used instead of
     <function>easter_date</function> to calculate Easter for years
     which fall outside the range of UNIX timestamps (i.e. before 1970
     or after 2037).
     <example>
      <title><function>easter_days</function> example</title>
      <programlisting role="php">
<![CDATA[
echo easter_days (1999);        /* 14, i.e. April 4   */
echo easter_days (1492);        /* 32, i.e. April 22  */
echo easter_days (1913);        /*  2, i.e. March 23  */
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The date of Easter Day was defined by the Council of Nicaea in
     AD325 as the Sunday after the first full moon which falls on or
     after the Spring Equinox.  The Equinox is assumed to always fall
     on 21st March, so the calculation reduces to determining the date
     of the full moon and the date of the following Sunday.  The
     algorithm used here was introduced around the year 532 by
     Dionysius Exiguus.  Under the Julian Calendar (for years before
     1753) a simple 19-year cycle is used to track the phases of the
     Moon.  Under the Gregorian Calendar (for years after 1753 -
     devised by Clavius and Lilius, and introduced by Pope Gregory
     XIII in October 1582, and into Britain and its then colonies in
     September 1752) two correction factors are added to make the
     cycle more accurate.
    </para>
    <para>
     (The code is based on a C program by Simon Kershaw,
     &lt;webmaster@ely.anglican.org&gt;)
    </para>
    <para>
     See also <function>easter_date</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.unixtojd">
   <refnamediv>
    <refname>unixtojd</refname>
    <refpurpose>Convert UNIX timestamp to Julian Day</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>unixtojd</methodname>
      <methodparam choice="opt"><type>int</type><parameter>timestamp</parameter></methodparam>
     </methodsynopsis>
    <para>
     Return the Julian Day for a UNIX <parameter>timestamp</parameter>
     (seconds since 1.1.1970), or for the current day if no
     <parameter>timestamp</parameter> is given.
    </para>
    <para>
     See also <function>jdtounix</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.jdtounix"> 
   <refnamediv>
    <refname>jdtounix</refname>
    <refpurpose>Convert Julian Day to UNIX timestamp</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>jdtounix</methodname>
      <methodparam><type>int</type><parameter>jday</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function will return a UNIX timestamp corresponding to the
     Julian Day given in <parameter>jday</parameter> or &false; if
     <parameter>jday</parameter> is not inside the UNIX epoch
     (Gregorian years between 1970 and 2037 or 2440588 &lt;=
     <parameter>jday</parameter> &lt;= 2465342 )
    </para>
    <para>
     See also <function>unixtojd</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.cal-days-in-month"> 
   <refnamediv>
    <refname>cal_days_in_month</refname>
    <refpurpose>Return the number of days in a month for a given year and calendar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>cal_days_in_month</methodname>
      <methodparam><type>int</type><parameter>calendar</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function will return the number of days in the
     <parameter>month</parameter> of <parameter>year</parameter> for
     the specified <parameter>calendar</parameter>.
    </para>
    <para>
     See also <function>jdtounix</function>.
    </para>
   </refsect1>
  </refentry>
  

  <refentry id='function.cal-to-jd'>
   <refnamediv>
    <refname>cal_to_jd</refname>
    <refpurpose>Converts from a supported calendar to Julian Day Count</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>cal_to_jd</methodname>
      <methodparam><type>int</type><parameter>calendar</parameter></methodparam>
      <methodparam><type>int</type><parameter>month</parameter></methodparam>
      <methodparam><type>int</type><parameter>day</parameter></methodparam>
      <methodparam><type>int</type><parameter>year</parameter></methodparam>
     </methodsynopsis>
    <para>
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.cal-from-jd'>
   <refnamediv>
    <refname>cal_from_jd</refname>
    <refpurpose>Converts from Julian Day Count to a supported calendar and return extended information</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>cal_from_jd</methodname>
      <methodparam><type>int</type><parameter>jd</parameter></methodparam>
      <methodparam><type>int</type><parameter>calendar</parameter></methodparam>
     </methodsynopsis>
    <para>
    </para>
   </refsect1>
  </refentry>


  <refentry id='function.cal-info'>
   <refnamediv>
    <refname>cal_info</refname>
    <refpurpose>Returns information about a particular calendar</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>cal_info</methodname>
      <methodparam><type>int</type><parameter>calendar</parameter></methodparam>
     </methodsynopsis>
    <para>
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->