preg-split.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 8adbf24fe904dcdd35212084a426ee20044b7285 Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<refentry xml:id="function.preg-split" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_split</refname>
  <refpurpose>Divide un string mediante una expresión regular</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>preg_split</methodname>
   <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Divide el string dado mediante una expresión regular.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
       El patrón de búsqueda, dado como string.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       El string de entrada.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
       Si se especifica, son devueltos únicamente los substrings hasta
       <parameter>limit</parameter>, con el resto del string colocado en el último
       substring. Si <parameter>limit</parameter> vale -1 o 0 significa "sin límite".
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter> puede ser una combinación de las siguientes
       banderas (combinadas con el operador <literal>|</literal> de bits):
       <variablelist>
        <varlistentry>
         <term><constant>PREG_SPLIT_NO_EMPTY</constant></term>
         <listitem>
          <simpara>
           Si se aplica esta bandera, solo serán devueltos los elementos no vacíos por
           <function>preg_split</function>.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>PREG_SPLIT_DELIM_CAPTURE</constant></term>
         <listitem>
          <simpara>
           Si se aplica esta bandera, las expresiones entre paréntesis en el patrón delimitador
           serán capturadas y devueltas.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>PREG_SPLIT_OFFSET_CAPTURE</constant></term>
         <listitem>
          <para>
           Si se aplica esta bandera, por cada coincidencia producida, el índice del string añadido
           también será devuelto. Observe que esto cambia el valor devuelto
           dentro de un array donde cada elemento es un array consistente en
           el string coincidente en el índice <literal>0</literal> y su índice de string
           dentro de <parameter>subject</parameter> en el índice <literal>1</literal>.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un array que contiene substrings de <parameter>subject</parameter>
   dividido por los límites coincidentes de <parameter>pattern</parameter>, &return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &pcre.pattern.warning;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>preg_split</function> : Obtener las partes de un string de búsqueda</title>
    <programlisting role="php">
<![CDATA[
<?php
// divide la frase mediante cualquier número de comas o caracteres de espacio,
// lo que incluye " ", \r, \t, \n y \f
$claves = preg_split("/[\s,]+/", "hypertext language, programming");
print_r($claves);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => hypertext
    [1] => language
    [2] => programming
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Dividir un string en sus caracteres constituyentes</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'string';
$caracteres = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($caracteres);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => s
    [1] => t
    [2] => r
    [3] => i
    [4] => n
    [5] => g
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Dividir un string mediante coincidencias y sus índices</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'hypertext language programming';
$caracteres = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($caracteres);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [0] => hypertext
            [1] => 0
        )

    [1] => Array
        (
            [0] => language
            [1] => 10
        )

    [2] => Array
        (
            [0] => programming
            [1] => 19
        )

)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <tip>
   <para>
    Si no necesita la potencia de expresiones regulares, puede optar por
    alternativas más rápidas (no obstante más sencillas) como <function>explode</function>
    o <function>str_split</function>.
   </para>
  </tip>
  <tip>
   <para>
    Si la comparación falla, será devuelto un array con un único elemento que contiene el string de entrada.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="pcre.pattern">Patrones de PCRE</link></member>
    <member><function>preg_quote</function></member>
    <member><function>implode</function></member>
    <member><function>preg_match</function></member>
    <member><function>preg_match_all</function></member>
    <member><function>preg_replace</function></member>
    <member><function>preg_last_error</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
-->