cvs: phpdoc /en/functions datetime.xml

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>