O Modelo de Iterador em Rust

Todas as coleções na biblioteca padrão de Rust - Vec, HashMap, arrays, slices - expõem seus elementos através da mesma pequena interface: um tipo que sabe como produzir "o próximo item" até que acabe. Essa interface, o trait Iterator, é o fio que une loops for, cadeias map/filter e a maior parte do código com sabor funcional que você escreverá em Rust. Entendê-lo como um modelo, em vez de um conjunto de métodos para memorizar, faz com que o restante das páginas desta seção - o próprio trait, adaptadores, consumo e IntoIterator - se encaixem como variações de uma única ideia.

Esta página é a âncora conceitual para a seção. Ela não percorre as APIs de coleção como Noções Básicas de Coleções faz; em vez disso, explica por que os iteradores são preguiçosos, como a propriedade decide qual de iter, iter_mut ou into_iter você deve usar, e o que o compilador realmente está fazendo quando transforma uma cadeia de adaptadores em código de máquina.

Resumo

• Um iterador é qualquer tipo que implementa Iterator, o que se resume a um método, next, que retorna Some(item) ou None; todo o resto no ecossistema é construído sobre essa única operação.
• Por que Importa: Rust precisa de um vocabulário compartilhado para "uma sequência de valores pela qual posso percorrer", e iteradores permitem que coleções, geradores de valores computados e leitores de I/O falem a mesma língua sem alocar buffers extras ou sacrificar desempenho.
• Conceitos Chave: preguiça, adaptadores vs consumidores, modos de propriedade (iter, iter_mut, into_iter), abstração de custo zero, IntoIterator.
• Quando Usar: Transformar ou filtrar uma sequência sem índices escritos manualmente; escrever código genérico sobre "qualquer coisa iterável"; construir tipos de sequência personalizados; escolher se um loop deve emprestar, mutar ou consumir sua origem.
• Limitações / Trade-offs: Cadeias são de passagem única e se consomem; alguns padrões (olhar para trás com janelas, acesso a índice e vizinho) são genuinamente mais desajeitados com adaptadores do que com um loop indexado simples.
• Tópicos Relacionados: closures e traits Fn, propriedade e empréstimo, genéricos e limites de trait, slices.

Fundamentos

Em sua essência, Iterator é um trait com um método obrigatório:

trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

Todo o resto - map, filter, take, sum, collect - são métodos padrão construídos sobre chamadas repetidas a next. Um tipo se torna um iterador implementando este único método; os outros aproximadamente setenta métodos do trait vêm de graça.

A propriedade mais importante deste modelo é a preguiça. Escrever (0..10).filter(|n| n % 2 == 0).map(|n| n * 2) não itera sobre dez números. Ele constrói uma pequena struct aninhada - um Filter envolvendo um Map envolvendo um Range - e não faz nenhum trabalho. Nada acontece até que você chame algo que peça repetidamente por next, como um loop for, .collect() ou .sum(). O compilador Rust até anexa #[must_use] aos adaptadores de iterador especificamente para que uma cadeia não utilizada produza um aviso em vez de silenciosamente não fazer nada.

Ajuda separar o vocabulário em duas famílias. Adaptadores (map, filter, zip, enumerate, take, skip, flat_map) envolvem um iterador em outro iterador, transformando o que next eventualmente produzirá. Consumidores (collect, sum, fold, count, for_each, e o consumo implícito dentro de um loop for) são os métodos que realmente chamam next em um loop e produzem um valor final, não iterador. Uma cadeia de adaptadores sem um consumidor no final é inerte - é uma receita, não um resultado.

Mecânicas e Interações

As três maneiras de transformar uma coleção em um iterador - iter(), iter_mut(), into_iter() - não são três métodos não relacionados para memorizar. São a mesma ideia subjacente, "me dê um iterador sobre os elementos desta coleção", expressa através dos três modos de propriedade de Rust.

  collection.iter()       -> Iterator<Item = &T>       (empréstimo compartilhado)
  collection.iter_mut()   -> Iterator<Item = &mut T>    (empréstimo exclusivo)
  collection.into_iter()  -> Iterator<Item = T>          (propriedade, consome a coleção)

iter() percorre a coleção por referência compartilhada, deixando-a utilizável depois. iter_mut() a percorre por referência exclusiva, permitindo que você mutate elementos no local - e, como com qualquer empréstimo &mut, o verificador de empréstimo garante que nenhum outro código possa aliasar a coleção enquanto você o faz. into_iter() move a própria coleção para o iterador, entregando valores de propriedade e deixando o binding original inutilizável. Um simples for x in some_vec descompila para some_vec.into_iter(), que é exatamente por que iterar um Vec por valor dentro de um loop for o move; escrever for x in &some_vec em vez disso chama a implementação IntoIterator em &Vec<T>, que internamente delega para iter().

É o trait IntoIterator fazendo seu trabalho: é o trait que faz os loops for funcionarem, e qualquer tipo que o implementa pode ser inserido em um loop for ou aceito por uma função genérica limitada com impl IntoIterator<Item = T>. O próprio Iterator implementa IntoIterator (retornando a si mesmo), que é por que um loop for aceita alegremente tanto um iterador fresco quanto uma coleção.

