Crate output_iter 

A utility for creating iterators that, in addition to yielding items, can perform a computation during iteration and return the result of that computation as soon as it is available.

Motivation

The OutputIterator is useful for scenarios where the result of a computation depends on iterated data and is not immediately available.

Without OutputIterator, you would rely on one of the following approaches:

• Calculate everything in advance: Collect the iterator into a Vec, perform the computation, and then return the result along with an iterator over the vector. This approach is inefficient as it requires unnecessary memory allocations.
• Introduce a “finishing” method: Add a method to the iterator to compute and return the result. However, this approach limits flexibility; for example, you couldn’t map the items of such an iterator since there is no such method on std::iter::Map.

---

Example

Here’s how you can use an OutputIterator to iterate over numbers, compute their sum, and retrieve the result as soon as the sum exceeds a certain threshold:

use output_iter::{OutputIterator, OutputIteratorVariant};

struct SumIterator {
    items: Vec<i32>,
    sum: i32,
    threshold: i32,
}

impl OutputIterator for SumIterator {
    type Item = i32;
    type Output = i32; // The computed sum
    type AfterOutput = std::vec::IntoIter<i32>;

    fn next(mut self) -> OutputIteratorVariant<Self> {
        use OutputIteratorVariant::*;
        
        if let Some(item) = self.items.pop() {
            self.sum += item;
            if self.sum >= self.threshold {
                Output(self.items.into_iter(), self.sum)
            } else {
                Next(self, item)
            }
        } else {
            Output(self.items.into_iter(), self.sum)
        }
    }
}

let iter = SumIterator {
    items: vec![1, 2, 3, 4, 5],
    sum: 0,
    threshold: 10,
};

let (remaining, result) = iter.until_output_iter(|before_iter| {
    for item in before_iter {
        println!("Processing item: {}", item);
    }
});

println!("Sum reached: {}", result);

for item in remaining {
    println!("Remaining item: {}", item);
}

Output

Processing item: 5
Processing item: 4
Processing item: 3
Sum reached: 12
Remaining item: 2
Remaining item: 1

Structs

Filter

An adapter for filtering items in an OutputIterator. This is created by the filter method on OutputIterator. See its documentation for more.

IgnoreOutput

An iterator that ignores the intermediate output of an OutputIterator.

ImmediateOutput

An OutputIterator that immediately produces its output without yielding any intermediate items.

InBetween

IntoIter

A standard iterator for OutputIterator, wrapping a mutable reference to the output. Upon completion, output buffer will be overridden with the output of the iterator.

IntoIterOption

An iterator for OutputIterator, wrapping a mutable reference to the output. At the beginning overrides buffer with None. Upon completion, output buffer will be Some with the output of the iterator. If upon completion output is None, then thread has panicked during one of the previous calls to the next.

Map

An adapter for mapping items in an OutputIterator.

MapOutput

An OutputIterator that transforms the intermediate output using a provided function.

UntilOutput

An iterator used for OutputIterator::until_output_iter

Enums

IterVariant

Represents the internal state of an iterator over the OutputIterator. Used in various iterators of this crate.

OutputIteratorVariant

Represents the possible states of an OutputIterator.

Traits

OutputIterator

A trait representing an Iterator with an intermediate output phase.

Functions

immediate_output

Produce an OutputIterator that immediately produces its output without yielding any intermediate items. Next call to next will return an OutputIteratorVariant::Output(iter, output).

in_between

An OutputIterator that first iterates over a before iterator, then outputs a value, and finally iterates over an after iterator.