php-doc-en/functions/datetime.sgml
James Gingerich 0fe79018d0 sync with the php3/doc stuff. grr.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@9729 c90b9560-bf6c-de11-be94-00142212c4b1
1999-06-15 20:59:47 +00:00

521 lines
21 KiB
Text

<reference id="ref.datetime">
<title>Date/Time Functions</title>
<titleabbrev>Date/time</titleabbrev>
<refentry id="function.checkdate">
<refnamediv>
<refname>checkdate</refname>
<refpurpose>validate a date/time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>checkdate</function></funcdef>
<paramdef>int <parameter>month</parameter></paramdef>
<paramdef>int <parameter>day</parameter></paramdef>
<paramdef>int <parameter>year</parameter></paramdef>
</funcsynopsis>
<para>
Returns true if the date given is valid; otherwise returns false.
Checks the validity of the date formed by the arguments. A date is
considered valid if:
<itemizedlist>
<listitem><simpara>
year is between 0 and 32767 inclusive
</simpara></listitem>
<listitem><simpara>
month is between 1 and 12 inclusive
</simpara></listitem>
<listitem><simpara>
day is within the allowed number of days for the given month.
Leap years are taken into consideration.
</simpara></listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.date">
<refnamediv>
<refname>date</refname>
<refpurpose>format a local time/date</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>date</function></funcdef>
<paramdef>string <parameter>format</parameter></paramdef>
<paramdef>int <parameter>timestamp</parameter></paramdef>
</funcsynopsis>
<para>
Returns a string formatted according to the given format string
using the given <parameter>timestamp</parameter> or the current
local time if no timestamp is given.
<para>
The following characters are recognized in the format string:
<itemizedlist>
<listitem><simpara>a - "am" or "pm"</simpara></listitem>
<listitem><simpara>A - "AM" or "PM"</simpara></listitem>
<listitem><simpara>d - day of the month, 2 digits with leading zeros; i.e. "01" to "31"</simpara></listitem>
<listitem><simpara>D - day of the week, textual, 3 letters; i.e. "Fri"</simpara></listitem>
<listitem><simpara>F - month, textual, long; i.e. "January"</simpara></listitem>
<listitem><simpara>h - hour, 12-hour format; i.e. "01" to "12"</simpara></listitem>
<listitem><simpara>H - hour, 24-hour format; i.e. "00" to "23"</simpara></listitem>
<listitem><simpara>g - hour, 12-hour format without leading zeros; i.e. "1" to "12"</simpara></listitem>
<listitem><simpara>G - hour, 24-hour format without leading zeros; i.e. "0" to "23"</simpara></listitem>
<listitem><simpara>i - minutes; i.e. "00" to "59"</simpara></listitem>
<listitem><simpara>j - day of the month without leading zeros; i.e. "1" to "31"</simpara></listitem>
<listitem><simpara>l (lowercase 'L') - day of the week, textual, long; i.e. "Friday"</simpara></listitem>
<listitem><simpara>L - boolean for whether it is a leap year; i.e. "0" or "1"</simpara></listitem>
<listitem><simpara>m - month; i.e. "01" to "12"</simpara></listitem>
<listitem><simpara>n - month without leading zeros; i.e. "1" to "12"</simpara></listitem>
<listitem><simpara>M - month, textual, 3 letters; i.e. "Jan"</simpara></listitem>
<listitem><simpara>s - seconds; i.e. "00" to "59"</simpara></listitem>
<listitem><simpara>S - English ordinal suffix, textual, 2 characters; i.e. "th", "nd"</simpara></listitem>
<listitem><simpara>t - number of days in the given month; i.e. "28" to "31"</simpara></listitem>
<listitem><simpara>U - seconds since the epoch</simpara></listitem>
<listitem><simpara>w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday)</simpara></listitem>
<listitem><simpara>Y - year, 4 digits; i.e. "1999"</simpara></listitem>
<listitem><simpara>y - year, 2 digits; i.e. "99"</simpara></listitem>
<listitem><simpara>z - day of the year; i.e. "0" to "365"</simpara></listitem>
<listitem><simpara>Z - timezone offset in seconds (i.e. "-43200" to "43200")</simpara></listitem>
</itemizedlist>
Unrecognized characters in the format string will be printed as-is.
The "Z" format will always return "0" when using <function>gmdate()</function>.
<example>
<title><function>date</function> example</title>
<programlisting>
print(date( "l dS of F Y h:i:s A" ));
print("July 1, 2000 is on a " . date("l", mktime(0,0,0,7,1,2000)));
</programlisting></example>
<para>
It is possible to use <function>date</function> and
<function>mktime</function> together to find dates in the
future or the past.
<example>
<title><function>date</function> and <function>mktime</function> example</title>
<programlisting>
$tomorrow = mktime(0,0,0,date("m") ,date("d")+1,date("Y"));
$lastmonth = mktime(0,0,0,date("m")-1,date("d"), date("Y"));
$nextyear = mktime(0,0,0,date("m"), date("d", date("Y")+1);
</programlisting></example>
</para>
<para>
To format dates in other languages, you should use the
<function>setlocale</function> and <function>strftime</function>
functions.
</para>
<para>
See also <function>gmdate</function> and
<function>mktime</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strftime">
<refnamediv>
<refname>strftime</refname>
<refpurpose>format a local time/date according to locale settings</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>strftime</function></funcdef>
<paramdef>string <parameter>format</parameter></paramdef>
<paramdef>int <parameter>timestamp</parameter></paramdef>
</funcsynopsis>
<para>
Returns a string formatted according to the given format string
using the given <parameter>timestamp</parameter> or the current
local time if no timestamp is given. Month and weekday names
and other language dependent strings respect the current locale
set with <function>setlocale</function>.
<para>
The following conversion specifiers are recognized in the format string:
<itemizedlist>
<listitem><simpara>%a - abbreviated weekday name according to the current locale</simpara></listitem>
<listitem><simpara>%A - full weekday name according to the current locale</simpara></listitem>
<listitem><simpara>%b - abbreviated month name according to the current locale</simpara></listitem>
<listitem><simpara>%B - full month name according to the current locale</simpara></listitem>
<listitem><simpara>%c - preferred date and time representation for the current locale</simpara></listitem>
<listitem><simpara>%d - day of the month as a decimal number (range 00 to 31)</simpara></listitem>
<listitem><simpara>%H - hour as a decimal number using a 24-hour clock (range 00 to 23)</simpara></listitem>
<listitem><simpara>%I - hour as a decimal number using a 12-hour clock (range 01 to 12)</simpara></listitem>
<listitem><simpara>%j - day of the year as a decimal number (range 001 to 366)</simpara></listitem>
<listitem><simpara>%m - month as a decimal number (range 1 to 12)</simpara></listitem>
<listitem><simpara>%M - minute as a decimal number</simpara></listitem>
<listitem><simpara>%p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale</simpara></listitem>
<listitem><simpara>%S - second as a decimal number</simpara></listitem>
<listitem><simpara>%U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week</simpara></listitem>
<listitem><simpara>%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week</simpara></listitem>
<listitem><simpara>%w - day of the week as a decimal, Sunday being 0</simpara></listitem>
<listitem><simpara>%x - preferred date representation for the current locale without the time</simpara></listitem>
<listitem><simpara>%X - preferred time representation for the current locale without the date</simpara></listitem>
<listitem><simpara>%y - year as a decimal number without a century (range 00 to 99)</simpara></listitem>
<listitem><simpara>%Y - year as a decimal number including the century</simpara></listitem>
<listitem><simpara>%Z - time zone or name or abbreviation</simpara></listitem>
<listitem><simpara>%% - a literal `%' character</simpara></listitem>
</itemizedlist>
<example>
<title><function>strftime</function> example</title>
<programlisting>
setlocale ("LC_TIME", "C");
print(strftime("%A in Finnish is "));
setlocale ("LC_TIME", "fi");
print(strftime("%A, in French "));
setlocale ("LC_TIME", "fr");
print(strftime("%A and in German "));
setlocale ("LC_TIME", "de");
print(strftime("%A.\n"));
</programlisting></example>
This example works if you have the respective locales installed
in your system.
<para>
See also <function>setlocale</function> and
<function>mktime</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.getdate">
<refnamediv>
<refname>getdate</refname>
<refpurpose>get date/time information</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>array <function>getdate</function></funcdef>
<paramdef>int <parameter>timestamp</parameter></paramdef>
</funcsynopsis>
<para>
Returns an associative array containing the date information of the
timestamp as the following array elements:
<itemizedlist>
<listitem><simpara>"seconds" - seconds</simpara></listitem>
<listitem><simpara>"minutes" - minutes</simpara></listitem>
<listitem><simpara>"hours" - hours</simpara></listitem>
<listitem><simpara>"mday" - day of the month</simpara></listitem>
<listitem><simpara>"wday" - day of the week, numeric</simpara></listitem>
<listitem><simpara>"mon" - month, numeric</simpara></listitem>
<listitem><simpara>"year" - year, numeric</simpara></listitem>
<listitem><simpara>"yday" - day of the year, numeric; i.e. "299"</simpara></listitem>
<listitem><simpara>"weekday" - day of the week, textual, full; i.e.
"Friday"</simpara></listitem>
<listitem><simpara>"month" - month, textual, full; i.e. "January"</simpara></listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.gettimeofday">
<refnamediv>
<refname>gettimeofday</refname>
<refpurpose>get current time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>array <function>gettimeofday</function></funcdef>
<paramdef>void</paramdef>
</funcsynopsis>
<para>
This is an interface to gettimeofday(2). It returns an
associative array containing the data returned from the
system call.
<itemizedlist>
<listitem><simpara>"sec" - seconds</simpara></listitem>
<listitem><simpara>"usec" - microseconds</simpara></listitem>
<listitem><simpara>"minuteswest" - minutes west of Greenwich</simpara></listitem>
<listitem><simpara>"dsttime" - type of dst correction</simpara></listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.gmdate">
<refnamediv>
<refname>gmdate</refname>
<refpurpose>format a GMT/CUT date/time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>gmdate</function></funcdef>
<paramdef>string <parameter>format</parameter></paramdef>
<paramdef>int <parameter>timestamp</parameter></paramdef>
</funcsynopsis>
<para>
Identical to the <function>date</function>
function except that the time returned is Greenwich Mean Time
(GMT). For example, when run in Finland (GMT +0200), the first
line below prints "Jan 01 1998 00:00:00", while the second prints
"Dec 31 1997 22:00:00".
<example>
<title><function>gmdate</function> example</title>
<programlisting>
echo date( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );
echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );
</programlisting></example>
</para><para>
See also <function>date</function>,
<function>mktime</function> and <function>gmmktime</function>.
</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>
<funcsynopsis>
<funcdef>int <function>easter_date</function></funcdef>
<paramdef>int <parameter>year</parameter></paramdef>
</funcsynopsis>
<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>
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>
<funcsynopsis>
<funcdef>int <function>easter_days</function></funcdef>
<paramdef>int <parameter>year</parameter></paramdef>
</funcsynopsis>
<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_date</function> example</title>
<programlisting>
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.mktime">
<refnamediv>
<refname>mktime</refname>
<refpurpose>get UNIX timestamp for a date</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>mktime</function></funcdef>
<paramdef>int <parameter>hour</parameter></paramdef>
<paramdef>int <parameter>minute</parameter></paramdef>
<paramdef>int <parameter>second</parameter></paramdef>
<paramdef>int <parameter>month</parameter></paramdef>
<paramdef>int <parameter>day</parameter></paramdef>
<paramdef>int <parameter>year</parameter></paramdef>
</funcsynopsis>
<para>
<emphasis>Warning:</emphasis> Note the strange order of
arguments, which differs from the order of arguments in
a regular UNIX mktime() call and which does not lend
itself well to leaving out parameters from right to left
(see below). It is a common error to mix these values up
in a script.
<para>
Returns the Unix timestamp corresponding to the arguments
given. This timestamp is a long integer containing the number of
seconds between the Unix Epoch (January 1 1970) and the time
specified.
</para><para>
Arguments may be left out in order from right to left; any
arguments thus omitted will be set to the current value according
to the local date and time.
</para><para>
MkTime is useful for doing date arithmetic and validation, as it
will automatically calculate the correct value for out-of-range
input. For example, each of the following lines produces the
string "Jan-01-1998".
<example>
<title><function>mktime</function> example</title>
<programlisting>
echo date( "M-d-Y", mktime(0,0,0,12,32,1997) );
echo date( "M-d-Y", mktime(0,0,0,13,1,1997) );
echo date( "M-d-Y", mktime(0,0,0,1,1,1998) );
</programlisting></example>
</para><para>
See also <function>date</function> and <function>time</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.gmmktime">
<refnamediv>
<refname>gmmktime</refname>
<refpurpose>get UNIX timestamp for a GMT date</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>gmmktime</function></funcdef>
<paramdef>int <parameter>hour</parameter></paramdef>
<paramdef>int <parameter>minute</parameter></paramdef>
<paramdef>int <parameter>second</parameter></paramdef>
<paramdef>int <parameter>month</parameter></paramdef>
<paramdef>int <parameter>day</parameter></paramdef>
<paramdef>int <parameter>year</parameter></paramdef>
</funcsynopsis>
<para>
Identical to <function>mktime</function> except the passed parameters
represents a GMT date.
</para>
</refsect1>
</refentry>
<refentry id="function.time">
<refnamediv>
<refname>time</refname>
<refpurpose>return current UNIX timestamp</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>int <function>time</function></funcdef>
<void>
</funcsynopsis>
<para>
Returns the current time measured in the number of seconds since
the Unix Epoch (January 1 1970 00:00:00 GMT).
</para><para>
See also <function>date</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.microtime">
<refnamediv>
<refname>microtime</refname>
<refpurpose>return current UNIX timestamp with microseconds</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcdef>string <function>microtime</function></funcdef>
<void>
</funcsynopsis>
<para>
Returns the string "msec sec" where sec is the current time measured in the
number of seconds since the Unix Epoch (0:00:00 January 1, 1970 GMT), and
msec is the microseconds part. This function is only available on operating
systems that support the gettimeofday() system call.
</para><para>
See also <function>time</function>.
</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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->