CKTIS / PHP
Iterator::rewind — voltar ao início de um iterador
Um ciclo `foreach` chama `Iterator::rewind()` antes da primeira verificação com `valid()`. A chamada pode ou não colocar o iterador no início, consoante a implementação.
Versão: PHP 8.3
Sintaxe
public function rewind(): voidIterator::rewind é um método público de instância, sem parâmetros e com o tipo de retorno void. A chamada $it->rewind() coloca o iterador no primeiro elemento, se existir. O método não devolve esse elemento. Ao percorrer o iterador manualmente, verifica valid() antes de leres o valor com current() ou a chave com key(). Se o iterador estiver vazio, valid() devolve false.
Quando um foreach começa a percorrer um objeto que implementa Iterator, o PHP chama rewind() antes da primeira verificação com valid(). Após o corpo do ciclo, se a iteração continuar, next() faz avançar o iterador e valid() verifica a nova posição. O fim do ciclo não desencadeia uma chamada a rewind(). Com ArrayIterator, avançar manualmente antes do ciclo não altera o ponto de partida de um novo ciclo.
Não partas do princípio de que podes voltar a percorrer qualquer iterador. Generator::rewind() executa o gerador até ao primeiro yield, inclusive. Se o gerador já estiver nessa posição, a chamada não faz nada; se a tiver ultrapassado, lança uma Exception. Para iniciar um ciclo na posição atual, envolve o iterador num NoRewindIterator: foreach continua a chamar rewind(), mas este invólucro não encaminha a chamada para o iterador interno.
O método distingue-se de rewind($stream), que reposiciona um fluxo de ficheiro, e de reset($array), que repõe o ponteiro interno de um array.
Exemplos
<?php
$items = new ArrayIterator(['a' => 'alpha', 'b' => 'beta']);
$items->next();
echo $items->current(), "\n";
$items->rewind();
echo $items->current(), "\n";
$items->next();
foreach ($items as $key => $value) {
echo $key, '=', $value, "\n";
}
Resultado
beta alpha a=alpha b=beta
`next()` avança primeiro para `beta`, e a chamada explícita a `rewind()` volta a `alpha`. Outro `next()` avança de novo para `beta`, mas `foreach` começa por `a=alpha` porque chama `rewind()` automaticamente.
Lições relacionadas
- PHP · Lição 61 · Avançado · Versão: 2
- PHP · Lição 63 · Avançado · Versão: 2