diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 5b6d9e2033caa..eb23b8d7fe1f5 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -1875,6 +1875,55 @@ pub trait Iterator { }).break_value() } + /// Extracts the single remaining element out of the iterator. + /// + /// [`next()`]: #method.next + /// [`by_ref()`]: #method.by_ref + /// [`Some(x)`]: ../../std/option/enum.Option.html#variant.Some + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// + /// If [`next()`] will return [`Some(x)`] the first time, and then return + /// [`None`] the next time around, then `single()` will return `Some(x)`. + /// If there are no elements to extract or if there more than one, + /// then the iterator will will return `None`. + /// + /// This method takes ownership of the iterator it is called on. + /// If you want to retain ownership, call [`by_ref()`] on the iterator + /// first before calling `single()`. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ```rust + /// #![feature(iterator_single)] + /// + /// let zero: [u8; 0] = []; + /// let one: [u8; 1] = [42]; + /// let two: [u8; 2] = [42, 24]; + /// let three: [u8; 3] = [42, 24, 0]; + /// + /// assert_eq!(zero.iter().single(), None); + /// assert_eq!(one.iter().single(), Some(&42)); + /// assert_eq!(two.iter().single(), None); + /// assert_eq!(three.iter().single(), None); + /// ``` + /// + /// # Invariants + /// + /// If `count()` does not panic and returns `1`, then `single()` will + /// return `Some(element)`. Otherwise, `single()` will return `None`. + #[inline] + #[unstable(feature = "iterator_single", issue = "55354")] + fn single(mut self) -> Option where Self: Sized { + if let x@Some(_) = self.next() { + if let None = self.next() { + return x + } + } + None + } + /// Searches for an element in an iterator, returning its index. /// /// `position()` takes a closure that returns `true` or `false`. It applies