How to Return an Iterator in Rust

By the end of this page, you will understand why Iterator itself cannot usually be returned by reference the way a concrete type can, and how Rust handles returning trait-based values. You will learn when to use impl Iterator, when to use trait objects like Box<dyn Iterator<...>>, how lifetimes apply to iterators that borrow data, and why your original function failed.

In Rust, Iterator is a trait, not a concrete type. That distinction is the key to your question.

When you write:

text.split(' ')

Rust creates a concrete iterator type. That concrete type is something like std::str::Split<'a, char>. It implements the Iterator trait.

Trait vs concrete type

A trait describes behavior:

• Iterator says a type can produce items one by one.
• It does not by itself tell Rust how much memory the value needs.

A concrete type describes an actual value in memory:

• Split<'a, char> has a known size.
• Rust can return it directly from a function.

That is why this works conceptually:

fn to_words(text: &str) -> std::str::Split<'_, char> {
    text.split(' ')
}

But in practice, Rust programmers usually write:

Think of a trait like a job description, and a concrete type like an actual worker.

• Iterator = "someone who can hand out items one at a time"
• Split = the specific worker doing that job

If a function says it returns an Iterator, that is like saying:

• "I will send you a worker with these abilities"

But Rust still needs to know how that worker is represented in memory.

There are three common ways to handle that:

1. Return the exact worker type
   • "I return a Split<'a, char>"
2. Return impl Iterator
   • "I return some specific worker that implements Iterator, but I won't tell you which one"
3. Return a boxed trait object
   • "I return any worker that implements Iterator, wrapped in a box"

Your original code tried to return a reference to a temporary worker who disappears as soon as the function ends. That is like handing someone a note saying, "Ask that worker over there," after the worker has already left the building.

Recommended approach: impl Iterator

This is the most common and cleanest solution.

fn main() {
    let text = "word1 word2 word3";
    println!("{}", to_words(text).take(2).count());
}

fn to_words(text: &str) -> impl Iterator<Item = &str> {
    text.split(' ')
}

Why this works

• text.split(' ') returns a concrete iterator type.
• impl Iterator<Item = &str> tells Rust:
  • the function returns some concrete type
  • that type implements Iterator
  • the items are &str

Rust still knows the real type internally, so there is no dynamic dispatch or heap allocation here.

Returning the exact concrete type

Consider this code:

fn to_words(text: &str) -> impl Iterator<Item = &str> {
    text.split(' ')
}

fn main() {
    let text = "word1 word2 word3";
    let count = to_words(text).take(2).count();
    println!("{count}");
}

Step by step

1. text is created

let text = "word1 word2 word3";

text is a string slice, &str.

2. to_words(text) is called

(text)

Returning iterators is useful in many practical situations.

1. Parsing text input

fn lines_without_empty(text: &str) -> impl Iterator<Item = &str> {
    text.lines().filter(|line| !line.trim().is_empty())
}

Used in:

• log parsing
• config file reading
• command output processing

2. Tokenizing user input

fn tokens(input: &str) -> impl Iterator<Item = &str> {
    input.split_whitespace()
}

Used in:

• CLI tools
• search queries
• simple interpreters

3. Processing API or file data lazily

You may not want to allocate a Vec immediately.

fn (line: &)   <Item = &> {
    line.()
}

In real projects, developers often return iterators to keep code efficient and expressive.

Common pattern: hide complex iterator types

fn active_usernames(data: &str) -> impl Iterator<Item = &str> {
    data.lines()
        .filter(|line| !line.is_empty())
        .map(|line| line.trim())
}

The actual return type here is a deeply nested iterator type. impl Iterator keeps the API readable.

Common pattern: validation before iteration

Sometimes developers use a guard clause before building the iterator.

fn words_or_empty(text: &str) -> impl Iterator<Item = &str> {
    text.split_whitespace()
}

Or if different logic is needed, they may return a boxed iterator:

fn choose_iter(text: &str, trim: )  < <Item = &> + > {
     trim {
        ::(text.())
    }  {
        ::(text.())
    }
}

1. Returning a reference to a temporary iterator

Broken code:

fn to_words(text: &str) -> &dyn Iterator<Item = &str> {
    &(text.split(' '))
}

Why it fails

The iterator created by text.split(' ') is temporary and is dropped when the function ends. A reference to it would be invalid.

Fix

Return the iterator by value:

fn to_words(text: &str) -> impl Iterator<Item = &str> {
    text.split(' ')
}

2. Confusing traits with types

Broken idea:

fn make_iter() -> Iterator<Item = i32> {
    0..10
}

Why it fails

Quick rules

• Iterator is a trait, not a concrete type.
• Return iterators by value, not by reference to a temporary.
• Use impl Iterator<Item = T> for most cases.
• Use Box<dyn Iterator<Item = T> + 'a> when different branches return different iterator types.
• If the iterator borrows from input, the returned iterator must carry that lifetime.

Common patterns

Return an iterator borrowing from input

fn words(text: &str) -> impl Iterator<Item = &str> {
    text.split_whitespace()
}

Return exact iterator type

fn words(text: &str) -> std::str::SplitWhitespace<'_> {
    text.split_whitespace()
}

Return boxed trait object

fn words(text: &str)  < <Item = &> + > {
    ::(text.())
}

Why can't I return Iterator directly in Rust?

Because Iterator is a trait, not a concrete sized type. Rust needs either a concrete type, impl Iterator, or a trait object like Box<dyn Iterator<...>>.

Should I use impl Iterator or Box<dyn Iterator>?

Use impl Iterator by default. Use Box<dyn Iterator> when you need to return different concrete iterator types from different branches.

Why did returning &Iterator fail?

You were returning a reference to a temporary iterator created inside the function. That temporary is dropped when the function ends.

Does impl Iterator allocate memory on the heap?

No. impl Iterator uses static dispatch and does not require heap allocation by itself.

What lifetime does the returned iterator have?

If the iterator borrows from text, its lifetime is tied to text. Rust usually infers this automatically.

Is split(' ') the same as ?

• Traits — Iterator is a trait, so understanding traits is essential to understanding this return-type problem.
• impl Trait — this is the most common way to return an iterator without exposing its exact type.
• Trait objects — dyn Trait is the dynamic-dispatch alternative when one concrete type is not enough.
• Lifetimes — returned iterators often borrow from input data, so lifetimes determine how long they can be used.
• Borrowing and references — your original code failed partly because it tried to return a reference to a temporary value.
• Static vs dynamic dispatch — this explains the difference between impl Iterator and Box<dyn Iterator>.
• Iterator adaptors — methods like map, filter, take, and count are central to how iterators are used.
• Owned vs borrowed data — sometimes you return &str items, and other times you must return owned String values.