Rollup merge of #79805 - m-ou-se:iterator-reduce, r=KodrAus

Rename Iterator::fold_first to reduce and stabilize it

This stabilizes `#![feature(iterator_fold_self)]`.

The name for this function (originally `fold_first`) was still an open question, but the discussion on [the tracking issue](https://github.com/rust-lang/rust/issues/68125) seems to have converged to `reduce`.

compiler/rustc_ast/src/lib.rs

@@ -14,7 +14,6 @@
 #![feature(const_fn_transmute)]
 #![feature(const_panic)]
 #![feature(crate_visibility_modifier)]
-#![feature(iterator_fold_self)]
 #![feature(label_break_value)]
 #![feature(nll)]
 #![feature(or_patterns)]

compiler/rustc_hir/src/hir.rs

@@ -358,7 +358,7 @@ impl GenericArgs<'_> {
             .iter()
             .filter(|arg| !arg.is_synthetic())
             .map(|arg| arg.span())
-            .fold_first(|span1, span2| span1.to(span2))
+            .reduce(|span1, span2| span1.to(span2))
     }
 
     /// Returns span encompassing arguments and their surrounding `<>` or `()`

compiler/rustc_hir/src/lib.rs

@@ -6,7 +6,6 @@
 #![feature(const_fn)] // For the unsizing cast on `&[]`
 #![feature(const_panic)]
 #![feature(in_band_lifetimes)]
-#![feature(iterator_fold_self)]
 #![feature(once_cell)]
 #![feature(or_patterns)]
 #![recursion_limit = "256"]

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

@@ -2028,7 +2028,8 @@ pub trait Iterator {
         self.try_fold((), call(f))
     }
 
-    /// An iterator method that applies a function, producing a single, final value.
+    /// Folds every element into an accumulator by applying an operation,
+    /// returning the final result.
     ///
     /// `fold()` takes two arguments: an initial value, and a closure with two
     /// arguments: an 'accumulator', and an element. The closure returns the value that
@@ -2049,6 +2050,9 @@ pub trait Iterator {
     /// may not terminate for infinite iterators, even on traits for which a
     /// result is determinable in finite time.
     ///
+    /// Note: [`reduce()`] can be used to use the first element as the initial
+    /// value, if the accumulator type and item type is the same.
+    ///
     /// # Note to Implementors
     ///
     /// Several of the other (forward) methods have default implementations in
@@ -2104,6 +2108,8 @@ pub trait Iterator {
     /// // they're the same
     /// assert_eq!(result, result2);
     /// ```
+    ///
+    /// [`reduce()`]: Iterator::reduce
     #[doc(alias = "reduce")]
     #[doc(alias = "inject")]
     #[inline]
@@ -2120,10 +2126,15 @@ pub trait Iterator {
         accum
     }
 
-    /// The same as [`fold()`], but uses the first element in the
-    /// iterator as the initial value, folding every subsequent element into it.
-    /// If the iterator is empty, return [`None`]; otherwise, return the result
-    /// of the fold.
+    /// Reduces the elements to a single one, by repeatedly applying a reducing
+    /// operation.
+    ///
+    /// If the iterator is empty, returns [`None`]; otherwise, returns the
+    /// result of the reduction.
+    ///
+    /// For iterators with at least one element, this is the same as [`fold()`]
+    /// with the first element of the iterator as the initial value, folding
+    /// every subsequent element into it.
     ///
     /// [`fold()`]: Iterator::fold
     ///
@@ -2132,13 +2143,11 @@ pub trait Iterator {
     /// Find the maximum value:
     ///
     /// ```
-    /// #![feature(iterator_fold_self)]
-    ///
     /// fn find_max<I>(iter: I) -> Option<I::Item>
     ///     where I: Iterator,
     ///           I::Item: Ord,
     /// {
-    ///     iter.fold_first(|a, b| {
+    ///     iter.reduce(|a, b| {
     ///         if a >= b { a } else { b }
     ///     })
     /// }
@@ -2149,8 +2158,8 @@ pub trait Iterator {
     /// assert_eq!(find_max(b.iter()), None);
     /// ```
     #[inline]
-    #[unstable(feature = "iterator_fold_self", issue = "68125")]
-    fn fold_first<F>(mut self, f: F) -> Option<Self::Item>
+    #[stable(feature = "iterator_fold_self", since = "1.51.0")]
+    fn reduce<F>(mut self, f: F) -> Option<Self::Item>
     where
         Self: Sized,
         F: FnMut(Self::Item, Self::Item) -> Self::Item,
@@ -2647,7 +2656,7 @@ pub trait Iterator {
             move |x, y| cmp::max_by(x, y, &mut compare)
         }
 
-        self.fold_first(fold(compare))
+        self.reduce(fold(compare))
     }
 
     /// Returns the element that gives the minimum value from the
@@ -2707,7 +2716,7 @@ pub trait Iterator {
             move |x, y| cmp::min_by(x, y, &mut compare)
         }
 
-        self.fold_first(fold(compare))
+        self.reduce(fold(compare))
     }
 
     /// Reverses an iterator's direction.