philip Wed Jan 15 05:03:35 2003 EDT
Modified files:
/phpdoc/en/reference/datetime/functions date.xml
Log:
Rewrote list in a table including additional information. This makes
it easier to read. Also some minor changes such as linking
UNIX_TIMESTAMP to the mysql manual, touchups to the examples, and
further clarication that the timestamp parameter is optional.
Index: phpdoc/en/reference/datetime/functions/date.xml
diff -u phpdoc/en/reference/datetime/functions/date.xml:1.4
phpdoc/en/reference/datetime/functions/date.xml:1.5
--- phpdoc/en/reference/datetime/functions/date.xml:1.4 Fri May 24 14:59:02 2002
+++ phpdoc/en/reference/datetime/functions/date.xml Wed Jan 15 05:03:34 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/datetime.xml, last change in rev 1.2 -->
<refentry id="function.date">
<refnamediv>
@@ -18,7 +18,8 @@
<para>
Returns a string formatted according to the given format string using the
given integer <parameter>timestamp</parameter> or the current local time
- if no timestamp is given.
+ if no timestamp is given. In otherwords, <parameter>timestamp</parameter>
+ is optional and defaults to the value of <function>time</function>.
<note>
<para>
The valid range of a timestamp is typically from Fri, 13 Dec
@@ -31,189 +32,207 @@
To generate a timestamp from a string representation of the date, you
may be able to use <function>strtotime</function>. Additionally, some
databases have functions to convert their date formats into timestamps
- (such as MySQL's UNIX_TIMESTAMP function).
+ (such as MySQL's <ulink url="&url.mysql.docs.date;">UNIX_TIMESTAMP</ulink>
+ function).
</para>
</note>
</para>
<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>
- B - Swatch Internet time
- </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; e.g. "Fri"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- F - month, textual, long; e.g. "January"
- </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>
- 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>
- i - minutes; i.e. "00" to "59"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- I (capital i) - "1" if Daylight Savings Time, "0" otherwise.
- </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;
- e.g. "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>
- M - month, textual, 3 letters; e.g. "Jan"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- n - month without leading zeros; i.e. "1" to "12"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- O - Difference to Greenwich time in hours; e.g. "+0200"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- r - RFC 822 formatted date; e.g. "Thu, 21 Dec 2000 16:01:07 +0200"
- (added in PHP 4.0.4)
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- s - seconds; i.e. "00" to "59"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- S - English ordinal suffix for the day of the month, 2 characters;
- i.e. "st", "nd", "rd" or "th"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- t - number of days in the given month; i.e. "28" to "31"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- T - Timezone setting of this machine; e.g. "EST" or "MDT"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- U - seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- w - day of the week, numeric, i.e. "0" (Sunday) to "6"
- (Saturday)
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- W - ISO-8601 week number of year, weeks starting on Monday (added in PHP
4.1.0)
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- Y - year, 4 digits; e.g. "1999"
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- y - year, 2 digits; e.g. "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"). The
- offset for timezones west of UTC is always negative, and for
- those east of UTC is always positive.
- </simpara>
- </listitem>
- </itemizedlist>
+ <table>
+ <title>The following characters are recognized in the
+ <parameter>format</parameter> parameter string</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry><parameter>format</parameter> character</entry>
+ <entry>Description</entry>
+ <entry>Example returned values</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>a</literal></entry>
+ <entry>Lowercase Ante meridiem and Post meridiem</entry>
+ <entry><literal>am</literal> or <literal>pm</literal></entry>
+ </row>
+ <row>
+ <entry><literal>A</literal></entry>
+ <entry>Uppercase Ante meridiem and Post meridiem</entry>
+ <entry><literal>AM</literal> or <literal>PM</literal></entry>
+ </row>
+ <row>
+ <entry><literal>B</literal></entry>
+ <entry>Swatch Internet time</entry>
+ <entry><literal>000</literal> through <literal>999</literal></entry>
+ </row>
+ <row>
+ <entry><literal>d</literal></entry>
+ <entry>Day of the month, 2 digits with leading zeros</entry>
+ <entry><literal>01</literal> to <literal>31</literal></entry>
+ </row>
+ <row>
+ <entry><literal>D</literal></entry>
+ <entry>A textual representation of a week, three letters</entry>
+ <entry><literal>Mon</literal> through <literal>Sun</literal></entry>
+ </row>
+ <row>
+ <entry><literal>F</literal></entry>
+ <entry>A full textual representation of a month, such as January or
+March</entry>
+ <entry><literal>January</literal> through <literal>December</literal></entry>
+ </row>
+ <row>
+ <entry><literal>g</literal></entry>
+ <entry>12-hour format of an hour without leading zeros</entry>
+ <entry><literal>1</literal> through <literal>12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>G</literal></entry>
+ <entry>24-hour format of an hour without leading zeros</entry>
+ <entry><literal>0</literal> through <literal>23</literal></entry>
+ </row>
+ <row>
+ <entry><literal>h</literal></entry>
+ <entry>12-hour format of an hour with leading zeros</entry>
+ <entry><literal>01</literal> through <literal>12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>H</literal></entry>
+ <entry>24-hour format of an hour with leading zeros</entry>
+ <entry><literal>00</literal> through <literal>23</literal></entry>
+ </row>
+ <row>
+ <entry><literal>i</literal></entry>
+ <entry>Minutes with leading zeros</entry>
+ <entry><literal>00</literal> to <literal>59</literal></entry>
+ </row>
+ <row>
+ <entry><literal>I</literal> (capital i)</entry>
+ <entry>Whether or not the date is in daylights savings time</entry>
+ <entry><literal>1</literal> if Daylight Savings Time, <literal>0</literal>
+otherwise.</entry>
+ </row>
+ <row>
+ <entry><literal>j</literal></entry>
+ <entry>Day of the month without leading zeros</entry>
+ <entry><literal>1</literal> to <literal>31</literal></entry>
+ </row>
+ <row>
+ <entry><literal>l</literal> (lowercase 'L')</entry>
+ <entry>A full textual representation of the day of the week</entry>
+ <entry><literal>Sunday</literal> through <literal>Saturday</literal></entry>
+ </row>
+ <row>
+ <entry><literal>L</literal></entry>
+ <entry>Whether it's a leap year</entry>
+ <entry><literal>1</literal> if it is a leap year, <literal>0</literal>
+otherwise.</entry>
+ </row>
+ <row>
+ <entry><literal>m</literal></entry>
+ <entry>Numeric representation of a month, with leading zeros</entry>
+ <entry><literal>01</literal> through <literal>12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>M</literal></entry>
+ <entry>A short textual representation of a month, three letters</entry>
+ <entry><literal>Jan</literal> through <literal>Dec</literal></entry>
+ </row>
+ <row>
+ <entry><literal>n</literal></entry>
+ <entry>Numeric representation of a month, without leading zeros</entry>
+ <entry><literal>1</literal> through <literal>12</literal></entry>
+ </row>
+ <row>
+ <entry><literal>O</literal></entry>
+ <entry>Difference to Greenwich time (GMT) in hours</entry>
+ <entry>Example: <literal>+0200</literal></entry>
+ </row>
+ <row>
+ <entry><literal>r</literal></entry>
+ <entry>RFC 822 formatted date</entry>
+ <entry>Example: <literal>Thu, 21 Dec 2000 16:01:07 +0200</literal></entry>
+ </row>
+ <row>
+ <entry><literal>s</literal></entry>
+ <entry>Seconds, with leading zeros</entry>
+ <entry><literal>00</literal> through <literal>59</literal></entry>
+ </row>
+ <row>
+ <entry><literal>S</literal></entry>
+ <entry>English ordinal suffix for the day of the month, 2 characters</entry>
+ <entry>
+ <literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> or
+ <literal>th</literal>. Works well with <literal>j</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>t</literal></entry>
+ <entry>Number of days in the given month</entry>
+ <entry><literal>28</literal> through <literal>31</literal></entry>
+ </row>
+ <row>
+ <entry><literal>T</literal></entry>
+ <entry>Timezone setting of this machine</entry>
+ <entry>Examples: <literal>EST</literal>, <literal>MDT</literal> ...</entry>
+ </row>
+ <row>
+ <entry><literal>U</literal></entry>
+ <entry>Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)</entry>
+ <entry>See also <function>time</function></entry>
+ </row>
+ <row>
+ <entry><literal>w</literal></entry>
+ <entry>Numeric representation of the day of the week</entry>
+ <entry><literal>0</literal> (for Sunday) through <literal>6</literal> (for
+Saturday)</entry>
+ </row>
+ <row>
+ <entry><literal>W</literal></entry>
+ <entry>ISO-8601 week number of year, weeks starting on Monday (added in PHP
+4.1.0)</entry>
+ <entry>Example: <literal>42</literal> (the 42nd week in the year)</entry>
+ </row>
+ <row>
+ <entry><literal>Y</literal></entry>
+ <entry>A full numeric representation of a year, 4 digits</entry>
+ <entry>Examples: <literal>1999</literal> or <literal>2003</literal></entry>
+ </row>
+ <row>
+ <entry><literal>y</literal></entry>
+ <entry>A two digit representation of a year</entry>
+ <entry>Examples: <literal>99</literal> or <literal>03</literal></entry>
+ </row>
+ <row>
+ <entry><literal>z</literal></entry>
+ <entry>The day of the year</entry>
+ <entry><literal>0</literal> through <literal>366</literal></entry>
+ </row>
+ <row>
+ <entry><literal>Z</literal></entry>
+ <entry>Timezone offset in seconds. The offset for timezones west of UTC is
+always
+ negative, and for those east of UTC is always positive.</entry>
+ <entry><literal>-43200</literal> through <literal>43200</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
Unrecognized characters in the format string will be printed
- as-is. The "Z" format will always return "0" when using
- <function>gmdate</function>.
+ as-is. The <literal>Z</literal> format will always return
+ <literal>0</literal> when using <function>gmdate</function>.
</para>
<para>
<example>
- <title><function>date</function> example</title>
+ <title><function>date</function> examples</title>
<programlisting role="php">
<![CDATA[
+<?php
+// Prints something like: Wednesday
+echo date("l");
+
+// Prints something like: Wednesday 15th of January 2003 05:51:38 AM
echo date ("l dS of F Y h:i:s A");
+
+// Prints: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date ("l", mktime(0,0,0,7,1,2000));
+?>
]]>
</programlisting>
</example>
@@ -227,7 +246,10 @@
<title>Escaping characters in <function>date</function></title>
<programlisting role="php">
<![CDATA[
-echo date("l \\t\h\e jS"); // prints something like 'Saturday the 8th'
+<?php
+// prints something like: Wednesday the 15th
+echo date("l \\t\h\e jS");
+?>
]]>
</programlisting>
</example>
@@ -243,9 +265,11 @@
</title>
<programlisting role="php">
<![CDATA[
+<?php
$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>
@@ -270,7 +294,9 @@
</title>
<programlisting role="php">
<![CDATA[
-/* Today is March 10th, 2001, 5:16:18 pm */
+<?php
+// Assuming today is: March 10th, 2001, 5:16:18 pm
+
$today = date("F j, Y, g:i a"); // March 10, 2001, 5:16 pm
$today = date("m.d.y"); // 03.10.01
$today = date("j, n, Y"); // 10, 3, 2001
@@ -280,6 +306,7 @@
$today = date("D M j G:i:s T Y"); // Sat Mar 10 15:16:08 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h'); // 17:03:17 m is month
$today = date("H:i:s"); // 17:16:17
+?>
]]>
</programlisting>
</example>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
