array_splice

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

    array_splice — Remove uma parte array e a substitui por outra coisa

    Descrição

    array_splice(
        array&$array,
        int$offset,
        ?int$length = null,
        mixed$replacement = []
    ): array

    Remove os elementos especificados por offset e length do array array, e os substitui com os elementos do array replacement, se for especificado.

    Nota:

    Chaves numéricas em array não são preservadas.

    Nota: Se replacement não for um array, ele será convertido para um array (i.e. (array) $replacement). Isso pode resultar em um comportamento inesperado ao usar um objeto ou replacementnull.

    Parâmetros

    array

    O array de entrada.

    offset

    Se offset for positivo então o começo da região removida será nesse deslocamento a partir do início do array array.

    Se offset for negativo então o começo da região removida será nesse deslocamento a partir do final do array array.

    length

    Se length for omitido, remove tudo a partir de offset até o final do array.

    Se length for especificado e for positivo, então essa quantidade de elementos será removida.

    Se length for especificado e for negativo, então o final da região removida será essa quantidade de elementos a partir do final do array.

    Se length for especificado e for zero, nenhum elemento será removido.

    Dica

    Para remover tudo a partir de offset até o final do array quando replacement também é especificado, use count($input) para length.

    replacement

    Se o array replacement for especificado, então os elementos removidos serão substituidos pelo elementos desse array.

    Se offset e length são tais que nada é removido, então os elementos do array replacement serão inseridos no lugar especificado pelo offset.

    Nota:

    Chaves em replacement não são preservadas.

    Se replacement for de apenas um elemento então não é necessário colocar array() ou colchetes ao redor dele, a não ser que elementos seja um array em si, um objeto ou null.

    Valor Retornado

    Retorna um array que consiste nos elementos extraídos.

    Registro de Alterações

    VersãoDescrição
    8.0.0length agora é anulável.

    Exemplos

    Exemplo #1 Exemplos da array_splice()

    <?php
    $input     = array("vermelho", "verde", "azul", "amarelo");
    array_splice($input, 2);
    var_dump($input);

    $input = array("vermelho", "verde", "azul", "amarelo");
    array_splice($input, 1, -1);
    var_dump($input);

    $input = array("vermelho", "verde", "azul", "amarelo");
    array_splice($input, 1, count($input), "laranja");
    var_dump($input);

    $input = array("vermelho", "verde", "azul", "amarelo");
    array_splice($input, -1, 1, array("preto", "marrom"));
    var_dump($input);
    ?>

    O exemplo acima produzirá:

    array(2) { [0]=> string(3) "vermelho" [1]=> string(5) "verde" } array(2) { [0]=> string(3) "vermelho" [1]=> string(6) "amarelo" } array(2) { [0]=> string(3) "vermelho" [1]=> string(6) "laranja" } array(5) { [0]=> string(3) "vermelho" [1]=> string(5) "verde" [2]=> string(4) "azul" [3]=> string(5) "preto" [4]=> string(6) "marrom" }

    Exemplo #2 Declarações equivalentes a vários exemplos da array_splice()

    As seguintes declarações são equivalentes:

    <?php

    // adiciona dois elementos a $input
    array_push($input, $x, $y);
    array_splice($input, count($input), 0, array($x, $y));

    // remove o último elemento de $input
    array_pop($input);
    array_splice($input, -1);

    // remove o primeiro elemento de $input
    array_shift($input);
    array_splice($input, 0, 1);

    // insere um elemento no início de $input
    array_unshift($input, $x, $y);
    array_splice($input, 0, 0, array($x, $y));

    // substitui o valor em $input no índice $x
    $input[$x] = $y; // para arrays onde a chave é igual ao deslocamento
    array_splice($input, $x, 1, $y);

    ?>

    Veja Também

    To Top