archived-doc-es/reference/strings/functions/sscanf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5e6e91b7dc20a1872c553d49ebb2144d22396177 Maintainer: jpberdejo Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sscanf" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>sscanf</refname>
  <refpurpose>Interpreta un string de entrada de acuerdo con un formato</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>sscanf</methodname>
   <methodparam><type>string</type><parameter>str</parameter></methodparam>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter role="reference">...</parameter></methodparam>
  </methodsynopsis>
  <para>
   La función <function>sscanf</function> es la entrada análoga de
   <function>printf</function>. <function>sscanf</function> lee
   del string <parameter>str</parameter> y lo interpreta
   de acuerdo con el <parameter>format</parameter> especificado, el cual está
   descrito en la documentación para <function>sprintf</function>.
  </para>
  <para>
   Cualquier espacio en blanco en el string de formato coincide con cualquier espacio en blanco en string
   de entrada. Esto significa que incluso un tabulador \t en el string de formato puede coincidir con un
   caracter simple de espacio en el string de entrada.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>str</parameter></term>
     <listitem>
      <para>
       El <type>string</type> de entrada para ser interpretado.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       El formato interpretado <parameter>str</parameter>, el cual está
       descrito en la documentación para <function>sprintf</function> con
       las siguientes diferencia:
       <simplelist>
        <member>
         La función no es consciente de la configuración regional.
        </member>
        <member>
         <literal>F</literal>, <literal>g</literal>, <literal>G</literal> y
         <literal>b</literal> no están soportados.
        </member>
        <member>
         <literal>D</literal> representa número decimal.
        </member>
        <member>
         <literal>i</literal> representa integer con detección de base.
        </member>
        <member>
         <literal>n</literal> representa el número de caracteres procesados hasta el momento.
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>...</parameter></term>
     <listitem>
      <para>
       Opcionalmente variables pasadas por referencia que contendrán los valores interpretados.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Si sólo se pasan dos parámetros a esta función, los valores interpretados
   se devolverán como una matriz. De lo contrario, si se pasan parámetros opcionales,
   la función devolverá el número de valores asignados. Los parámetros
   opcionales se deben pasar por referencia.
  </para>
  <para>
   Si hay más substrings esperados en el <parameter>format</parameter>
   que los que hay disponibles en <parameter>str</parameter>,
   será devuelto <literal>-1</literal>.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>sscanf</function></title>
    <programlisting role="php">
<![CDATA[
<?php
// obtener el número serial
list($serial) = sscanf("SN/2350001", "SN/%d");
// y la fecha de manufactura
$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>
   Si se pasan parámetros opcionales, la función devolverá el
   número de valores asignados.
  </para>
  <para>
   <example>
    <title><function>sscanf</function> - using optional parameters</title>
    <programlisting role="php">
<![CDATA[
<?php
// obtener la información del autor y generar entrada DocBook
$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>fscanf</function></member>
    <member><function>printf</function></member>
    <member><function>sprintf</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
-->