php-doc-en/functions/calendar.xml
Hartmut Holzgraefe 7839d91186 added DO NOT EDIT noctice to old english functions files,
removing the others


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
2002-04-17 19:58:46 +00:00

636 lines
21 KiB
XML

<!-- D O N O T E D I T T H I S F I L E ! ! !
it is still here for historical reasons only
(as translators may need to check old revision diffs)
if you want to change things documented in this file
you should now edit the files found under en/reference
instead -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.26 $ -->
<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 id="calendar.installation">
<title>Installation</title>
<para>
To get these functions to work, you have to compile PHP with
<option role="configure">--enable-calendar</option>.
</para>
</section>
<section id="calendar.configuration">
<title>Runtime Configuration</title>
&no.config;
</section>
<section id="calendar.resources">
<title>Resource types</title>
&no.resource;
</section>
<section id="calendar.constants">
<title>Predefined constants</title>
&no.constants;
</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
-->