From a79edd78a5e0b175095ba2212e4b3070e884f01c Mon Sep 17 00:00:00 2001
From: Boiethios <felix-dev@daudre-vignier.fr>
Date: Thu, 25 Oct 2018 22:26:02 +0200
Subject: [PATCH] Iterator::single

---
 src/libcore/iter/iterator.rs | 52 ++++++++++++++++++++++++++++++++++++
 src/libcore/lib.rs           |  1 +
 2 files changed, 53 insertions(+)

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 5b6d9e2033caa..a22d199444f84 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -571,6 +571,58 @@ pub trait Iterator {
         Map { iter: self, f }
     }
 
+    /// Checks whether there is only one item in the iterator, or not.
+    /// If there is one unique item in the iterator, `single()` returns
+    /// [`Some(T)`] of this item, otherwise it returns [`None`], meaning
+    /// that there is no item, or that there are more than one item.
+    /// 
+    /// [`Some(T)`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    /// 
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// #![feature(iterator_single)]
+    ///
+    /// let unique = [1];
+    /// let single = unique.iter().single();
+    /// 
+    /// assert_eq!(single, Some(&1));
+    /// ```
+    /// 
+    /// If there is no or multiple items, `single()` returns `None`:
+    /// 
+    /// ```
+    /// #![feature(iterator_single)]
+    ///
+    /// let empty: [i32; 0] = [];
+    /// let single = empty.iter().single();
+    /// 
+    /// assert_eq!(single, None);
+    /// ```
+    /// 
+    /// ```
+    /// #![feature(iterator_single)]
+    ///
+    /// let multiple = [1, 2];
+    /// let single = multiple.iter().single();
+    /// 
+    /// assert_eq!(single, None);
+    /// ```
+    #[inline]
+    #[unstable(feature = "iterator_single", issue = "12345")] // Not sure of what I should put there
+    fn single(mut self) -> Option<Self::Item> where
+        Self: Sized
+    {
+        let next = self.next();
+        match self.next().is_some() {
+            true => None,
+            false => next,
+        }
+    }
+
     /// Calls a closure on each element of an iterator.
     ///
     /// This is equivalent to using a [`for`] loop on the iterator, although
diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs
index 4156b1bec92a0..a3455188a11ec 100644
--- a/src/libcore/lib.rs
+++ b/src/libcore/lib.rs
@@ -89,6 +89,7 @@
 #![feature(fundamental)]
 #![cfg_attr(stage0, feature(impl_header_lifetime_elision))]
 #![feature(intrinsics)]
+#![feature(iterator_single)]
 #![feature(lang_items)]
 #![feature(link_llvm_intrinsics)]
 #![feature(never_type)]