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

1 files changed, 60 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.
 ///