jimw Thu Nov 1 20:14:56 2001 EDT
Modified files:
/phpdoc/en/functions datetime.xml
Log:
add some more notes and examples based on user notes.
Index: phpdoc/en/functions/datetime.xml
diff -u phpdoc/en/functions/datetime.xml:1.49 phpdoc/en/functions/datetime.xml:1.50
--- phpdoc/en/functions/datetime.xml:1.49 Sun Oct 7 09:16:55 2001
+++ phpdoc/en/functions/datetime.xml Thu Nov 1 20:14:56 2001
@@ -1,5 +1,5 @@
<?xml encoding="iso-8859-1"?>
-<!-- $Revision: 1.49 $ -->
+<!-- $Revision: 1.50 $ -->
<reference id="ref.datetime">
<title>Date and Time functions</title>
<titleabbrev>Date/time</titleabbrev>
@@ -65,9 +65,23 @@
</funcprototype>
</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.
+ 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.
+ <note>
+ <para>
+ The valid range of a timestamp is typically from Fri, 13 Dec
+ 1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are
+ the dates that correspond to the minimum and maximum values for
+ a 32-bit signed integer.)
+ </para>
+ <para>
+ 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).
+ </para>
+ </note>
</para>
<para>
The following characters are recognized in the format string:
@@ -168,7 +182,7 @@
</listitem>
<listitem>
<simpara>
- O - Difference to Greenwich time in hours; i.e. "+0200"
+ O - Difference to Greenwich time in hours; i.e. "+0200"
</simpara>
</listitem>
<listitem>
@@ -235,11 +249,25 @@
Unrecognized characters in the format string will be printed
as-is. The "Z" format will always return "0" when using
<function>gmdate</function>.
+ </para>
+ <para>
<example>
<title><function>date</function> example</title>
<programlisting role="php">
-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)));
+echo date ("l dS of F Y h:i:s A");
+echo "July 1, 2000 is on a " . date ("l", mktime(0,0,0,7,1,2000));
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ You can prevent a recognized character in the format string from being
+ expanded by escaping it with a preceding backslash. If the character with
+ a backslash is already a special sequence, you may need to also escape
+ the backslash.
+ <example>
+ <title>Escaping characters in <function>date</function></title>
+ <programlisting role="php">
+echo date("l \\t\h\e jS"); // prints something like 'Saturday the 8th'
</programlisting>
</example>
</para>
@@ -258,6 +286,13 @@
$nextyear = mktime (0,0,0,date("m"), date("d"), date("Y")+1);
</programlisting>
</example>
+ <note>
+ <para>
+ This can be more reliable than simply adding or substracting the number
+ of seconds in a day or month to a timestamp because of daylight savings
+ time.
+ </para>
+ </note>
</para>
<para>
Some examples of <function>date</function> formatting. Note that
@@ -290,8 +325,9 @@
functions.
</para>
<para>
- See also <function>gmdate</function>,
- <function>mktime</function> and <function>strftime</function>.
+ See also <function>getlastmod</function>, <function>gmdate</function>,
+ <function>mktime</function>, <function>strftime</function>
+ and <function>time</function>.
</para>
</refsect1>
</refentry>
