preg_split

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_split — Divide uma string com base em expressão regular

Descrição

preg_split(
    string $pattern,
    string $subject,
    int $limit = -1,
    int $flags = 0
): array|false

Divide a string informada com base em uma expressão regular.

Parâmetros

pattern

A expressão a ser pesquisada, como uma string.

subject

A string de entrada.

limit

Se especificado, somente substrings de até limit bytes são retornadas com o resto da string sendo colocado na última substring. Um valor de -1 ou 0 em limit significa "sem limite".

flags

flags pode ser qualquer combinação das seguintes opções (combinadas com o operador binário |):

PREG_SPLIT_NO_EMPTY
Se esta opção for definida, somente partes não vazias serão retornadas por preg_split().
PREG_SPLIT_DELIM_CAPTURE
Se esta opção for definida, expressões entre parênteses na expressão serão capturadas e também retornadas.
PREG_SPLIT_OFFSET_CAPTURE

Se esta opção for definida, para cada correspondência que ocorrer, a sua posição na string de entrada também será retornada. Observe que isto altera o valor de retorno para um array onde cada elemento é um array consistindo da string correspondida no índice 0 e seu deslocamento na string de entrada (subject) no índice 1.

Valor Retornado

Retorna um array contendo substrings de subject divididas ao longo de limites correspondidos por pattern, ou false em caso de falha.

Erros/Exceções

Se o padrão de expressão regular passado não for compilado para uma expressão regular válida, um E_WARNING será emitido.

Exemplos

Example #1 Exemplo de preg_split(): Obter partes de uma string de pesquisa

<?php
// divide a frase por qualquer número de vírgulas ou caracteres representativos de espaço,
// que incluem " ", \r, \t, \n e \f
$keywords = preg_split("/[\s,]+/", "hypertext language, programming");
print_r($keywords);
?>

O exemplo acima produzirá:

Array
(
    [0] => hypertext
    [1] => language
    [2] => programming
)

Example #2 Dividindo uma string em seus caracteres componentes

<?php
$str = 'string';
$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($chars);
?>

O exemplo acima produzirá:

Array
(
    [0] => s
    [1] => t
    [2] => r
    [3] => i
    [4] => n
    [5] => g
)

Example #3 Dividindo uma string em correspondências e suas posições

<?php
$str = 'hypertext language programming';
$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($chars);
?>

O exemplo acima produzirá:

Array
(
    [0] => Array
        (
            [0] => hypertext
            [1] => 0
        )

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

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

)

Notas

Tip

Se o poder das expressões regulares não for necessário, pode-se optar por alternativas mais rápidas (e simples) como explode() ou str_split().

Tip

Se a correspondência falhar, um array com um único elemento contendo a string de entrada será retornado.

Veja Também