sscanf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.sscanf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>sscanf</refname>
  <refpurpose>Parses input from a string according to a format</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>int</type><type>null</type></type><methodname>sscanf</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
  </methodsynopsis>
  <para>
   The function <function>sscanf</function> is the input analog of
   <function>printf</function>. <function>sscanf</function> reads
   from the string <parameter>string</parameter> and interprets it
   according to the specified <parameter>format</parameter>. 
  </para>
  <para>
   Any whitespace in the format string matches any whitespace in the input
   string. This means that even a tab (<literal>\t</literal>) in the format string can match a
   single space character in the input string.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       The input <type>string</type> being parsed.
      </para>
     </listitem>
    </varlistentry>
    &strings.scanf.parameter.format;
    <varlistentry>
     <term><parameter>vars</parameter></term>
     <listitem>
      <para>
       Optionally pass in variables by reference that will contain the parsed values.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   If only two parameters were passed to this function, the values parsed will
   be returned as an array. Otherwise, if optional parameters are passed, the
   function will return the number of assigned values. The optional parameters
   must be passed by reference.
  </para>
  <para>
   If there are more substrings expected in the <parameter>format</parameter>
   than there are available within <parameter>string</parameter>,
   &null; will be returned.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>sscanf</function> Example</title>
    <programlisting role="php">
<![CDATA[
<?php
// getting the serial number
list($serial) = sscanf("SN/2350001", "SN/%d");
// and the date of manufacturing
$mandate = "January 01 2000";
list($month, $day, $year) = sscanf($mandate, "%s %d %d");
echo "Item $serial was manufactured on: $year-" . substr($month, 0, 3) . "-$day\n";
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   If optional parameters are passed, the function will return the
   number of assigned values.
  </para>
  <para>
   <example>
    <title><function>sscanf</function> - using optional parameters</title>
    <programlisting role="php">
<![CDATA[
<?php
// get author info and generate DocBook entry
$auth = "24\tLewis Carroll";
$n = sscanf($auth, "%d\t%s %s", $id, $first, $last);
echo "<author id='$id'>
    <firstname>$first</firstname>
    <surname>$last</surname>
</author>\n";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>printf</function></member>
    <member><function>sprintf</function></member>
    <member><function>fprintf</function></member>
    <member><function>vprintf</function></member>
    <member><function>vsprintf</function></member>
    <member><function>vfprintf</function></member>
    <member><function>fscanf</function></member>
    <member><function>number_format</function></member>
    <member><function>date</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
-->