Add #[must_use] to adaptor returned by methods on Itertools trait

src/adaptors/mod.rs

@@ -28,6 +28,7 @@ macro_rules! clone_fields {
 ///
 /// See [`.interleave()`](../trait.Itertools.html#method.interleave) for more information.
 #[derive(Clone, Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Interleave<I, J> {
     a: Fuse<I>,
     b: Fuse<J>,
@@ -90,6 +91,7 @@ impl<I, J> Iterator for Interleave<I, J>
 /// See [`.interleave_shortest()`](../trait.Itertools.html#method.interleave_shortest)
 /// for more information.
 #[derive(Clone, Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct InterleaveShortest<I, J>
     where I: Iterator,
           J: Iterator<Item = I::Item>
@@ -267,6 +269,7 @@ impl<I> Iterator for PutBack<I>
 /// Iterator element type is `(I::Item, J::Item)`.
 ///
 /// See [`.cartesian_product()`](../trait.Itertools.html#method.cartesian_product) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Product<I, J>
     where I: Iterator
 {
@@ -362,6 +365,7 @@ impl<I, J> Iterator for Product<I, J>
 ///
 /// See [`.batching()`](../trait.Itertools.html#method.batching) for more information.
 #[derive(Clone)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Batching<I, F> {
     f: F,
     iter: I,
@@ -401,6 +405,7 @@ impl<B, F, I> Iterator for Batching<I, F>
 ///
 /// See [`.step()`](../trait.Itertools.html#method.step) for more information.
 #[derive(Clone, Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Step<I> {
     iter: Fuse<I>,
     skip: usize,
@@ -514,6 +519,7 @@ impl<I, J> MergeCore<I, J>
 /// Iterator element type is `I::Item`.
 ///
 /// See [`.merge()`](../trait.Itertools.html#method.merge_by) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Merge<I, J>
     where I: Iterator,
           J: Iterator<Item = I::Item>
@@ -586,6 +592,7 @@ impl<I, J> Iterator for Merge<I, J>
 /// Iterator element type is `I::Item`.
 ///
 /// See [`.merge_by()`](../trait.Itertools.html#method.merge_by) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct MergeBy<I, J, F>
     where I: Iterator,
           J: Iterator<Item = I::Item>
@@ -686,6 +693,7 @@ impl<I> CoalesceCore<I>
 /// An iterator adaptor that may join together adjacent elements.
 ///
 /// See [`.coalesce()`](../trait.Itertools.html#method.coalesce) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Coalesce<I, F>
     where I: Iterator
 {
@@ -740,6 +748,7 @@ impl<I, F> Iterator for Coalesce<I, F>
 /// An iterator adaptor that removes repeated duplicates.
 ///
 /// See [`.dedup()`](../trait.Itertools.html#method.dedup) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Dedup<I>
     where I: Iterator
 {
@@ -812,6 +821,7 @@ impl<I> Iterator for Dedup<I>
 /// to only pick off elements while the predicate returns `true`.
 ///
 /// See [`.take_while_ref()`](../trait.Itertools.html#method.take_while_ref) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct TakeWhileRef<'a, I: 'a, F> {
     iter: &'a mut I,
     f: F,
@@ -862,6 +872,7 @@ impl<'a, I, F> Iterator for TakeWhileRef<'a, I, F>
 ///
 /// See [`.while_some()`](../trait.Itertools.html#method.while_some) for more information.
 #[derive(Clone, Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct WhileSome<I> {
     iter: I,
 }
@@ -895,6 +906,7 @@ impl<I, A> Iterator for WhileSome<I>
 /// See [`.tuple_combinations()`](../trait.Itertools.html#method.tuple_combinations) for more
 /// information.
 #[derive(Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct TupleCombinations<I, T>
     where I: Iterator,
           T: HasCombination<I>
@@ -1023,6 +1035,7 @@ impl_tuple_combination!(Tuple4Combination Tuple3Combination ; A, A, A, A, A; a b
 ///
 /// See [`.flatten()`](../trait.Itertools.html#method.flatten) for more information.
 #[derive(Clone, Debug)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Flatten<I, J> {
     iter: I,
     front: Option<J>,
@@ -1074,6 +1087,7 @@ impl<I, J> Iterator for Flatten<I, J>
 /// An iterator adapter to apply a transformation within a nested `Result`.
 ///
 /// See [`.map_results()`](../trait.Itertools.html#method.map_results) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct MapResults<I, F> {
     iter: I,
     f: F
@@ -1108,6 +1122,7 @@ impl<I, F, T, U, E> Iterator for MapResults<I, F>
 /// An iterator adapter to get the positions of each element that matches a predicate.
 ///
 /// See [`.positions()`](../trait.Itertools.html#method.positions) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Positions<I, F> {
     iter: I,
     f: F,

src/combinations.rs

@@ -5,6 +5,7 @@ use std::fmt;
 /// An iterator to iterate through all the `n`-length combinations in an iterator.
 ///
 /// See [`.combinations()`](../trait.Itertools.html#method.combinations) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Combinations<I: Iterator> {
     n: usize,
     indices: Vec<usize>,

src/groupbylazy.rs

@@ -284,6 +284,7 @@ impl<K, I, F> GroupInner<K, I, F>
 /// iterated.
 ///
 /// See [`.group_by()`](../trait.Itertools.html#method.group_by) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct GroupBy<K, I, F>
     where I: Iterator,
 {
@@ -458,6 +459,7 @@ pub fn new_chunks<J>(iter: J, size: usize) -> IntoChunks<J::IntoIter>
 /// Iterator element type is `Chunk`, each chunk's iterator.
 ///
 /// See [`.chunks()`](../trait.Itertools.html#method.chunks) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct IntoChunks<I>
     where I: Iterator,
 {

src/intersperse.rs

@@ -10,6 +10,7 @@ use super::size_hint;
 /// This iterator is *fused*.
 ///
 /// See [`.intersperse()`](../trait.Itertools.html#method.intersperse) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Intersperse<I>
     where I: Iterator
 {

src/kmerge_impl.rs

@@ -109,6 +109,7 @@ fn sift_down<T, S>(heap: &mut [T], index: usize, mut less_than: S)
 /// Iterator element type is `I::Item`.
 ///
 /// See [`.kmerge()`](../trait.Itertools.html#method.kmerge) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct KMerge<I>
     where I: Iterator
 {
@@ -183,6 +184,7 @@ impl<I> Iterator for KMerge<I>
 ///
 /// See [`.kmerge_by()`](../trait.Itertools.html#method.kmerge_by) for more
 /// information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct KMergeBy<I, F>
     where I: Iterator,
 {

src/pad_tail.rs

@@ -8,6 +8,7 @@ use size_hint;
 ///
 /// See [`.pad_using()`](../trait.Itertools.html#method.pad_using) for more information.
 #[derive(Clone)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct PadUsing<I, F> {
     iter: Fuse<I>,
     min: usize,

src/peeking_take_while.rs

@@ -76,6 +76,7 @@ impl<I> PeekingNext for PutBackN<I>
 ///
 /// See [`.peeking_take_while()`](../trait.Itertools.html#method.peeking_take_while)
 /// for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct PeekingTakeWhile<'a, I: 'a, F>
     where I: Iterator,
 {

src/tee.rs

@@ -15,6 +15,7 @@ struct TeeBuffer<A, I> {
 /// One half of an iterator pair where both return the same elements.
 ///
 /// See [`.tee()`](../trait.Itertools.html#method.tee) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Tee<I>
     where I: Iterator
 {

src/tuple_impl.rs

@@ -60,6 +60,7 @@ impl<T> ExactSizeIterator for TupleBuffer<T>
 /// An iterator that groups the items in tuples of a specific size.
 ///
 /// See [`.tuples()`](../trait.Itertools.html#method.tuples) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Tuples<I, T>
     where I: Iterator<Item = T::Item>,
           T: TupleCollect
@@ -114,6 +115,7 @@ impl<I, T> Tuples<I, T>
 ///
 /// See [`.tuple_windows()`](../trait.Itertools.html#method.tuple_windows) for more
 /// information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct TupleWindows<I, T>
     where I: Iterator<Item = T::Item>,
           T: TupleCollect

src/unique_impl.rs

@@ -8,6 +8,7 @@ use std::fmt;
 ///
 /// See [`.unique_by()`](../trait.Itertools.html#method.unique) for more information.
 #[derive(Clone)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct UniqueBy<I: Iterator, V, F> {
     iter: I,
     // Use a hashmap for the entry API
@@ -98,6 +99,7 @@ impl<I> Iterator for Unique<I>
 ///
 /// See [`.unique()`](../trait.Itertools.html#method.unique) for more information.
 #[derive(Clone)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct Unique<I: Iterator> {
     iter: UniqueBy<I, I::Item, ()>,
 }

src/with_position.rs

@@ -5,6 +5,7 @@ use std::iter::{Fuse,Peekable};
 /// Iterator element type is `Position<I::Item>`.
 ///
 /// See [`.with_position()`](../trait.Itertools.html#method.with_position) for more information.
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 pub struct WithPosition<I>
     where I: Iterator,
 {