Add docs for `FromIterator<(AE, BE)> for (A, B)`

1 files changed, 19 insertions, 0 deletions

diff --git a/library/core/src/iter/traits/collect.rs b/library/core/src/iter/traits/collect.rs
index 788edfc3f8f..2ebbe2bf274 100644
--- a/library/core/src/iter/traits/collect.rs
+++ b/library/core/src/iter/traits/collect.rs
@@ -150,6 +150,25 @@ pub trait FromIterator<A>: Sized {
     fn from_iter<T: IntoIterator<Item = A>>(iter: T) -> Self;
 }
 
+/// This implementation turns an iterator of tuples into a tuple of types which implement
+/// [`Default`] and [`Extend`].
+///
+/// This is similar to [`Iterator::unzip`], but is also composable with other [`FromIterator`]
+/// implementations:
+///
+/// ```rust
+/// # fn main() -> Result<(), core::num::ParseIntError> {
+/// let string = "1,2,123,4";
+///
+/// let (numbers, lengths): (Vec<_>, Vec<_>) = string
+///     .split(',')
+///     .map(|s| s.parse().map(|n: u32| (n, s.len())))
+///     .collect::<Result<_, _>>()?;
+///
+/// assert_eq!(numbers, [1, 2, 123, 4]);
+/// assert_eq!(lengths, [1, 1, 3, 1]);
+/// # Ok(()) }
+/// ```
 #[stable(feature = "from_iterator_for_tuple", since = "CURRENT_RUSTC_VERSION")]
 impl<A, B, AE, BE> FromIterator<(AE, BE)> for (A, B)
 where