skip to content

In Rust, why return `impl Iterator<Item = &i32>` from a function that filters a borrowed slice, and what may the caller do with it?

level: juniorimportance: must knowfreq 62%

answer

  1. a closure's type has no name
  2. adapter chain as the real type
  3. opaque to the caller
  4. only the bound's methods

basics

~20 s

The real type is a Filter adapter holding a closure, whose type cannot be written. Returning impl Iterator hands it back unboxed and lazy; the caller sees an opaque type and may use only Iterator's methods.

solid answer

~40 s

`readings.iter().filter(...)` has the type `Filter<slice::Iter<'_, i32>, C>`, where `C` is a closure type that cannot be named in source. Writing `-> impl Iterator<Item = &i32>` lets the body choose that type while the signature promises only `Iterator`. The value is returned by value with no allocation, calls are statically dispatched, and nothing is filtered until the caller pulls items. The caller gets an opaque type: it can call `next`, `count`, `take`, `collect` and every other `Iterator` method, but `len()` fails with E0599 and annotating the concrete `Filter` type fails with E0308. Because the items are `&i32`, the iterator keeps the slice borrowed while it lives.

code

rust · 12 lines
rust
fn above(readings: &[i32], limit: i32) -> impl Iterator<Item = &i32> {
    readings.iter().filter(move |r| **r > limit)
}

fn main() {
    let readings = vec![12, 48, 7, 51, 30];
    let hot = above(&readings, 25);
    let total: i32 = hot.sum();
    println!("total above 25: {total}");
    let first_two: Vec<&i32> = above(&readings, 25).take(2).collect();
    println!("{first_two:?}");
}

go deeper

for a junior

Recall that closures and adapter chains have types you cannot write, and that impl Iterator returns them without boxing. Know that the caller only gets Iterator's methods.

for a middle

Explain the opaque type: one concrete type chosen by the body, invisible to callers, statically dispatched, lazy. Show the E0599 a caller gets for a method outside the bound.

for a senior

Choose between impl Iterator, Vec and a boxed iterator by cost and by what callers need, such as len, several passes or a type picked at run time.

for a principal

Treat an opaque return type as an API promise: the bound is all callers may rely on, so a narrow bound keeps the body free to change without a breaking release.

## The type you cannot write A function that filters a borrowed slice builds a chain of iterator **adapters**. `readings.iter()` produces a `std::slice::Iter<'_, i32>`, and `.filter(move |r| **r > limit)` wraps it in a `std::iter::Filter<std::slice::Iter<'_, i32>, C>`, where `C` is the type of the closure. Every closure in Rust has its own **unique, anonymous type** that has no name in source code, so `C` cannot be written in a signature. Before `impl Trait` existed, the usual ways out were a heap-allocated trait object or a hand-written iterator struct. `impl Iterator<Item = &i32>` in **return position** solves this. The function body decides the concrete type, the compiler records it, and the signature promises only that the value implements `Iterator` with `&i32` items. ```rust fn above(readings: &[i32], limit: i32) -> impl Iterator<Item = &i32> { readings.iter().filter(move |r| **r > limit) } ``` ## What the caller receives The caller gets an **opaque type**: a real, fixed, sized type that the compiler knows but that the caller is not allowed to depend on. In practice that means: - the caller may call any method of `Iterator` (and of its supertraits, if any): `next`, `count`, `sum`, `take`, `collect` and the rest; - methods of traits that are not in the bound are invisible, even when the hidden `Filter` type might have them; rustc reports **E0599**, "no method named `len` found for opaque type `impl Iterator<Item = &i32>`"; - annotating a variable with the concrete `Filter<…>` type fails with **E0308** ("expected `Filter<…>`, found opaque type"); - the author can later change the body to a different iterator chain without breaking callers, as long as it still satisfies the bound. Because the item type `&i32` borrows from `readings`, the returned iterator keeps the slice borrowed until the caller is done with it. ## What it costs For `above`, the opaque type is resolved at compile time. The value is returned **by value**, with the size of the hidden concrete type, and calls on it are statically dispatched and can be inlined. Nothing is allocated and nothing is computed until the caller pulls items, because iterator adapters are lazy. | Return type | Allocation | Dispatch | Work done before the caller iterates | |---|---|---|---| | `impl Iterator<Item = &i32>` | none | static | none (lazy) | | `Vec<&i32>` | one buffer | static | every element filtered and stored | | `Box<dyn Iterator<Item = &i32> + '_>` | one box | dynamic, through a vtable | none (lazy) | Laziness matters in practice. A caller that writes `above(&readings, 25).next()` to find the first hot reading runs the filter closure only until one element passes; a function that collected into a `Vec` first would have scanned and stored every match. A caller that wants a count, a sum or a vector can still get one, by calling `count`, `sum` or `collect` on the returned iterator, so returning the iterator gives up nothing a `Vec` return would have offered except random access and a known length. A `Vec` is still the right return type when the caller needs `len`, indexing or several passes; a boxed trait object is still needed when the function must return different iterator types chosen at run time. ## Where `impl Trait` may appear `impl Trait` is accepted only in the **parameter and return types of functions and methods** (including trait methods). rustc rejects it elsewhere with **E0562**: 1. as the type of a `let` binding: "`impl Trait` is not allowed in the type of variable bindings"; 2. as a struct field type: "`impl Trait` is not allowed in field types"; 3. inside a type alias on stable Rust. To store the returned iterator in a struct, make the struct generic over `I: Iterator<Item = …>` and let inference fill `I`, or box it. ## Mistakes worth avoiding - Thinking `impl Iterator` boxes the value: it does not; that is what `Box<dyn Iterator>` does. - Thinking the caller can rely on the hidden type: only the declared bound is usable. - Collecting into a `Vec` "to be safe": it costs an allocation and an eager pass that a caller who only wants the first match never needed. - Forgetting that the result borrows the input slice: the caller cannot mutate the source `Vec` while the iterator is alive.

  • In Rust, can a struct field hold the iterator that `above` returns?
    Not by writing `impl Iterator` as the field type: rustc rejects that with E0562, "`impl Trait` is not allowed in field types". Make the struct generic, `struct Report<I: Iterator<Item = u32>> { rows: I }`, and let inference choose `I` when it is built from the returned value, or store a `Box<dyn Iterator<Item = u32>>` and accept one allocation and dynamic dispatch.
  • In Rust, why can the caller not push to the source `Vec` while the returned iterator is alive?
    The item type `&i32` borrows from the `readings` slice, so the opaque return type carries that borrow. While the iterator is still used, `readings` is borrowed immutably, and a `push` needs a mutable borrow, which the borrow checker rejects with E0502. Finish iterating, or collect the results, before mutating the vector.

  • impl Iterator allocates the iterator on the heap like a Box
  • The caller can call len() or index into the returned iterator
  • impl Iterator lets the function pick a different iterator type on each call
  • Returning an iterator filters every element before the function returns
  • The caller may annotate the result with its concrete Filter type