From 7029153ebb0b225670fedbc07e96d2bbbdc6ea90 Mon Sep 17 00:00:00 2001
From: jim winstead <jimw@php.net>
Date: Fri, 2 Nov 2001 01:14:56 +0000
Subject: [PATCH] add some more notes and examples based on user notes.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@61375 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/datetime.xml | 54 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/functions/datetime.xml b/functions/datetime.xml
index 127bdac0da..485735b493 100644
--- a/functions/datetime.xml
+++ b/functions/datetime.xml
@@ -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 @@ $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>
+     <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 @@ $today = date("H:i:s");                         // 17:16:17
      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>