/// Folding is useful whenever you have a collection of something, and want
/// to produce a single value from it.
///
+ /// Note: `rfold()` combines elements in a *right-associative* fashion. For associative
+ /// operators like `+`, the order the elements are combined in is not important, but for non-associative
+ /// operators like `-` the order will affect the final result.
+ /// For a *left-associative* version of `rfold()`, see [`Iterator::fold()`].
+ ///
/// # Examples
///
/// Basic usage:
/// assert_eq!(sum, 6);
/// ```
///
- /// This example builds a string, starting with an initial value
+ /// This example demonstrates the right-associative nature of `rfold()`:
+ /// it builds a string, starting with an initial value
/// and continuing with each element from the back until the front:
///
/// ```
///
/// assert_eq!(result, "(1 + (2 + (3 + (4 + (5 + 0)))))");
/// ```
+ #[doc(alias = "foldr")]
#[inline]
#[stable(feature = "iter_rfold", since = "1.27.0")]
fn rfold<B, F>(mut self, init: B, mut f: F) -> B
/// 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: `fold()` combines elements in a *left-associative* fashion. For associative
+ /// operators like `+`, the order the elements are combined in is not important, but for non-associative
+ /// operators like `-` the order will affect the final result.
+ /// For a *right-associative* version of `fold()`, see [`DoubleEndedIterator::rfold()`].
+ ///
/// # Note to Implementors
///
/// Several of the other (forward) methods have default implementations in
///
/// And so, our final result, `6`.
///
+ /// This example demonstrates the left-associative nature of `fold()`:
+ /// it builds a string, starting with an initial value
+ /// and continuing with each element from the front until the back:
+ ///
+ /// ```
+ /// let numbers = [1, 2, 3, 4, 5];
+ ///
+ /// let zero = "0".to_string();
+ ///
+ /// let result = numbers.iter().fold(zero, |acc, &x| {
+ /// format!("({} + {})", acc, x)
+ /// });
+ ///
+ /// assert_eq!(result, "(((((0 + 1) + 2) + 3) + 4) + 5)");
+ /// ```
/// It's common for people who haven't used iterators a lot to
/// use a `for` loop with a list of things to build up a result. Those
/// can be turned into `fold()`s:
/// ```
///
/// [`reduce()`]: Iterator::reduce
- #[doc(alias = "inject")]
+ #[doc(alias = "inject", alias = "foldl")]
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn fold<B, F>(mut self, init: B, mut f: F) -> B