Escribe tu propio iterador: impl Iterator con next

Hasta ahora has consumido iteradores; ahora vas a fabricarlos. Y aquí aguarda una de las lecciones de diseño más limpias de Rust: para que tu propio tipo se integre en todo el universo de map, filter, zip, collect y compañía, solo debes implementar un método. Iterator es un trait con un único requisito obligatorio, next, y todo lo demás son cortesías por defecto construidas encima. Escribe seis líneas y tu tipo hablará el idioma de toda la biblioteca estándar.

El contrato mínimo: type Item y next

Iterator es un trait con un solo método obligatorio. Todo lo demás —map, filter, collect, sum, los setenta y tantos adaptadores y consumidores— tiene implementación por defecto construida sobre él. El contrato es:

pub trait Iterator {
    type Item;                                 // que tipo produce
    fn next(&mut self) -> Option<Self::Item>;  // el siguiente, o None si se acabo
    // ...decenas de metodos con cuerpo por defecto
}

type Item es un tipo asociado: fija de una vez qué produce este iterador. next es el motor: cada llamada avanza el estado interno y devuelve Some(valor), o None cuando no queda nada. Que devuelva Option es lo que codifica “puede que haya, puede que no” sin un centinela mágico ni una excepción.

Un iterador de verdad

Construyamos uno que genere la sucesión de Fibonacci. El estado —los dos últimos términos— vive en el struct; next lo hace avanzar en cada paso.

struct Fibonacci {
    actual: u64,
    siguiente: u64,
}

impl Iterator for Fibonacci {
    type Item = u64;

    fn next(&mut self) -> Option<u64> {
        let emitido = self.actual;
        self.actual = self.siguiente;
        self.siguiente = emitido + self.siguiente;
        Some(emitido) // nunca se agota: es infinito
    }
}

fn fib() -> Fibonacci {
    Fibonacci { actual: 0, siguiente: 1 }
}

Este iterador es infinito: su next jamás devuelve None. No pasa nada: la pereza permite iteradores sin fin siempre que un adaptador como take los recorte. Y en cuanto existe next, todo el vocabulario del trait está disponible sin escribir una línea más:

let primeros: Vec<u64> = fib().take(10).collect();
assert_eq!(primeros, [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]);

let pares: Vec<u64> = fib().filter(|n| n % 2 == 0).take(4).collect();
assert_eq!(pares, [0, 2, 8, 34]);

Todo gratis por encima de next, e IntoIterator

La lección de diseño es contundente: implementas un método y recibes decenas. map, filter, take, zip, sum, fold, collect… todos llaman a next por debajo. Puedes redefinir alguno —size_hint para pre-reservar memoria, o nth para saltar sin recorrer— cuando conoces un atajo, pero nunca es obligatorio.

Conviene no confundir dos traits vecinos. Iterator es algo que produce elementos con next. IntoIterator es algo que puede convertirse en un iterador con into_iter; es lo que habilita a un tipo a usarse directamente en un bucle for. Un Vec no es un Iterator, pero sí es IntoIterator; por eso for x in vec funciona, mientras que for x in vec.iter() recorre el iterador que iter devuelve.

struct Cuenta {
    fin: u32,
    i: u32,
}

impl Iterator for Cuenta {
    type Item = u32;
    fn next(&mut self) -> Option<u32> {
        if self.i < self.fin {
            self.i += 1;
            Some(self.i)
        } else {
            None // aqui si se agota
        }
    }
}

fn main() {
    // Como Cuenta ya es Iterator, sum vino gratis con el contrato
    let total: u32 = Cuenta { fin: 5, i: 0 }.sum();
    assert_eq!(total, 15); // 1 + 2 + 3 + 4 + 5
}

flowchart LR
call[Alguien llama a next] --> est[Lee y avanza el estado interno]
est --> hay[Queda algo devuelve Some del valor]
est --> no[Se agoto devuelve None]
hay --> call
style call fill:#cba6f7,color:#11111b
style hay fill:#a6e3a1,color:#11111b
style no fill:#f38ba8,color:#11111b