<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.preg-split" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>preg_split</refname>

<refpurpose>Divide una cadena mediante expresión regular</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></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 una cadena mediante expresión regular.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>pattern</parameter></term>

<listitem>

<para>

El patrón a buscar, en forma de cadena.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>subject</parameter></term>

<listitem>

<para>

La cadena de entrada.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>limit</parameter></term>

<listitem>

<para>

Si se especifica, entonces solo se devuelven las primeras sub-cadenas

hasta <parameter>limit</parameter> con el resto de la cadena

colocado en la última sub-cadena.

Un <parameter>limit</parameter> de -1 o 0 significa "sin límite".

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<para>

<parameter>flags</parameter> puede ser la combinación de las

siguientes opciones (combinadas con el operador <literal>|</literal>):

<variablelist>

<varlistentry>

<term><constant>PREG_SPLIT_NO_EMPTY</constant></term>

<listitem>

<simpara>

Si esta opción está activada, solo se devuelven las sub-caenas no vacías

por <function>preg_split</function>.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>PREG_SPLIT_DELIM_CAPTURE</constant></term>

<listitem>

<simpara>

Si esta opción está activada, las expresiones entre paréntesis entre

los delimitadores de patrones también serán capturadas y devueltas.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>PREG_SPLIT_OFFSET_CAPTURE</constant></term>

<listitem>

<para>

Si esta opción está activada, para cada resultado, su posición será devuelta.

Tenga en cuenta que esto cambia el valor devuelto a un array donde cada elemento es un

array compuesto por la cadena encontrada en la posición <literal>0</literal>

y la posición de la cadena en <parameter>subject</parameter> en

la posición <literal>1</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Devuelve un array que contiene las sub-caenas de <parameter>subject</parameter>,

separadas por las cadenas que coinciden con <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 con <function>preg_split</function>: División de una cadena de búsqueda</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

<para>

<example>

<title>Dividir una cadena en caracteres</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

<para>

<example>

<title>Dividir una cadena y capturar las posiciones</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<tip>

<para>

Si no se necesita el poder de las expresiones regulares,

pueden elegirse alternativas más rápidas (aunque más simples)

como <function>explode</function> o <function>str_split</function>.

</para>

</tip>

<tip>

<para>

Si la búsqueda de una coincidencia falla, se devuelve un array que contiene

un solo elemento que contiene la cadena de entrada.

</para>

</tip>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><link linkend="pcre.pattern">Patrones PCRE</link></member>

<member><function>preg_quote</function></member>

<member><function>explode</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>