Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / PHP

SplFixedArray::offsetGet — ler um elemento pelo índice

Lê uma posição com `offsetGet()` ou `[]` e distingue um valor `null` de um índice fora do intervalo ou de um tipo de índice não suportado.

Versão: PHP 8.3

Sintaxe

$value = $array->offsetGet($index);
$value = $array[$index];

SplFixedArray::offsetGet é um método de instância que devolve o valor no índice pedido. O tipo devolvido é mixed: o valor mantém o tipo com que foi guardado. Graças a ArrayAccess, uma leitura simples com $array[$index] dá o mesmo resultado que $array->offsetGet($index). A classe faz parte da SPL, que está integrada no PHP 8.3 e não pode ser desativada. Num espaço de nomes, usa \SplFixedArray ou importa SplFixedArray.

Os índices começam em zero e têm de satisfazer 0 <= $index && $index < $array->getSize(). Ler uma posição válida à qual nunca foi atribuído um valor devolve null. Ler um null guardado explicitamente dá o mesmo resultado. O valor devolvido, por si só, não permite distinguir os dois casos.

Em PHP 8.3, um índice inteiro fora do intervalo lança RuntimeException; um tipo de índice não suportado, como o da cadeia 'name', lança TypeError. A partir de PHP 8.4, o erro de limites é OutOfBoundsException, uma subclasse de RuntimeException. Antes de PHP 8.1, as chaves não suportadas lançavam RuntimeException. Valida o tipo e o intervalo dos índices provenientes de dados externos, em vez de depender da conversão implícita: por exemplo, uma leitura com [] pode tratar a cadeia '0' como o índice 0.

O método não devolve uma referência à posição. Para alterar um array PHP aninhado, lê-o para uma variável, modifica-o e volta a guardá-lo com $array[$index] = $value ou $array->offsetSet($index, $value).

Exemplos

<?php
$array = new \SplFixedArray(2);
$array[0] = 42;

var_dump($array->offsetGet(0));
var_dump($array[0]);
var_dump($array->offsetGet(1));

foreach ([2, 'name'] as $index) {
    try {
        $array->offsetGet($index);
    } catch (\RuntimeException | \TypeError $error) {
        echo get_class($error), "\n";
    }
}

Resultado

int(42)
int(42)
NULL
RuntimeException
TypeError

As duas formas de leitura devolvem `int(42)`. A posição sem valor atribuído devolve `NULL`, e as duas últimas linhas mostram as classes de exceção esperadas em PHP 8.3.

Lições relacionadas

  • PHP · Lição 66 · Avançado · Versão: 2

Fontes