A frase "abstração de custo zero", aplicada a cadeias de iteradores, tem um significado específico e verificável: não significa que os adaptadores são gratuitos para raciocinar, apenas que a saída compilada não tem um custo de tempo de execução por usá-los. Cada map/filter/take em uma cadeia é uma struct genérica distinta, monomorfizada por tipo de closure no tempo de compilação. O LLVM então embuti toda a estrutura aninhada e, na maioria dos casos, a funde em um loop indistinguível de um que você teria escrito à mão com índices. Esta é uma propriedade real e mensurável, não linguagem de marketing - mas depende do compilador ser capaz de ver através de toda a cadeia, o que geralmente se mantém para código de linha reta e pode falhar em dispatch dinâmico (Box<dyn Iterator>) ou ramificações imprevisíveis.

// Tipos de adaptadores aninhados são visíveis se você tentar nomeá-los:
fn evens_doubled(v: &[i32]) -> std::iter::Map<std::iter::Filter<std::slice::Iter<i32>, fn(&&i32) -> bool>, fn(&i32) -> i32> {
    // Código real usa `impl Iterator<Item = i32>` aqui em vez disso - o tipo concreto
    // é impossível de nomear na prática, que é *por que* `impl Trait` existe.
    unimplemented!()
}

O trecho acima é deliberadamente impraticável: ele mostra que uma cadeia de dois passos já tem um tipo muito desajeitado para escrever, que é precisamente a pressão que levou aos tipos de retorno impl Trait para funções que produzem iteradores.

Considerações Avançadas e Aplicações

Como as cadeias são preguiçosas e de passagem única, algumas decisões estruturais recorrem constantemente assim que o código fica mais complexo.

A ordem dos adaptadores importa tanto para a correção quanto para o custo: filter antes de map pula o trabalho de transformação para elementos descartados, enquanto map antes de filter faz a transformação incondicionalmente. filter_map colapsa um filtro-depois-transformação em uma única passagem, evitando uma alocação intermediária que filter().map() não precisa realmente, mas que um pipeline collect()-depois-iter() ingênuo introduziria.

Consumir um iterador é permanente. Uma vez que next retornou None (ou uma vez que você entregou o iterador para collect), o valor está esgotado; não há "rebobinamento". Código que precisa percorrer os mesmos dados duas vezes deve primeiro collect() em uma coleção de propriedade e iterá-la duas vezes, ou reestruturar para evitar a segunda passagem - não há maneira gratuita de "reproduzir" uma cadeia preguiçosa.

Em código assíncrono, o modelo de iterador tem um irmão em vez de uma extensão: Stream (do ecossistema futures, e cada vez mais tokio) espelha a preguiça e o vocabulário de adaptadores do Iterator, mas produz itens através de pontos .await em vez de síncronamente. Os dois são conceitualmente da mesma forma - "puxar o próximo item sob demanda" - mas são traits diferentes com consumidores diferentes, então adaptadores de iterador e adaptadores de stream não se misturam sem uma conversão explícita.

Iteradores personalizados também são como Rust modela sequências "infinitas" ou geradas com segurança: uma struct Counter implementando Iterator sem um fim natural é completamente válida, porque a preguiça significa que nada é executado até que algo a limite. Essa também é a armadilha - coletar um iterador ilimitado sem um take(n) primeiro irá travar ou esgotar a memória, pois collect não tem como saber que a sequência é ilimitada até que pare de receber None.

Concepções Errôneas Comuns

• "Iteradores são apenas uma sintaxe mais agradável para loops" - A sintaxe é mais agradável, mas o ponto mais profundo é que uma cadeia é um valor (uma struct inerte) antes de ser uma computação; nada é executado até que um consumidor a acione, o que é fácil de perder vindo de linguagens onde as operações de lista são executadas ansiosamente.
• "iter() e into_iter() são intercambiáveis" - Eles diferem no que nos entregam (&T vs T) e se a coleção de origem sobrevive depois; escolher o errado é o erro de compilação mais comum relacionado a iteradores para iniciantes.
• "Custo zero significa que escrever a cadeia não tem custo" - Significa que o programa compilado não tem custo de tempo de execução extra em comparação com um loop escrito à mão; ler e raciocinar sobre uma cadeia de cinco adaptadores ainda tem um custo cognitivo real, e dispatch dinâmico pesado (Box<dyn Iterator>) pode reintroduzir sobrecarga de tempo de execução.
• "map/filter alocam uma coleção intermediária a cada passo" - Eles não o fazem; cada adaptador apenas envolve o iterador anterior em uma struct, e nenhum buffer existe até que um consumidor como collect realmente aloque um.
• "Uma cadeia de iteradores pode ser iterada mais de uma vez" - Uma vez consumido, um iterador está esgotado; reutilizar a mesma cadeia para uma segunda passagem produz silenciosamente um iterador que retorna imediatamente None, não uma nova execução.

FAQs

Relacionados

• Noções Básicas de Coleções - o companheiro prático desta página, para escolher entre Vec, HashMap, BTreeMap e similares.
• O Trait Iterator - as mecânicas de implementar Iterator você mesmo, incluindo size_hint e FusedIterator.
• Adaptadores de Iterador - um tour prático de map, filter, zip, flat_map e ordenação de cadeia.
• IntoIterator & Propriedade vs. Empréstimo - um olhar mais profundo e baseado em receitas sobre iter/iter_mut/into_iter.
• Padrões de Closure + Iterador em Rust - como closures capturados dentro de adaptadores interagem com a propriedade.
• Iteradores Falíveis & collect() - coletando em Result<Vec<T>, E> e curto-circuitando em caso de erro.

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024). Ela é conceitual e não está vinculada a uma versão específica de crate além da biblioteca padrão.