Auto merge of #47562 - Centril:feature/core_convert_id, r=oli-obk

Add the identity function as core::convert::identity

## New notes

This implements rust-lang/rfcs#2306 (see https://github.com/rust-lang/rust/issues/53500).

## Old notes (ignore this in new reviews)

Adds the identity function `fn id<T>(x: T) -> T { x }` to core::convert and the prelude.
Some motivations for why this is useful are explained in the doc tests.
Another is that using the identity function instead of `{ x }` or `|x| x` makes it clear that you intended to use an identity conversion on purpose.

The reasoning:
+ behind adding this to `convert` and not `mem` is that this is an identity *conversion*.
+ for adding this to the prelude is that it should be easy enough to use that the ease of writing your own identity function or using a closure `|x| x` doesn't overtake that.

I've separated this out into two feature gates so that the addition to the prelude can be considered and stabilized separately.

cc @bluss

4 files changed, 107 insertions, 0 deletions

diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index 11cc4ffecf0..d5337868843 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -48,6 +48,66 @@
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
+/// An identity function.
+///
+/// Two things are important to note about this function:
+///
+/// - It is not always equivalent to a closure like `|x| x` since the
+///   closure may coerce `x` into a different type.
+///
+/// - It moves the input `x` passed to the function.
+///
+/// While it might seem strange to have a function that just returns back the
+/// input, there are some interesting uses.
+///
+/// # Examples
+///
+/// Using `identity` to do nothing among other interesting functions:
+///
+/// ```rust
+/// #![feature(convert_id)]
+/// use std::convert::identity;
+///
+/// fn manipulation(x: u32) -> u32 {
+///     // Let's assume that this function does something interesting.
+///     x + 1
+/// }
+///
+/// let _arr = &[identity, manipulation];
+/// ```
+///
+/// Using `identity` to get a function that changes nothing in a conditional:
+///
+/// ```rust
+/// #![feature(convert_id)]
+/// use std::convert::identity;
+///
+/// # let condition = true;
+///
+/// # fn manipulation(x: u32) -> u32 { x + 1 }
+///
+/// let do_stuff = if condition { manipulation } else { identity };
+///
+/// // do more interesting stuff..
+///
+/// let _results = do_stuff(42);
+/// ```
+///
+/// Using `identity` to keep the `Some` variants of an iterator of `Option<T>`:
+///
+/// ```rust
+/// #![feature(convert_id)]
+/// use std::convert::identity;
+///
+/// let iter = vec![Some(1), None, Some(3)].into_iter();
+/// let filtered = iter.filter_map(identity).collect::<Vec<_>>();
+/// assert_eq!(vec![1, 3], filtered);
+/// ```
+#[unstable(feature = "convert_id", issue = "53500")]
+#[rustc_const_unstable(feature = "const_convert_id")]
+#[inline]
+pub const fn identity<T>(x: T) -> T { x }
+
 /// A cheap reference-to-reference conversion. Used to convert a value to a
 /// reference value within generic code.
 ///
diff --git a/src/test/ui/rfc-2306/convert-id-const-no-gate.rs b/src/test/ui/rfc-2306/convert-id-const-no-gate.rs
new file mode 100644
index 00000000000..545c179dec9
--- /dev/null
+++ b/src/test/ui/rfc-2306/convert-id-const-no-gate.rs
@@ -0,0 +1,17 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// This test should fail since identity is not stable as a const fn yet.
+
+#![feature(convert_id)]
+
+fn main() {
+    const _FOO: u8 = ::std::convert::identity(42u8);
+}
diff --git a/src/test/ui/rfc-2306/convert-id-const-no-gate.stderr b/src/test/ui/rfc-2306/convert-id-const-no-gate.stderr
new file mode 100644
index 00000000000..dfd8619d875
--- /dev/null
+++ b/src/test/ui/rfc-2306/convert-id-const-no-gate.stderr
@@ -0,0 +1,10 @@
+error: `std::convert::identity` is not yet stable as a const fn
+  --> $DIR/convert-id-const-no-gate.rs:16:22
+   |
+LL |     const _FOO: u8 = ::std::convert::identity(42u8);
+   |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: in Nightly builds, add `#![feature(const_convert_id)]` to the crate attributes to enable
+
+error: aborting due to previous error
+
diff --git a/src/test/ui/rfc-2306/convert-id-const-with-gate.rs b/src/test/ui/rfc-2306/convert-id-const-with-gate.rs
new file mode 100644
index 00000000000..c546f11914f
--- /dev/null
+++ b/src/test/ui/rfc-2306/convert-id-const-with-gate.rs
@@ -0,0 +1,20 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// This test should pass since we've opted into 'identity' as an
+// unstable const fn.
+
+// compile-pass
+
+#![feature(convert_id, const_convert_id)]
+
+fn main() {
+    const _FOO: u8 = ::std::convert::identity(42u8);
+}