From b9d270fb6040782580cfc02239f7a94dce1458d5 Mon Sep 17 00:00:00 2001 From: Takashiidobe Date: Wed, 8 Oct 2025 22:19:16 -0400 Subject: [PATCH 1/2] fix some typos and add some examples that panic --- src/adaptors/mod.rs | 4 +-- src/combinations.rs | 4 +-- src/combinations_with_replacement.rs | 4 +-- src/either_or_both.rs | 2 +- src/grouping_map.rs | 2 +- src/kmerge_impl.rs | 4 +-- src/lib.rs | 47 +++++++++++++++++++++++----- src/powerset.rs | 2 +- 8 files changed, 50 insertions(+), 19 deletions(-) diff --git a/src/adaptors/mod.rs b/src/adaptors/mod.rs index e66b105fc..703998bc0 100644 --- a/src/adaptors/mod.rs +++ b/src/adaptors/mod.rs @@ -522,7 +522,7 @@ where debug_fmt_fields!(TakeWhileRef, iter); } -/// Create a new `TakeWhileRef` from a reference to clonable iterator. +/// Create a new `TakeWhileRef` from a reference to cloneable iterator. pub fn take_while_ref(iter: &mut I, f: F) -> TakeWhileRef<'_, I, F> where I: Iterator + Clone, @@ -626,7 +626,7 @@ pub trait HasCombination: Sized { type Combination: From + Iterator; } -/// Create a new `TupleCombinations` from a clonable iterator. +/// Create a new `TupleCombinations` from a cloneable iterator. pub fn tuple_combinations(iter: I) -> TupleCombinations where I: Iterator, diff --git a/src/combinations.rs b/src/combinations.rs index 7bf9dfeab..838007578 100644 --- a/src/combinations.rs +++ b/src/combinations.rs @@ -14,7 +14,7 @@ pub type Combinations = CombinationsGeneric>; /// Iterator for const generic combinations returned by [`.array_combinations()`](crate::Itertools::array_combinations) pub type ArrayCombinations = CombinationsGeneric; -/// Create a new `Combinations` from a clonable iterator. +/// Create a new `Combinations` from a cloneable iterator. pub fn combinations(iter: I, k: usize) -> Combinations where I::Item: Clone, @@ -22,7 +22,7 @@ where Combinations::new(iter, (0..k).collect()) } -/// Create a new `ArrayCombinations` from a clonable iterator. +/// Create a new `ArrayCombinations` from a cloneable iterator. pub fn array_combinations(iter: I) -> ArrayCombinations where I::Item: Clone, diff --git a/src/combinations_with_replacement.rs b/src/combinations_with_replacement.rs index 7142681fe..315df685e 100644 --- a/src/combinations_with_replacement.rs +++ b/src/combinations_with_replacement.rs @@ -36,7 +36,7 @@ where debug_fmt_fields!(CombinationsWithReplacementGeneric, indices, pool, first); } -/// Create a new `ArrayCombinationsWithReplacement`` from a clonable iterator. +/// Create a new `ArrayCombinationsWithReplacement`` from a cloneable iterator. pub fn array_combinations_with_replacement( iter: I, ) -> ArrayCombinationsWithReplacement @@ -45,7 +45,7 @@ where { ArrayCombinationsWithReplacement::new(iter, [0; K]) } -/// Create a new `CombinationsWithReplacement` from a clonable iterator. +/// Create a new `CombinationsWithReplacement` from a cloneable iterator. pub fn combinations_with_replacement(iter: I, k: usize) -> CombinationsWithReplacement where I: Iterator, diff --git a/src/either_or_both.rs b/src/either_or_both.rs index 03a312e90..b39e46265 100644 --- a/src/either_or_both.rs +++ b/src/either_or_both.rs @@ -467,7 +467,7 @@ impl EitherOrBoth { /// Return either value of left, right, or apply a function `f` to both values if both are present. /// The input function has to return the same type as both Right and Left carry. /// - /// This function can be used to preferrably extract the left resp. right value, + /// This function can be used to preferably extract the left resp. right value, /// but fall back to the other (i.e. right resp. left) if the preferred one is not present. /// /// # Examples diff --git a/src/grouping_map.rs b/src/grouping_map.rs index 725e2592a..8b0e75383 100644 --- a/src/grouping_map.rs +++ b/src/grouping_map.rs @@ -46,7 +46,7 @@ where /// `GroupingMapBy` is an intermediate struct for efficient group-and-fold operations. /// -/// See [`GroupingMap`] for more informations. +/// See [`GroupingMap`] for more information. pub type GroupingMapBy = GroupingMap>; /// `GroupingMap` is an intermediate struct for efficient group-and-fold operations. diff --git a/src/kmerge_impl.rs b/src/kmerge_impl.rs index 9ea73f9e8..2495cf782 100644 --- a/src/kmerge_impl.rs +++ b/src/kmerge_impl.rs @@ -97,7 +97,7 @@ where } } -/// An iterator adaptor that merges an abitrary number of base iterators in ascending order. +/// An iterator adaptor that merges an arbitrary number of base iterators in ascending order. /// If all base iterators are sorted (ascending), the result is sorted. /// /// Iterator element type is `I::Item`. @@ -146,7 +146,7 @@ where kmerge_by(iterable, KMergeByLt) } -/// An iterator adaptor that merges an abitrary number of base iterators +/// An iterator adaptor that merges an arbitrary number of base iterators /// according to an ordering function. /// /// Iterator element type is `I::Item`. diff --git a/src/lib.rs b/src/lib.rs index 699f68598..e4885dac7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -622,6 +622,28 @@ pub trait Itertools: Iterator { /// /// **Panics** if the iterators reach an end and they are not of equal /// lengths. + /// + /// # Examples + /// + /// ``` + /// use itertools::Itertools; + /// + /// let a = [1, 2]; + /// let b = [3, 4]; + /// + /// let zipped: Vec<_> = a.into_iter().zip_eq(b.into_iter()).collect(); + /// + /// assert_eq!(zipped, vec![(1, 3), (2, 4)]); + /// ``` + /// + /// ```should_panic + /// use itertools::Itertools; + /// + /// let a = [1, 2]; + /// let b = [3, 4, 5]; + /// // This example panics because the iterators are not of equal length. + /// let _zipped: Vec<_> = a.iter().zip_eq(b.iter()).collect(); + /// ``` #[inline] fn zip_eq(self, other: J) -> ZipEq where @@ -731,6 +753,8 @@ pub trait Itertools: Iterator { /// /// **Panics** if `size` is 0. /// + /// # Examples + /// /// ``` /// use itertools::Itertools; /// @@ -744,6 +768,13 @@ pub trait Itertools: Iterator { /// assert_eq!(4, chunk.sum()); /// } /// ``` + /// + /// ```should_panic + /// use itertools::Itertools; + /// let data = vec![1, 2, 3]; + /// // Panics because chunk size is 0. + /// let _chunks = data.into_iter().chunks(0); + /// ``` #[cfg(feature = "use_alloc")] fn chunks(self, size: usize) -> IntoChunks where @@ -872,7 +903,7 @@ pub trait Itertools: Iterator { /// Split into an iterator pair that both yield all elements from /// the original iterator. /// - /// **Note:** If the iterator is clonable, prefer using that instead + /// **Note:** If the iterator is cloneable, prefer using that instead /// of using this method. Cloning is likely to be more efficient. /// /// Iterator element type is `Self::Item`. @@ -1003,7 +1034,7 @@ pub trait Itertools: Iterator { /// as long as the original iterator produces `Ok` values. /// /// If the original iterable produces an error at any point, the adapted - /// iterator ends and it will return the error iself. + /// iterator ends and it will return the error itself. /// /// Otherwise, the return value from the closure is returned wrapped /// inside `Ok`. @@ -1601,11 +1632,11 @@ pub trait Itertools: Iterator { /// #[derive(Debug, PartialEq)] /// struct NoCloneImpl(i32); /// - /// let non_clonable_items: Vec<_> = vec![1, 2, 3, 4, 5] + /// let non_cloneable_items: Vec<_> = vec![1, 2, 3, 4, 5] /// .into_iter() /// .map(NoCloneImpl) /// .collect(); - /// let filtered: Vec<_> = non_clonable_items + /// let filtered: Vec<_> = non_cloneable_items /// .into_iter() /// .take_while_inclusive(|n| n.0 % 3 != 0) /// .collect(); @@ -3797,7 +3828,7 @@ pub trait Itertools: Iterator { /// value of type `K` will be used as key to identify the groups and the /// value of type `V` as value for the folding operation. /// - /// See [`GroupingMap`] for more informations + /// See [`GroupingMap`] for more information /// on what operations are available. #[cfg(feature = "use_std")] fn into_grouping_map(self) -> GroupingMap @@ -3814,7 +3845,7 @@ pub trait Itertools: Iterator { /// The values from this iterator will be used as values for the folding operation /// while the keys will be obtained from the values by calling `key_mapper`. /// - /// See [`GroupingMap`] for more informations + /// See [`GroupingMap`] for more information /// on what operations are available. #[cfg(feature = "use_std")] fn into_grouping_map_by(self, key_mapper: F) -> GroupingMapBy @@ -4334,7 +4365,7 @@ pub trait Itertools: Iterator { } } - /// Return the postions of the minimum and maximum elements of an + /// Return the positions of the minimum and maximum elements of an /// iterator, as determined by the specified function. /// /// The return value is a variant of [`MinMaxResult`] like for @@ -4382,7 +4413,7 @@ pub trait Itertools: Iterator { } } - /// Return the postions of the minimum and maximum elements of an + /// Return the positions of the minimum and maximum elements of an /// iterator, as determined by the specified comparison function. /// /// The return value is a variant of [`MinMaxResult`] like for diff --git a/src/powerset.rs b/src/powerset.rs index 734eaf614..f32cf8b78 100644 --- a/src/powerset.rs +++ b/src/powerset.rs @@ -31,7 +31,7 @@ where debug_fmt_fields!(Powerset, combs); } -/// Create a new `Powerset` from a clonable iterator. +/// Create a new `Powerset` from a cloneable iterator. pub fn powerset(src: I) -> Powerset where I: Iterator, From 04e00541151336a72f93ba9056febb9d8510fe9c Mon Sep 17 00:00:00 2001 From: Takashiidobe Date: Thu, 9 Oct 2025 09:02:27 -0400 Subject: [PATCH 2/2] fix failing rustdoc test: [] should've been vec![] --- src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index e4885dac7..ee4f3ab78 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -628,12 +628,12 @@ pub trait Itertools: Iterator { /// ``` /// use itertools::Itertools; /// - /// let a = [1, 2]; - /// let b = [3, 4]; + /// let a = vec![1, 2]; + /// let b = vec![3, 4]; /// /// let zipped: Vec<_> = a.into_iter().zip_eq(b.into_iter()).collect(); /// - /// assert_eq!(zipped, vec![(1, 3), (2, 4)]); + /// itertools::assert_equal(zipped, vec![(1, 3), (2, 4)]); /// ``` /// /// ```should_panic