add docs, test

Author: Qelxiros

library/core/src/iter/traits/accum.rs

@@ -99,8 +99,9 @@ macro_rules! integer_sum_product {
 }
 
 macro_rules! saturating_integer_sum_product {
-    (@impls $zero:expr, $one:expr, #[$attr:meta], $($a:ty)*) => ($(
+    (@impls $zero:expr, $one:expr, $doc:expr, #[$attr:meta], $($a:ty)*) => ($(
         #[$attr]
+        #[doc = $doc]
         impl Sum for $a {
             fn sum<I: Iterator<Item=Self>>(iter: I) -> Self {
                 iter.fold(
@@ -112,6 +113,7 @@ macro_rules! saturating_integer_sum_product {
         }
 
         #[$attr]
+        #[doc = $doc]
         impl Product for $a {
             fn product<I: Iterator<Item=Self>>(iter: I) -> Self {
                 iter.fold(
@@ -123,6 +125,7 @@ macro_rules! saturating_integer_sum_product {
         }
 
         #[$attr]
+        #[doc = $doc]
         impl<'a> Sum<&'a $a> for $a {
             fn sum<I: Iterator<Item=&'a Self>>(iter: I) -> Self {
                 iter.fold(
@@ -134,6 +137,7 @@ macro_rules! saturating_integer_sum_product {
         }
 
         #[$attr]
+        #[doc = $doc]
         impl<'a> Product<&'a $a> for $a {
             fn product<I: Iterator<Item=&'a Self>>(iter: I) -> Self {
                 iter.fold(
@@ -145,8 +149,9 @@ macro_rules! saturating_integer_sum_product {
         }
     )*);
     ($($a:ty)*) => (
-        integer_sum_product!(@impls Saturating(0), Saturating(1),
-                #[stable(feature = "saturating_iter_arith", since = "1.14.0")],
+        saturating_integer_sum_product!(@impls Saturating(0), Saturating(1),
+                "The short-circuiting behavior of this implementation is unspecified. If you care about short-circuiting, use [`Iterator::fold`] directly.",
+                #[stable(feature = "saturating_iter_arith", since = "CURRENT_RUSTC_VERSION")],
                 $(Saturating<$a>)*);
     );
 }

library/coretests/tests/iter/traits/accum.rs

@@ -1,4 +1,5 @@
 use core::iter::*;
+use std::num::Saturating;
 
 #[test]
 fn test_iterator_sum() {
@@ -64,3 +65,38 @@ fn test_iterator_product_option() {
     let v: &[Option<i32>] = &[Some(1), None, Some(3), Some(4)];
     assert_eq!(v.iter().cloned().product::<Option<i32>>(), None);
 }
+
+#[test]
+fn test_saturating_sum_product() {
+    let v = (1u32..=10).map(|i| Saturating(i));
+    assert_eq!(v.sum::<Saturating<u32>>(), Saturating(55));
+    let v = (1u32..=10).map(|i| Saturating(i));
+    assert_eq!(v.product::<Saturating<u32>>(), Saturating(3628800));
+    let v = [Saturating(usize::MAX), Saturating(2)];
+    assert_eq!(v.iter().copied().sum::<Saturating<usize>>(), Saturating(usize::MAX));
+    assert_eq!(v.iter().copied().product::<Saturating<usize>>(), Saturating(usize::MAX));
+
+    let mut cnt = 0;
+    let v = 250..=u8::MAX;
+    assert_eq!(
+        v.map(|i| {
+            cnt += 1;
+            Saturating(i)
+        })
+        .sum::<Saturating<u8>>(),
+        Saturating(u8::MAX)
+    );
+    assert_eq!(cnt, 6); // no short-circuiting
+
+    let mut cnt = 0;
+    let v = (250..=u8::MAX).chain(0..5);
+    assert_eq!(
+        v.map(|i| {
+            cnt += 1;
+            Saturating(i)
+        })
+        .product::<Saturating<u8>>(),
+        Saturating(0)
+    );
+    assert_eq!(cnt, 11); // no short-circuiting
+}