Add itertools::note_position.

src/lib.rs

@@ -75,6 +75,7 @@ pub mod structs {
     pub use sources::{RepeatCall, Unfold, Iterate};
     pub use tee::Tee;
     pub use tuple_impl::{TupleBuffer, TupleWindows, Tuples};
+    pub use with_position::WithPosition;
     pub use zip_eq_impl::ZipEq;
     pub use zip_longest::ZipLongest;
     pub use ziptuple::Zip;
@@ -86,6 +87,7 @@ pub use diff::Diff;
 pub use minmax::MinMaxResult;
 pub use repeatn::repeat_n;
 pub use sources::{repeat_call, unfold, iterate};
+pub use with_position::Position;
 pub use zip_longest::EitherOrBoth;
 pub use ziptuple::multizip;
 mod adaptors;
@@ -107,6 +109,7 @@ mod size_hint;
 mod sources;
 mod tee;
 mod tuple_impl;
+mod with_position;
 mod zip_eq_impl;
 mod zip_longest;
 mod ziptuple;
@@ -894,6 +897,31 @@ pub trait Itertools : Iterator {
         adaptors::flatten(self)
     }
 
+    /// Return an iterator adaptor that wraps each element in a `Position` to
+    /// ease special-case handling of the first or last elements.
+    ///
+    /// Iterator element type is
+    /// [`Position<Self::Item>`](enum.Position.html)
+    ///
+    /// ```
+    /// use itertools::{Itertools, Position};
+    ///
+    /// let it = (0..4).with_position();
+    /// itertools::assert_equal(it,
+    ///                         vec![Position::First(0),
+    ///                              Position::Middle(1),
+    ///                              Position::Middle(2),
+    ///                              Position::Last(3)]);
+    ///
+    /// let it = (0..1).with_position();
+    /// itertools::assert_equal(it, vec![Position::Only(0)]);
+    /// ```
+    fn with_position(self) -> WithPosition<Self>
+        where Self: Sized,
+    {
+        with_position::with_position(self)
+    }
+
     // non-adaptor methods
     /// Advances the iterator and returns the next items grouped in a tuple of
     /// a specific size (up to 4).

src/with_position.rs

@@ -0,0 +1,74 @@
+use std::iter::{Fuse,Peekable};
+
+/// An iterator adaptor that wraps each element in an [`Position`](../enum.Position.html).
+///
+/// Iterator element type is `Position<I::Item>`.
+/// This iterator is *fused*.
+///
+/// See [`.with_position()`](../trait.Itertools.html#method.with_position) for more information.
+pub struct WithPosition<I>
+    where I: Iterator,
+{
+    handled_first: bool,
+    peekable: Peekable<Fuse<I>>,
+}
+
+/// Create a new `WithPosition` iterator.
+pub fn with_position<I>(iter: I) -> WithPosition<I>
+    where I: Iterator,
+{
+    WithPosition {
+        handled_first: false,
+        peekable: iter.fuse().peekable(),
+    }
+}
+
+/// A value yielded by `WithPosition`.
+/// Indicates the position of this element in the iterator results.
+///
+/// See [`.with_position()`](trait.Itertools.html#method.with_position) for more information.
+#[derive(Copy, Clone, Debug, PartialEq)]
+pub enum Position<T> {
+    /// This is the first element.
+    First(T),
+    /// This is neither the first nor the last element.
+    Middle(T),
+    /// This is the last element.
+    Last(T),
+    /// This is the only element.
+    Only(T),
+}
+
+impl<I: Iterator> Iterator for WithPosition<I> {
+    type Item = Position<I::Item>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.peekable.next() {
+            Some(item) => {
+                if !self.handled_first {
+                    // Haven't seen the first item yet, and there is one to give.
+                    self.handled_first = true;
+                    // Peek to see if this is also the last item,
+                    // in which case tag it as `Only`.
+                    match self.peekable.peek() {
+                        Some(_) => Some(Position::First(item)),
+                        None => Some(Position::Only(item)),
+                    }
+                } else {
+                    // Have seen the first item, and there's something left.
+                    // Peek to see if this is the last item.
+                    match self.peekable.peek() {
+                        Some(_) => Some(Position::Middle(item)),
+                        None => Some(Position::Last(item)),
+                    }
+                }
+            }
+            // Iterator is finished.
+            None => None,
+        }
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.peekable.size_hint()
+    }
+}