createfromformat.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="datetimeimmutable.createfromformat" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>DateTimeImmutable::createFromFormat</refname>
  <refname>date_create_immutable_from_format</refname>
  <refpurpose>Parses a time string according to a specified format</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="oop">
   <modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>DateTimeImmutable</type><type>false</type></type><methodname>DateTimeImmutable::createFromFormat</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam><type>string</type><parameter>datetime</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis role="procedural">
   <type class="union"><type>DateTimeImmutable</type><type>false</type></type><methodname>date_create_immutable_from_format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam><type>string</type><parameter>datetime</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Returns a new DateTimeImmutable object representing the date and time specified by the
   <parameter>datetime</parameter> string, which was formatted in the given
   <parameter>format</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>format</parameter></term>
    <listitem>
     <para>
      The format that the passed in <type>string</type> should be in. See the
      formatting options below. In most cases, the same letters as for the
      <function>date</function> can be used.
     </para>
     <para>
      The format is parsed from left to right, which means that in some
      situations the order in which the format characters are present effects
      the result. In in the case of <literal>z</literal> (the day of the year)
      it is required that it is only used if a year has already been parsed,
      for example through the <literal>Y</literal> or <literal>y</literal>
      characters.
     </para>
     <para>
      <table>
       <title>The following characters are recognized in the
       <parameter>format</parameter> parameter string</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry><parameter>format</parameter> character</entry>
          <entry>Description</entry>
          <entry>Example parsable values</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry align="center"><emphasis>Day</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>d</literal> and <literal>j</literal></entry>
          <entry>Day of the month, 2 digits with or without leading zeros</entry>
          <entry>
           <literal>01</literal> to <literal>31</literal> or
           <literal>1</literal> to <literal>31</literal>
          </entry>
         </row>
         <row>
          <entry><literal>D</literal> and <literal>l</literal></entry>
          <entry>A textual representation of a day</entry>
          <entry>
           <literal>Mon</literal> through <literal>Sun</literal> or
           <literal>Sunday</literal> through <literal>Saturday</literal>
          </entry>
         </row>
         <row>
          <entry><literal>S</literal></entry>
          <entry>English ordinal suffix for the day of the month, 2
          characters. It's ignored while processing.</entry>
          <entry>
           <literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> or
           <literal>th</literal>.
          </entry>
         </row>
         <row>
          <entry><literal>z</literal></entry>
          <entry>
           The day of the year (starting from 0);
           must be preceded by <literal>Y</literal> or <literal>y</literal>.
          </entry>
          <entry><literal>0</literal> through <literal>365</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Month</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>F</literal> and <literal>M</literal></entry>
          <entry>A textual representation of a month, such as January or Sept</entry>
          <entry>
           <literal>January</literal> through <literal>December</literal> or
           <literal>Jan</literal> through <literal>Dec</literal>
          </entry>
         </row>
         <row>
          <entry><literal>m</literal> and <literal>n</literal></entry>
          <entry>Numeric representation of a month, with or without leading zeros</entry>
          <entry>
           <literal>01</literal> through <literal>12</literal> or
           <literal>1</literal> through <literal>12</literal>
          </entry>
         </row>
         <row>
          <entry align="center"><emphasis>Year</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>Y</literal></entry>
          <entry>A full numeric representation of a year, up to 4 digits</entry>
          <entry>Examples: <literal>0055</literal>, <literal>787</literal>,
           <literal>1999</literal>, <literal>2003</literal></entry>
         </row>
         <row>
          <entry><literal>y</literal></entry>
          <entry>
           A two digit representation of a year (which is assumed to be in the
           range 1970-2069, inclusive)
          </entry>
          <entry>
           Examples:
           <literal>99</literal> or <literal>03</literal>
           (which will be interpreted as <literal>1999</literal> and
           <literal>2003</literal>, respectively)
          </entry>
         </row>
         <row>
          <entry align="center"><emphasis>Time</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>a</literal> and <literal>A</literal></entry>
          <entry>Ante meridiem and Post meridiem</entry>
          <entry><literal>am</literal> or <literal>pm</literal></entry>
         </row>
         <row>
          <entry><literal>g</literal> and <literal>h</literal></entry>
          <entry>12-hour format of an hour with or without leading zero</entry>
          <entry>
           <literal>1</literal> through <literal>12</literal> or
           <literal>01</literal> through <literal>12</literal>
          </entry>
         </row>
         <row>
          <entry><literal>G</literal> and <literal>H</literal></entry>
          <entry>24-hour format of an hour with or without leading zeros</entry>
          <entry>
           <literal>0</literal> through <literal>23</literal> or
           <literal>00</literal> through <literal>23</literal> (2 digit
           numbers higher than 24 are accepted, in which case they will make
           the day overflow. For example using <literal>26</literal> means
           <literal>02:00</literal> the next day)
          </entry>
         </row>
         <row>
          <entry><literal>i</literal></entry>
          <entry>Minutes with leading zeros</entry>
          <entry><literal>00</literal> to <literal>59</literal></entry>
         </row>
         <row>
          <entry><literal>s</literal></entry>
          <entry>Seconds, with leading zeros</entry>
          <entry><literal>00</literal> through <literal>59</literal></entry>
         </row>
         <row>
          <entry><literal>v</literal></entry>
          <entry>Milliseconds (up to three digits)</entry>
          <entry>Example: <literal>12</literal>, <literal>345</literal></entry>
         </row>
         <row>
          <entry><literal>u</literal></entry>
          <entry>Microseconds (up to six digits)</entry>
          <entry>Example: <literal>45</literal>, <literal>654321</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Timezone</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry>
           <literal>e</literal>, <literal>O</literal>,
           <literal>P</literal> and <literal>T</literal>
          </entry>
          <entry>Timezone identifier, or difference to UTC in hours, or
          difference to UTC with colon between hours and minutes, or timezone
          abbreviation</entry>
          <entry>Examples: <literal>UTC</literal>, <literal>GMT</literal>,
           <literal>Atlantic/Azores</literal> or 
           <literal>+0200</literal> or <literal>+02:00</literal> or
           <literal>EST</literal>, <literal>MDT</literal>
          </entry>
         </row>
         <row>
          <entry align="center"><emphasis>Full Date/Time</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal>U</literal></entry>
          <entry>Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)</entry>
          <entry>Example: <literal>1292177455</literal></entry>
         </row>
         <row>
          <entry align="center"><emphasis>Whitespace and Separators</emphasis></entry>
          <entry>---</entry>
          <entry>---</entry>
         </row>
         <row>
          <entry><literal> </literal> (space)</entry>
          <entry>One space or one tab</entry>
          <entry>Example: <literal> </literal></entry>
         </row>
         <row>
          <entry><literal>#</literal></entry>
          <entry>
           One of the following separation symbol: <literal>;</literal>,
           <literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
           <literal>,</literal>, <literal>-</literal>, <literal>(</literal> or
           <literal>)</literal>
          </entry>
          <entry>Example: <literal>/</literal></entry>
         </row>
         <row>
          <entry>
           <literal>;</literal>,
           <literal>:</literal>, <literal>/</literal>, <literal>.</literal>,
           <literal>,</literal>, <literal>-</literal>, <literal>(</literal> or
           <literal>)</literal>
          </entry>
          <entry>The specified character.</entry>
          <entry>Example: <literal>-</literal></entry>
         </row>
         <row>
          <entry><literal>?</literal></entry>
          <entry>A random byte</entry>
          <entry>Example: <literal>^</literal> (Be aware that for UTF-8
          characters you might need more than one <literal>?</literal>.
          In this case, using <literal>*</literal> is probably what you want
          instead)</entry>
         </row>
         <row>
          <entry><literal>*</literal></entry>
          <entry>Random bytes until the next separator or digit</entry>
          <entry>Example: <literal>*</literal> in <literal>Y-*-d</literal> with
          the string <literal>2009-aWord-08</literal> will match
          <literal>aWord</literal></entry>
         </row>
         <row>
          <entry><literal>!</literal></entry>
          <entry>Resets all fields (year, month, day, hour, minute, second,
          fraction and timezone information) to zero-like values (
           <literal>0</literal> for hour, minute, second and fraction,
           <literal>1</literal> for month and day, <literal>1970</literal>
           for year and <literal>UTC</literal> for timezone information)</entry>
          <entry>Without <literal>!,</literal> all fields will be set to the
          current date and time.</entry>
         </row>
         <row>
          <entry><literal>|</literal></entry>
          <entry>Resets all fields (year, month, day, hour, minute, second,
          fraction and timezone information) to zero-like values if they have
          not been parsed yet</entry>
          <entry><literal>Y-m-d|</literal> will set the year, month and day
          to the information found in the string to parse, and sets the hour,
          minute and second to 0.</entry>
         </row>
         <row>
          <entry><literal>+</literal></entry>
          <entry>If this format specifier is present, trailing data in the
          string will not cause an error, but a warning instead</entry>
          <entry>Use <methodname>DateTimeImmutable::getLastErrors</methodname> to find out
          whether trailing data was present.</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
     <para>
      Unrecognized characters in the format string will cause the
      parsing to fail and an error message is appended to the returned
      structure. You can query error messages with
      <methodname>DateTimeImmutable::getLastErrors</methodname>.
     </para>       
     <para>
      To include literal characters in <parameter>format</parameter>, you have
      to escape them with a backslash (<literal>\</literal>).
     </para>
     <para>
      If <parameter>format</parameter> does not contain the character
      <literal>!</literal> then portions of the generated time which are not
      specified in <parameter>format</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 not provided in <parameter>format</parameter>, as well as
      values to the left-hand side of the <literal>!</literal>, will
      be set to corresponding values from the Unix epoch.
     </para>
     <para>
      The Unix epoch is 1970-01-01 00:00:00 UTC.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>datetime</parameter></term>
    <listitem>
     <para>
      String representing the time.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>timezone</parameter></term>
    <listitem>
     <para>
      A <classname>DateTimeZone</classname> object representing the
      desired time zone.
     </para>
     <para>
      If <parameter>timezone</parameter> is omitted or &null; and
      <parameter>datetime</parameter> contains no timezone,
      the current timezone will be used.
     </para>
     <note>
      <para>
       The <parameter>timezone</parameter> parameter
       and the current timezone are ignored when the
       <parameter>datetime</parameter> parameter either
       contains a UNIX timestamp (e.g. <literal>946684800</literal>)
       or specifies a timezone
       (e.g. <literal>2010-01-28T15:00:00+02:00</literal>).
      </para>
     </note>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a new DateTimeImmutable instance&return.falseforfailure;.
  </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>7.3.0</entry>
       <entry>
        The <literal>v</literal> <parameter>format</parameter> specifier has been added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>DateTimeImmutable::createFromFormat</function> example</title>
   <para>&style.oop;</para>
   <programlisting role="php">
<![CDATA[
<?php
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');
?>
]]>
   </programlisting>
  </example>
  <example>
   <title>Intricacies of <function>DateTimeImmutable::createFromFormat</function></title>
   <programlisting role="php">
<![CDATA[
<?php
echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
Current time: 2010-04-23 10:29:35
Format: Y-m-d; 2009-02-15 10:29:35
Format: Y-m-d H:i:s; 2009-02-15 15:16:17
Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
Format: !d; 1970-01-15 00:00:00
]]>
   </screen>
  </example>
  <example>
   <title>Format string with literal characters</title>
   <programlisting role="php">
<![CDATA[
<?php
echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
23:15:03
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>DateTimeImmutable::__construct</function></member>
   <member><function>DateTimeImmutable::getLastErrors</function></member>
   <member><function>checkdate</function></member>
   <member><function>strptime</function></member>
  </simplelist>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->