php-doc-en/reference/datetime/functions/strptime.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.strptime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <refnamediv>
    <refname>strptime</refname>
    <refpurpose>
     Parse a time/date generated with <function>strftime</function>
    </refpurpose>
   </refnamediv>
   <refsect1 role="description">
    &reftitle.description;
    <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>strptime</methodname>
   <methodparam><type>string</type><parameter>timestamp</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
  </methodsynopsis>
    <para>
     <function>strptime</function> returns an array with the
     <parameter>timestamp</parameter> parsed, or &false; on error.
    </para>
    <para>
     Month and weekday names and other language dependent strings respect the
     current locale set with <function>setlocale</function> (<constant>LC_TIME</constant>).
    </para>
   </refsect1>

   <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
    <variablelist>
     <varlistentry>
      <term><parameter>timestamp</parameter> (<type>string</type>)</term>
      <listitem>
       <para>
        The string to parse (e.g. returned from <function>strftime</function>).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>format</parameter> (<type>string</type>)</term>
      <listitem>
       <para>
        The format used in <parameter>timestamp</parameter> (e.g. the same as
        used in <function>strftime</function>). Note that some of the format
        options available to <function>strftime</function> may not have any
        effect within <function>strptime</function>; the exact subset that are
        supported will vary based on the operating system and C library in
        use.
       </para>
       <para>
        For more information about the format options, read the
        <function>strftime</function> page.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect1>

  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
    Returns an array&return.falseforfailure;.
   </para>

    <para>
     <table>
      <title>The following parameters are returned in the array</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>parameters</entry>
         <entry>Description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><literal>"tm_sec"</literal></entry>
         <entry>Seconds after the minute (0-61)</entry>
        </row>
        <row>
         <entry><literal>"tm_min"</literal></entry>
         <entry>Minutes after the hour (0-59)</entry>
        </row>
        <row>
         <entry><literal>"tm_hour"</literal></entry>
         <entry>Hour since midnight (0-23)</entry>
        </row>
        <row>
         <entry><literal>"tm_mday"</literal></entry>
         <entry>Day of the month (1-31)</entry>
        </row>
        <row>
         <entry><literal>"tm_mon"</literal></entry>
         <entry>Months since January (0-11)</entry>
        </row>
        <row>
         <entry><literal>"tm_year"</literal></entry>
         <entry>Years since 1900</entry>
        </row>
        <row>
         <entry><literal>"tm_wday"</literal></entry>
         <entry>Days since Sunday (0-6)</entry>
        </row>
        <row>
         <entry><literal>"tm_yday"</literal></entry>
         <entry>Days since January 1 (0-365)</entry>
        </row>
        <row>
         <entry><literal>"unparsed"</literal></entry>
         <entry>the <parameter>timestamp</parameter> part which was not
          recognized using the specified <parameter>format</parameter></entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>

  </refsect1>

  <refsect1 role="examples">
   &reftitle.examples;
   <para>
   <example>
    <title><function>strptime</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$format = '%d/%m/%Y %H:%M:%S';
$strf = strftime($format);

echo "$strf\n";

print_r(strptime($strf, $format));
?>
]]>
      </programlisting>
      &example.outputs.similar;
      <screen>
<![CDATA[
03/10/2004 15:54:19

Array
(
    [tm_sec] => 19
    [tm_min] => 54
    [tm_hour] => 15
    [tm_mday] => 3
    [tm_mon] => 9
    [tm_year] => 104
    [tm_wday] => 0
    [tm_yday] => 276
    [unparsed] =>
)
]]>
      </screen>
      </example>
     </para>
    </refsect1>

    <refsect1 role="notes">
     &reftitle.notes;
     &note.no-windows;
     <note>
      <para>
       Internally, this function calls the <literal>strptime()</literal>
       function provided by the system's C library. This function can exhibit
       noticeably different behaviour across different operating systems. The
       use of <function>date_parse_from_format</function>, which does not
       suffer from these issues, is recommended on PHP 5.3.0 and later.
      </para>
     </note>
     <note>
      <para>
       <literal>"tm_sec"</literal> includes any leap seconds (currently upto 2
       a year). For more information on leap seconds, see the <link
       xlink:href="&url.wiki.leap-seconds;">Wikipedia article
       on leap seconds</link>.
      </para>
     </note>
     <note>
      <para>
       Prior to PHP 5.2.0, this function could return undefined behaviour. Notably,
       the <literal>"tm_sec"</literal>, <literal>"tm_min"</literal> and <literal>"tm_hour"</literal> 
       entries would return undefined values.
      </para>
     </note>
    </refsect1>

    <refsect1 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>checkdate</function></member>
      <member><function>strftime</function></member>
      <member><function>date_parse_from_format</function></member>
      <member><function>DateTime::createFromFormat</function></member>
     </simplelist>
    </para>
   </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
-->