diff --git a/src/lib.rs b/src/lib.rs index d69a23e..3e43163 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,12 +1,44 @@ #![no_std] #![warn(missing_docs)] -//! This crate provides the [`accumulate()`](IterAccumulate::accumulate) iterator adaptor. +//! This crate provides [`accumulate()`], an iterator adaptor that accumulates the elements from the +//! base iterator using the provided closure. +//! +//! [`accumulate()`] is similar to [`fold()`], but instead of returning the final accumulated +//! result, it returns an iterator that yields the current accumulated value for each iteration. +//! In other words, the last element yielded by [`accumulate()`] is what would have been returned +//! by [`fold()`] if it was used instead. +//! +//! The returned iterator is **not** fused and it is not specified what happens when the base +//! iterator returns [`None`]. +//! If you want a fused iterator, use [`fuse()`]. +//! +//! # Examples +//! +//! ``` +//! use iter_accumulate::IterAccumulate; +//! +//! let input = [1, 2, 3, 4, 5]; +//! let mut iter = input.iter().accumulate(1, |acc, i| acc * i); +//! +//! assert_eq!(iter.next(), Some(1)); +//! assert_eq!(iter.next(), Some(2)); +//! assert_eq!(iter.next(), Some(6)); +//! assert_eq!(iter.next(), Some(24)); +//! assert_eq!(iter.next(), Some(120)); +//! assert_eq!(iter.next(), None); +//! ``` +//! +//! [`accumulate()`]: IterAccumulate::accumulate +//! [`fold()`]: Iterator::fold +//! [`fuse()`]: Iterator::fuse + +use core::fmt; /// An iterator adaptor that accumulates the elements from the base iterator using the provided /// closure. /// -/// See [`IterAccumulate::accumulate()`] for more information. +/// See the [crate-level documentation](crate) for more information. #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] #[derive(Clone)] pub struct Accumulate { @@ -70,33 +102,7 @@ pub trait IterAccumulate: Iterator { /// Creates an iterator adaptor that accumulates the elements from the base iterator using the /// provided closure. /// - /// `accumulate()` is similar to [`fold()`], but instead of returning the final accumulated - /// result, it returns an iterator that yields the current accumulated value for each iteration. - /// In other words, the last element yielded by `accumulate()` is what would have been returned - /// by [`fold()`] if it was used instead. - /// - /// The returned iterator is **not** fused and it is not specified what happens when the base - /// iterator returns [`None`]. - /// If you want a fused iterator, use [`fuse()`]. - /// - /// # Examples - /// - /// ``` - /// use iter_accumulate::IterAccumulate; - /// - /// let input = [1, 2, 3, 4, 5]; - /// let mut iter = input.iter().accumulate(1, |acc, i| acc * i); - /// - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), Some(6)); - /// assert_eq!(iter.next(), Some(24)); - /// assert_eq!(iter.next(), Some(120)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// [`fold()`]: Iterator::fold - /// [`fuse()`]: Iterator::fuse + /// See the [crate-level documentation](crate) for more information. #[inline] fn accumulate(self, init: B, f: F) -> Accumulate where