From 6bd8161553051690fce3e98756471e72b38666d8 Mon Sep 17 00:00:00 2001
From: Torben Wilson <torben@php.net>
Date: Sun, 13 Sep 2009 09:14:40 +0000
Subject: [PATCH] More thorough explanation of the use of ! to select default
 values in the generated time.

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

diff --git a/reference/datetime/datetime/createfromformat.xml b/reference/datetime/datetime/createfromformat.xml
index 31599105c6..cdfbfc5007 100644
--- a/reference/datetime/datetime/createfromformat.xml
+++ b/reference/datetime/datetime/createfromformat.xml
@@ -30,6 +30,30 @@
       <para>
        Format accepted by <function>date</function>.
       </para>
+      <para>
+       If <parameter>format</parameter> does not contain the character
+       <literal>!</literal> then portions of the date/time value
+       specified in <parameter>format</parameter> but not specified
+       in <parameter>time</parameter> will be set to the current
+       system time.
+      </para>
+      <para>
+       If <parameter>format</parameter> contains the
+       character <literal>!</literal>, then portions of the generated
+       time specified to the left-hand side of
+       the <literal>!</literal> in <parameter>format</parameter> will
+       be set to corresponding values from the Unix epoch.
+      </para>
+      <para>
+       If the first character of <parameter>format</parameter>
+       is <literal>!</literal>, then all portions of the date/time
+       value generated which are not specified in
+       <parameter>time</parameter> will be initialized to corresponding
+       values from the Unix epoch. 
+      </para>
+      <para>
+       The Unix epoch is 1970-01-01 00:00:00.
+      </para>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -50,15 +74,6 @@
     </varlistentry>
    </variablelist>
   </para>
-  <para>
-   If the first character of <parameter>format</parameter>
-   is <literal>!</literal>, then portions of the date/time value
-   generated which are not specified in
-   <parameter>time</parameter> will be initialized to zero. If the
-   first character of <parameter>format</parameter> is
-   not <literal>!</literal> then portions of the date/time value
-   generated will be initialized to the current system time.
-  </para>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -68,6 +83,50 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using <literal>!</literal> to reset default date/time values</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo "Current system date and time: " . date('Y-m-d H:i:s') . "\n";
+
+$format = 'Y-m-d';
+$dt = DateTime::createFromFormat($format, '2009-02-03');
+echo "Format: $format; " . $dt->date . "\n";
+
+$format = 'Y-m-d H:i:s';
+$dt = DateTime::createFromFormat($format, '2009-02-03 15:16:17');
+echo "Format: $format; " . $dt->date . "\n";
+
+$format = 'Y-m-!d H:i:s';
+$dt = DateTime::createFromFormat($format, '2009-02-03 15:16:17');
+echo "Format: $format; " . $dt->date . "\n";
+
+$format = '!Y-m-d';
+$dt = DateTime::createFromFormat($format, '2009-02-03');
+echo "Format: $format; " . $dt->date . "\n";
+?>
+]]>
+    </programlisting>
+    <para>
+     The above example will output something like the following
+     (taking into account the current system time):
+    </para>
+    <screen>
+<![CDATA[
+Current system date and time: 2009-09-13 01:04:03
+Format: Y-m-d; 2009-02-03 01:04:03
+Format: Y-m-d H:i:s; 2009-02-03 15:16:17
+Format: Y-m-!d H:i:s; 1970-01-03 15:16:17
+Format: !Y-m-d; 2009-02-03 00:00:00
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file