[PHP-DOC] cvs: phpdoc /en/reference/datetime/functions strtotime.xml

[Nuno Lopes]

nlopess         Thu Jun 23 15:38:39 2005 EDT

  Modified files:              
    /phpdoc/en/reference/datetime/functions     strtotime.xml 
  Log:
  upgrade style
  document php 5.1 changes, like the return value & date.timezone
  
http://cvs.php.net/diff.php/phpdoc/en/reference/datetime/functions/strtotime.xml?r1=1.13&r2=1.14&ty=u
Index: phpdoc/en/reference/datetime/functions/strtotime.xml
diff -u phpdoc/en/reference/datetime/functions/strtotime.xml:1.13 
phpdoc/en/reference/datetime/functions/strtotime.xml:1.14
--- phpdoc/en/reference/datetime/functions/strtotime.xml:1.13   Mon Jun  6 
13:50:53 2005
+++ phpdoc/en/reference/datetime/functions/strtotime.xml        Thu Jun 23 
15:38:38 2005
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <!-- splitted from ./en/functions/datetime.xml, last change in rev 1.8 -->
 <refentry id="function.strtotime">
  <refnamediv>
   <refname>strtotime</refname>
   <refpurpose>Parse about any English textual datetime description into a Unix 
timestamp</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>int</type><methodname>strtotime</methodname>
    <methodparam><type>string</type><parameter>time</parameter></methodparam>
@@ -18,25 +18,82 @@
    format and will try to parse that format into a Unix timestamp (the
    number of seconds since January 1 1970 00:00:00 GMT), relative
    to the timestamp given in <parameter>now</parameter>, or the current time
-   if none is supplied. Upon failure, <literal>-1</literal> is returned.
+   if none is supplied.
   </simpara>
-  <simpara>
-   Because <function>strtotime</function> behaves according to GNU
-   date syntax, have a look at the GNU manual page titled
-   <ulink url="&url.gnu.man.date-input;">Date Input Formats</ulink>.
-   Described there is valid syntax for the <parameter>time</parameter>
-   parameter.
-  </simpara>
-  <warning>
-   <para>
-    In PHP 5 up to 5.0.2, <literal>"now"</literal> and other relative times
-    are wrongly computed from today's midnight. It differs from other
-    versions where it is correctly computed from current time.
-   </para>
-  </warning>
+  <para>
+   This function will use the <envar>TZ</envar> environment variable (if
+   available) to calculate the timestamp. Since PHP 5.1.0 and if the
+   <envar>TZ</envar> variable isn't set, the <link
+    linkend="ini.date.timezone">date.timezone</link> ini configuration option
+   will be used. If none of these are available, "GMT" is assumed.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>time</parameter></term>
+     <listitem>
+      <para>
+       The string to parse, according to the GNU <ulink
+        url="&url.gnu.man.date-input;">Date Input Formats</ulink>
+       syntax
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>now</parameter></term>
+     <listitem>
+      <para>
+       The timestamp used to calculate the returned value
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns a timestamp on success, &false; otherwise. Previous to PHP 5.1.0,
+   this function would return <literal>-1</literal> on failure.
+  </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>5.1.0</entry>
+       <entry>
+        It now returns &false; on failure, instead of <literal>-1</literal>.
+        Added the <link linkend="ini.date.timezone">date.timezone</link> ini
+        option.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
   <para>
    <example>
-    <title><function>strtotime</function> examples</title>
+    <title>A <function>strtotime</function> example</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -59,7 +116,9 @@
 <![CDATA[
 <?php
 $str = 'Not Good';
-if (($timestamp = strtotime($str)) === -1) {
+
+// previous to PHP 5.1.0 you would compare with -1, instead of false
+if (($timestamp = strtotime($str)) === false) {
     echo "The string ($str) is bogus";
 } else {
     echo "$str == " . date('l dS of F Y h:i:s A', $timestamp);
@@ -69,6 +128,17 @@
     </programlisting>
    </example>
   </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <warning>
+   <para>
+    In PHP 5 up to 5.0.2, <literal>"now"</literal> and other relative times
+    are wrongly computed from today's midnight. It differs from other
+    versions where it is correctly computed from current time.
+   </para>
+  </warning>
   <note>
    <para>
     The valid range of a timestamp is typically from Fri, 13 Dec
@@ -82,6 +152,15 @@
    </para>
   </note>
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>strptime</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file