1//! Traits for conversions between types.2//!3//! The traits in this module provide a way to convert from one type to another type.4//! Each trait serves a different purpose:5//!6//! - Implement the [`AsRef`] trait for cheap reference-to-reference conversions7//! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions8//! - Implement the [`From`] trait for consuming value-to-value conversions9//! - Implement the [`Into`] trait for consuming value-to-value conversions to types10//! outside the current crate11//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`],12//! but should be implemented when the conversion can fail.13//!14//! The traits in this module are often used as trait bounds for generic functions such that to15//! arguments of multiple types are supported. See the documentation of each trait for examples.16//!17//! As a library author, you should always prefer implementing [`From<T>`][`From`] or18//! [`TryFrom<T>`][`TryFrom`] rather than [`Into<U>`][`Into`] or [`TryInto<U>`][`TryInto`],19//! as [`From`] and [`TryFrom`] provide greater flexibility and offer20//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a21//! blanket implementation in the standard library. When targeting a version prior to Rust 1.41, it22//! may be necessary to implement [`Into`] or [`TryInto`] directly when converting to a type23//! outside the current crate.24//!25//! # Generic Implementations26//!27//! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference28//! (but not generally for all [dereferenceable types][core::ops::Deref])29//! - [`From`]`<U> for T` implies [`Into`]`<T> for U`30//! - [`TryFrom`]`<U> for T` implies [`TryInto`]`<T> for U`31//! - [`From`] and [`Into`] are reflexive, which means that all types can32//! `into` themselves and `from` themselves33//!34//! See each trait for usage examples.3536#![stable(feature ="rust1", since ="1.0.0")]3738usecrate::error::Error;39usecrate::fmt;40usecrate::hash::{Hash, Hasher};41usecrate::marker::PointeeSized;4243modnum;4445#[unstable(feature ="convert_float_to_int", issue ="67057")]46pub usenum::FloatToInt;4748/// The identity function.49///50/// Two things are important to note about this function:51///52/// - It is not always equivalent to a closure like `|x| x`, since the53/// closure may coerce `x` into a different type.54///55/// - It moves the input `x` passed to the function.56///57/// While it might seem strange to have a function that just returns back the58/// input, there are some interesting uses.59///60/// # Examples61///62/// Using `identity` to do nothing in a sequence of other, interesting,63/// functions:64///65/// ```rust66/// use std::convert::identity;67///68/// fn manipulation(x: u32) -> u32 {69/// // Let's pretend that adding one is an interesting function.70/// x + 171/// }72///73/// let _arr = &[identity, manipulation];74/// ```75///76/// Using `identity` as a "do nothing" base case in a conditional:77///78/// ```rust79/// use std::convert::identity;80///81/// # let condition = true;82/// #83/// # fn manipulation(x: u32) -> u32 { x + 1 }84/// #85/// let do_stuff = if condition { manipulation } else { identity };86///87/// // Do more interesting stuff...88///89/// let _results = do_stuff(42);90/// ```91///92/// Using `identity` to keep the `Some` variants of an iterator of `Option<T>`:93///94/// ```rust95/// use std::convert::identity;96///97/// let iter = [Some(1), None, Some(3)].into_iter();98/// let filtered = iter.filter_map(identity).collect::<Vec<_>>();99/// assert_eq!(vec![1, 3], filtered);100/// ```101#[stable(feature ="convert_id", since ="1.33.0")]102#[rustc_const_stable(feature ="const_identity", since ="1.33.0")]103#[inline(always)]104#[rustc_diagnostic_item ="convert_identity"]105pub const fnidentity<T>(x: T) -> T {106 x107}108109/// Used to do a cheap reference-to-reference conversion.110///111/// This trait is similar to [`AsMut`] which is used for converting between mutable references.112/// If you need to do a costly conversion it is better to implement [`From`] with type113/// `&T` or write a custom function.114///115/// # Relation to `Borrow`116///117/// `AsRef` has the same signature as [`Borrow`], but [`Borrow`] is different in a few aspects:118///119/// - Unlike `AsRef`, [`Borrow`] has a blanket impl for any `T`, and can be used to accept either120/// a reference or a value. (See also note on `AsRef`'s reflexibility below.)121/// - [`Borrow`] also requires that [`Hash`], [`Eq`] and [`Ord`] for a borrowed value are122/// equivalent to those of the owned value. For this reason, if you want to123/// borrow only a single field of a struct you can implement `AsRef`, but not [`Borrow`].124///125/// **Note: This trait must not fail**. If the conversion can fail, use a126/// dedicated method which returns an [`Option<T>`] or a [`Result<T, E>`].127///128/// # Generic Implementations129///130/// `AsRef` auto-dereferences if the inner type is a reference or a mutable reference131/// (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`).132///133/// Note that due to historic reasons, the above currently does not hold generally for all134/// [dereferenceable types], e.g. `foo.as_ref()` will *not* work the same as135/// `Box::new(foo).as_ref()`. Instead, many smart pointers provide an `as_ref` implementation which136/// simply returns a reference to the [pointed-to value] (but do not perform a cheap137/// reference-to-reference conversion for that value). However, [`AsRef::as_ref`] should not be138/// used for the sole purpose of dereferencing; instead ['`Deref` coercion'] can be used:139///140/// [dereferenceable types]: core::ops::Deref141/// [pointed-to value]: core::ops::Deref::Target142/// ['`Deref` coercion']: core::ops::Deref#deref-coercion143///144/// ```145/// let x = Box::new(5i32);146/// // Avoid this:147/// // let y: &i32 = x.as_ref();148/// // Better just write:149/// let y: &i32 = &x;150/// ```151///152/// Types which implement [`Deref`] should consider implementing `AsRef<T>` as follows:153///154/// [`Deref`]: core::ops::Deref155///156/// ```157/// # use core::ops::Deref;158/// # struct SomeType;159/// # impl Deref for SomeType {160/// # type Target = [u8];161/// # fn deref(&self) -> &[u8] {162/// # &[]163/// # }164/// # }165/// impl<T> AsRef<T> for SomeType166/// where167/// T: ?Sized,168/// <SomeType as Deref>::Target: AsRef<T>,169/// {170/// fn as_ref(&self) -> &T {171/// self.deref().as_ref()172/// }173/// }174/// ```175///176/// # Reflexivity177///178/// Ideally, `AsRef` would be reflexive, i.e. there would be an `impl<T: ?Sized> AsRef<T> for T`179/// with [`as_ref`] simply returning its argument unchanged.180/// Such a blanket implementation is currently *not* provided due to technical restrictions of181/// Rust's type system (it would be overlapping with another existing blanket implementation for182/// `&T where T: AsRef<U>` which allows `AsRef` to auto-dereference, see "Generic Implementations"183/// above).184///185/// [`as_ref`]: AsRef::as_ref186///187/// A trivial implementation of `AsRef<T> for T` must be added explicitly for a particular type `T`188/// where needed or desired. Note, however, that not all types from `std` contain such an189/// implementation, and those cannot be added by external code due to orphan rules.190///191/// # Examples192///193/// By using trait bounds we can accept arguments of different types as long as they can be194/// converted to the specified type `T`.195///196/// For example: By creating a generic function that takes an `AsRef<str>` we express that we197/// want to accept all references that can be converted to [`&str`] as an argument.198/// Since both [`String`] and [`&str`] implement `AsRef<str>` we can accept both as input argument.199///200/// [`&str`]: primitive@str201/// [`Borrow`]: crate::borrow::Borrow202/// [`Eq`]: crate::cmp::Eq203/// [`Ord`]: crate::cmp::Ord204/// [`String`]: ../../std/string/struct.String.html205///206/// ```207/// fn is_hello<T: AsRef<str>>(s: T) {208/// assert_eq!("hello", s.as_ref());209/// }210///211/// let s = "hello";212/// is_hello(s);213///214/// let s = "hello".to_string();215/// is_hello(s);216/// ```217#[stable(feature ="rust1", since ="1.0.0")]218#[rustc_diagnostic_item ="AsRef"]219pub traitAsRef<T: PointeeSized>: PointeeSized {220/// Converts this type into a shared reference of the (usually inferred) input type.221#[stable(feature ="rust1", since ="1.0.0")]222fnas_ref(&self) ->&T;223}224225/// Used to do a cheap mutable-to-mutable reference conversion.226///227/// This trait is similar to [`AsRef`] but used for converting between mutable228/// references. If you need to do a costly conversion it is better to229/// implement [`From`] with type `&mut T` or write a custom function.230///231/// **Note: This trait must not fail**. If the conversion can fail, use a232/// dedicated method which returns an [`Option<T>`] or a [`Result<T, E>`].233///234/// # Generic Implementations235///236/// `AsMut` auto-dereferences if the inner type is a mutable reference237/// (e.g.: `foo.as_mut()` will work the same if `foo` has type `&mut Foo` or `&mut &mut Foo`).238///239/// Note that due to historic reasons, the above currently does not hold generally for all240/// [mutably dereferenceable types], e.g. `foo.as_mut()` will *not* work the same as241/// `Box::new(foo).as_mut()`. Instead, many smart pointers provide an `as_mut` implementation which242/// simply returns a reference to the [pointed-to value] (but do not perform a cheap243/// reference-to-reference conversion for that value). However, [`AsMut::as_mut`] should not be244/// used for the sole purpose of mutable dereferencing; instead ['`Deref` coercion'] can be used:245///246/// [mutably dereferenceable types]: core::ops::DerefMut247/// [pointed-to value]: core::ops::Deref::Target248/// ['`Deref` coercion']: core::ops::DerefMut#mutable-deref-coercion249///250/// ```251/// let mut x = Box::new(5i32);252/// // Avoid this:253/// // let y: &mut i32 = x.as_mut();254/// // Better just write:255/// let y: &mut i32 = &mut x;256/// ```257///258/// Types which implement [`DerefMut`] should consider to add an implementation of `AsMut<T>` as259/// follows:260///261/// [`DerefMut`]: core::ops::DerefMut262///263/// ```264/// # use core::ops::{Deref, DerefMut};265/// # struct SomeType;266/// # impl Deref for SomeType {267/// # type Target = [u8];268/// # fn deref(&self) -> &[u8] {269/// # &[]270/// # }271/// # }272/// # impl DerefMut for SomeType {273/// # fn deref_mut(&mut self) -> &mut [u8] {274/// # &mut []275/// # }276/// # }277/// impl<T> AsMut<T> for SomeType278/// where279/// <SomeType as Deref>::Target: AsMut<T>,280/// {281/// fn as_mut(&mut self) -> &mut T {282/// self.deref_mut().as_mut()283/// }284/// }285/// ```286///287/// # Reflexivity288///289/// Ideally, `AsMut` would be reflexive, i.e. there would be an `impl<T: ?Sized> AsMut<T> for T`290/// with [`as_mut`] simply returning its argument unchanged.291/// Such a blanket implementation is currently *not* provided due to technical restrictions of292/// Rust's type system (it would be overlapping with another existing blanket implementation for293/// `&mut T where T: AsMut<U>` which allows `AsMut` to auto-dereference, see "Generic294/// Implementations" above).295///296/// [`as_mut`]: AsMut::as_mut297///298/// A trivial implementation of `AsMut<T> for T` must be added explicitly for a particular type `T`299/// where needed or desired. Note, however, that not all types from `std` contain such an300/// implementation, and those cannot be added by external code due to orphan rules.301///302/// # Examples303///304/// Using `AsMut` as trait bound for a generic function, we can accept all mutable references that305/// can be converted to type `&mut T`. Unlike [dereference], which has a single [target type],306/// there can be multiple implementations of `AsMut` for a type. In particular, `Vec<T>` implements307/// both `AsMut<Vec<T>>` and `AsMut<[T]>`.308///309/// In the following, the example functions `caesar` and `null_terminate` provide a generic310/// interface which work with any type that can be converted by cheap mutable-to-mutable conversion311/// into a byte slice (`[u8]`) or byte vector (`Vec<u8>`), respectively.312///313/// [dereference]: core::ops::DerefMut314/// [target type]: core::ops::Deref::Target315///316/// ```317/// struct Document {318/// info: String,319/// content: Vec<u8>,320/// }321///322/// impl<T: ?Sized> AsMut<T> for Document323/// where324/// Vec<u8>: AsMut<T>,325/// {326/// fn as_mut(&mut self) -> &mut T {327/// self.content.as_mut()328/// }329/// }330///331/// fn caesar<T: AsMut<[u8]>>(data: &mut T, key: u8) {332/// for byte in data.as_mut() {333/// *byte = byte.wrapping_add(key);334/// }335/// }336///337/// fn null_terminate<T: AsMut<Vec<u8>>>(data: &mut T) {338/// // Using a non-generic inner function, which contains most of the339/// // functionality, helps to minimize monomorphization overhead.340/// fn doit(data: &mut Vec<u8>) {341/// let len = data.len();342/// if len == 0 || data[len-1] != 0 {343/// data.push(0);344/// }345/// }346/// doit(data.as_mut());347/// }348///349/// fn main() {350/// let mut v: Vec<u8> = vec![1, 2, 3];351/// caesar(&mut v, 5);352/// assert_eq!(v, [6, 7, 8]);353/// null_terminate(&mut v);354/// assert_eq!(v, [6, 7, 8, 0]);355/// let mut doc = Document {356/// info: String::from("Example"),357/// content: vec![17, 19, 8],358/// };359/// caesar(&mut doc, 1);360/// assert_eq!(doc.content, [18, 20, 9]);361/// null_terminate(&mut doc);362/// assert_eq!(doc.content, [18, 20, 9, 0]);363/// }364/// ```365///366/// Note, however, that APIs don't need to be generic. In many cases taking a `&mut [u8]` or367/// `&mut Vec<u8>`, for example, is the better choice (callers need to pass the correct type then).368#[stable(feature ="rust1", since ="1.0.0")]369#[rustc_diagnostic_item ="AsMut"]370pub traitAsMut<T: PointeeSized>: PointeeSized {371/// Converts this type into a mutable reference of the (usually inferred) input type.372#[stable(feature ="rust1", since ="1.0.0")]373fnas_mut(&mutself) ->&mutT;374}375376/// A value-to-value conversion that consumes the input value. The377/// opposite of [`From`].378///379/// One should avoid implementing [`Into`] and implement [`From`] instead.380/// Implementing [`From`] automatically provides one with an implementation of [`Into`]381/// thanks to the blanket implementation in the standard library.382///383/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function384/// to ensure that types that only implement [`Into`] can be used as well.385///386/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`].387///388/// # Generic Implementations389///390/// - [`From`]`<T> for U` implies `Into<U> for T`391/// - [`Into`] is reflexive, which means that `Into<T> for T` is implemented392///393/// # Implementing [`Into`] for conversions to external types in old versions of Rust394///395/// Prior to Rust 1.41, if the destination type was not part of the current crate396/// then you couldn't implement [`From`] directly.397/// For example, take this code:398///399/// ```400/// # #![allow(non_local_definitions)]401/// struct Wrapper<T>(Vec<T>);402/// impl<T> From<Wrapper<T>> for Vec<T> {403/// fn from(w: Wrapper<T>) -> Vec<T> {404/// w.0405/// }406/// }407/// ```408/// This will fail to compile in older versions of the language because Rust's orphaning rules409/// used to be a little bit more strict. To bypass this, you could implement [`Into`] directly:410///411/// ```412/// struct Wrapper<T>(Vec<T>);413/// impl<T> Into<Vec<T>> for Wrapper<T> {414/// fn into(self) -> Vec<T> {415/// self.0416/// }417/// }418/// ```419///420/// It is important to understand that [`Into`] does not provide a [`From`] implementation421/// (as [`From`] does with [`Into`]). Therefore, you should always try to implement [`From`]422/// and then fall back to [`Into`] if [`From`] can't be implemented.423///424/// # Examples425///426/// [`String`] implements [`Into`]`<`[`Vec`]`<`[`u8`]`>>`:427///428/// In order to express that we want a generic function to take all arguments that can be429/// converted to a specified type `T`, we can use a trait bound of [`Into`]`<T>`.430/// For example: The function `is_hello` takes all arguments that can be converted into a431/// [`Vec`]`<`[`u8`]`>`.432///433/// ```434/// fn is_hello<T: Into<Vec<u8>>>(s: T) {435/// let bytes = b"hello".to_vec();436/// assert_eq!(bytes, s.into());437/// }438///439/// let s = "hello".to_string();440/// is_hello(s);441/// ```442///443/// [`String`]: ../../std/string/struct.String.html444/// [`Vec`]: ../../std/vec/struct.Vec.html445#[rustc_diagnostic_item ="Into"]446#[stable(feature ="rust1", since ="1.0.0")]447#[doc(search_unbox)]448#[rustc_const_unstable(feature ="const_from", issue ="143773")]449#[const_trait]450pub traitInto<T>: Sized {451/// Converts this type into the (usually inferred) input type.452#[must_use]453 #[stable(feature ="rust1", since ="1.0.0")]454fninto(self) -> T;455}456457/// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of458/// [`Into`].459///460/// One should always prefer implementing `From` over [`Into`]461/// because implementing `From` automatically provides one with an implementation of [`Into`]462/// thanks to the blanket implementation in the standard library.463///464/// Only implement [`Into`] when targeting a version prior to Rust 1.41 and converting to a type465/// outside the current crate.466/// `From` was not able to do these types of conversions in earlier versions because of Rust's467/// orphaning rules.468/// See [`Into`] for more details.469///470/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function471/// to ensure that types that only implement [`Into`] can be used as well.472///473/// The `From` trait is also very useful when performing error handling. When constructing a function474/// that is capable of failing, the return type will generally be of the form `Result<T, E>`.475/// `From` simplifies error handling by allowing a function to return a single error type476/// that encapsulates multiple error types. See the "Examples" section and [the book][book] for more477/// details.478///479/// **Note: This trait must not fail**. The `From` trait is intended for perfect conversions.480/// If the conversion can fail or is not perfect, use [`TryFrom`].481///482/// # Generic Implementations483///484/// - `From<T> for U` implies [`Into`]`<U> for T`485/// - `From` is reflexive, which means that `From<T> for T` is implemented486///487/// # When to implement `From`488///489/// While there's no technical restrictions on which conversions can be done using490/// a `From` implementation, the general expectation is that the conversions491/// should typically be restricted as follows:492///493/// * The conversion is *infallible*: if the conversion can fail, use [`TryFrom`]494/// instead; don't provide a `From` impl that panics.495///496/// * The conversion is *lossless*: semantically, it should not lose or discard497/// information. For example, `i32: From<u16>` exists, where the original498/// value can be recovered using `u16: TryFrom<i32>`. And `String: From<&str>`499/// exists, where you can get something equivalent to the original value via500/// `Deref`. But `From` cannot be used to convert from `u32` to `u16`, since501/// that cannot succeed in a lossless way. (There's some wiggle room here for502/// information not considered semantically relevant. For example,503/// `Box<[T]>: From<Vec<T>>` exists even though it might not preserve capacity,504/// like how two vectors can be equal despite differing capacities.)505///506/// * The conversion is *value-preserving*: the conceptual kind and meaning of507/// the resulting value is the same, even though the Rust type and technical508/// representation might be different. For example `-1_i8 as u8` is *lossless*,509/// since `as` casting back can recover the original value, but that conversion510/// is *not* available via `From` because `-1` and `255` are different conceptual511/// values (despite being identical bit patterns technically). But512/// `f32: From<i16>` *is* available because `1_i16` and `1.0_f32` are conceptually513/// the same real number (despite having very different bit patterns technically).514/// `String: From<char>` is available because they're both *text*, but515/// `String: From<u32>` is *not* available, since `1` (a number) and `"1"`516/// (text) are too different. (Converting values to text is instead covered517/// by the [`Display`](crate::fmt::Display) trait.)518///519/// * The conversion is *obvious*: it's the only reasonable conversion between520/// the two types. Otherwise it's better to have it be a named method or521/// constructor, like how [`str::as_bytes`] is a method and how integers have522/// methods like [`u32::from_ne_bytes`], [`u32::from_le_bytes`], and523/// [`u32::from_be_bytes`], none of which are `From` implementations. Whereas524/// there's only one reasonable way to wrap an [`Ipv6Addr`](crate::net::Ipv6Addr)525/// into an [`IpAddr`](crate::net::IpAddr), thus `IpAddr: From<Ipv6Addr>` exists.526///527/// # Examples528///529/// [`String`] implements `From<&str>`:530///531/// An explicit conversion from a `&str` to a String is done as follows:532///533/// ```534/// let string = "hello".to_string();535/// let other_string = String::from("hello");536///537/// assert_eq!(string, other_string);538/// ```539///540/// While performing error handling it is often useful to implement `From` for your own error type.541/// By converting underlying error types to our own custom error type that encapsulates the542/// underlying error type, we can return a single error type without losing information on the543/// underlying cause. The '?' operator automatically converts the underlying error type to our544/// custom error type with `From::from`.545///546/// ```547/// use std::fs;548/// use std::io;549/// use std::num;550///551/// enum CliError {552/// IoError(io::Error),553/// ParseError(num::ParseIntError),554/// }555///556/// impl From<io::Error> for CliError {557/// fn from(error: io::Error) -> Self {558/// CliError::IoError(error)559/// }560/// }561///562/// impl From<num::ParseIntError> for CliError {563/// fn from(error: num::ParseIntError) -> Self {564/// CliError::ParseError(error)565/// }566/// }567///568/// fn open_and_parse_file(file_name: &str) -> Result<i32, CliError> {569/// let mut contents = fs::read_to_string(&file_name)?;570/// let num: i32 = contents.trim().parse()?;571/// Ok(num)572/// }573/// ```574///575/// [`String`]: ../../std/string/struct.String.html576/// [`from`]: From::from577/// [book]: ../../book/ch09-00-error-handling.html578#[rustc_diagnostic_item ="From"]579#[stable(feature ="rust1", since ="1.0.0")]580#[rustc_on_unimplemented(on(581 all(Self="&str", T ="alloc::string::String"),582 note ="to coerce a `{T}` into a `{Self}`, use `&*` as a prefix",583))]584#[doc(search_unbox)]585#[rustc_const_unstable(feature ="const_from", issue ="143773")]586#[const_trait]587pub traitFrom<T>: Sized {588/// Converts to this type from the input type.589#[rustc_diagnostic_item ="from_fn"]590 #[must_use]591 #[stable(feature ="rust1", since ="1.0.0")]592fnfrom(value: T) ->Self;593}594595/// An attempted conversion that consumes `self`, which may or may not be596/// expensive.597///598/// Library authors should usually not directly implement this trait,599/// but should prefer implementing the [`TryFrom`] trait, which offers600/// greater flexibility and provides an equivalent `TryInto`601/// implementation for free, thanks to a blanket implementation in the602/// standard library. For more information on this, see the603/// documentation for [`Into`].604///605/// Prefer using [`TryInto`] over [`TryFrom`] when specifying trait bounds on a generic function606/// to ensure that types that only implement [`TryInto`] can be used as well.607///608/// # Implementing `TryInto`609///610/// This suffers the same restrictions and reasoning as implementing611/// [`Into`], see there for details.612#[rustc_diagnostic_item ="TryInto"]613#[stable(feature ="try_from", since ="1.34.0")]614#[rustc_const_unstable(feature ="const_from", issue ="143773")]615#[const_trait]616pub traitTryInto<T>: Sized {617/// The type returned in the event of a conversion error.618#[stable(feature ="try_from", since ="1.34.0")]619typeError;620621/// Performs the conversion.622#[stable(feature ="try_from", since ="1.34.0")]623fntry_into(self) ->Result<T,Self::Error>;624}625626/// Simple and safe type conversions that may fail in a controlled627/// way under some circumstances. It is the reciprocal of [`TryInto`].628///629/// This is useful when you are doing a type conversion that may630/// trivially succeed but may also need special handling.631/// For example, there is no way to convert an [`i64`] into an [`i32`]632/// using the [`From`] trait, because an [`i64`] may contain a value633/// that an [`i32`] cannot represent and so the conversion would lose data.634/// This might be handled by truncating the [`i64`] to an [`i32`] or by635/// simply returning [`i32::MAX`], or by some other method. The [`From`]636/// trait is intended for perfect conversions, so the `TryFrom` trait637/// informs the programmer when a type conversion could go bad and lets638/// them decide how to handle it.639///640/// # Generic Implementations641///642/// - `TryFrom<T> for U` implies [`TryInto`]`<U> for T`643/// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`644/// is implemented and cannot fail -- the associated `Error` type for645/// calling `T::try_from()` on a value of type `T` is [`Infallible`].646/// When the [`!`] type is stabilized [`Infallible`] and [`!`] will be647/// equivalent.648///649/// Prefer using [`TryInto`] over [`TryFrom`] when specifying trait bounds on a generic function650/// to ensure that types that only implement [`TryInto`] can be used as well.651///652/// `TryFrom<T>` can be implemented as follows:653///654/// ```655/// struct GreaterThanZero(i32);656///657/// impl TryFrom<i32> for GreaterThanZero {658/// type Error = &'static str;659///660/// fn try_from(value: i32) -> Result<Self, Self::Error> {661/// if value <= 0 {662/// Err("GreaterThanZero only accepts values greater than zero!")663/// } else {664/// Ok(GreaterThanZero(value))665/// }666/// }667/// }668/// ```669///670/// # Examples671///672/// As described, [`i32`] implements `TryFrom<`[`i64`]`>`:673///674/// ```675/// let big_number = 1_000_000_000_000i64;676/// // Silently truncates `big_number`, requires detecting677/// // and handling the truncation after the fact.678/// let smaller_number = big_number as i32;679/// assert_eq!(smaller_number, -727379968);680///681/// // Returns an error because `big_number` is too big to682/// // fit in an `i32`.683/// let try_smaller_number = i32::try_from(big_number);684/// assert!(try_smaller_number.is_err());685///686/// // Returns `Ok(3)`.687/// let try_successful_smaller_number = i32::try_from(3);688/// assert!(try_successful_smaller_number.is_ok());689/// ```690///691/// [`try_from`]: TryFrom::try_from692#[rustc_diagnostic_item ="TryFrom"]693#[stable(feature ="try_from", since ="1.34.0")]694#[rustc_const_unstable(feature ="const_from", issue ="143773")]695#[const_trait]696pub traitTryFrom<T>: Sized {697/// The type returned in the event of a conversion error.698#[stable(feature ="try_from", since ="1.34.0")]699typeError;700701/// Performs the conversion.702#[stable(feature ="try_from", since ="1.34.0")]703 #[rustc_diagnostic_item ="try_from_fn"]704fntry_from(value: T) ->Result<Self,Self::Error>;705}706707////////////////////////////////////////////////////////////////////////////////708// GENERIC IMPLS709////////////////////////////////////////////////////////////////////////////////710711// As lifts over &712#[stable(feature ="rust1", since ="1.0.0")]713impl<T: PointeeSized, U: PointeeSized> AsRef<U>for&T714where715T: AsRef<U>,716{717#[inline]718fnas_ref(&self) ->&U {719 <TasAsRef<U>>::as_ref(*self)720 }721}722723// As lifts over &mut724#[stable(feature ="rust1", since ="1.0.0")]725impl<T: PointeeSized, U: PointeeSized> AsRef<U>for&mutT726where727T: AsRef<U>,728{729#[inline]730fnas_ref(&self) ->&U {731 <TasAsRef<U>>::as_ref(*self)732 }733}734735// FIXME (#45742): replace the above impls for &/&mut with the following more general one:736// // As lifts over Deref737// impl<D: ?Sized + Deref<Target: AsRef<U>>, U: ?Sized> AsRef<U> for D {738// fn as_ref(&self) -> &U {739// self.deref().as_ref()740// }741// }742743// AsMut lifts over &mut744#[stable(feature ="rust1", since ="1.0.0")]745impl<T: PointeeSized, U: PointeeSized> AsMut<U>for&mutT746where747T: AsMut<U>,748{749#[inline]750fnas_mut(&mutself) ->&mutU {751 (*self).as_mut()752 }753}754755// FIXME (#45742): replace the above impl for &mut with the following more general one:756// // AsMut lifts over DerefMut757// impl<D: ?Sized + Deref<Target: AsMut<U>>, U: ?Sized> AsMut<U> for D {758// fn as_mut(&mut self) -> &mut U {759// self.deref_mut().as_mut()760// }761// }762763// From implies Into764#[stable(feature ="rust1", since ="1.0.0")]765#[rustc_const_unstable(feature ="const_from", issue ="143773")]766impl<T, U>constInto<U>forT767where768U: ~constFrom<T>,769{770/// Calls `U::from(self)`.771 ///772 /// That is, this conversion is whatever the implementation of773 /// <code>[From]<T> for U</code> chooses to do.774#[inline]775 #[track_caller]776fninto(self) -> U {777 U::from(self)778 }779}780781// From (and thus Into) is reflexive782#[stable(feature ="rust1", since ="1.0.0")]783#[rustc_const_unstable(feature ="const_from", issue ="143773")]784impl<T>constFrom<T>forT {785/// Returns the argument unchanged.786#[inline(always)]787fnfrom(t: T) -> T {788 t789 }790}791792/// **Stability note:** This impl does not yet exist, but we are793/// "reserving space" to add it in the future. See794/// [rust-lang/rust#64715][#64715] for details.795///796/// [#64715]: https://github.com/rust-lang/rust/issues/64715797#[stable(feature ="convert_infallible", since ="1.34.0")]798#[rustc_reservation_impl ="permitting this impl would forbid us from adding \799 `impl<T> From<!> for T` later; see rust-lang/rust#64715 for details"]800#[rustc_const_unstable(feature ="const_from", issue ="143773")]801impl<T>constFrom<!>forT {802fnfrom(t: !) -> T {803 t804 }805}806807// TryFrom implies TryInto808#[stable(feature ="try_from", since ="1.34.0")]809#[rustc_const_unstable(feature ="const_from", issue ="143773")]810impl<T, U>constTryInto<U>forT811where812U: ~constTryFrom<T>,813{814typeError = U::Error;815816#[inline]817fntry_into(self) ->Result<U, U::Error> {818 U::try_from(self)819 }820}821822// Infallible conversions are semantically equivalent to fallible conversions823// with an uninhabited error type.824#[stable(feature ="try_from", since ="1.34.0")]825#[rustc_const_unstable(feature ="const_from", issue ="143773")]826impl<T, U>constTryFrom<U>forT827where828U: ~constInto<T>,829{830typeError = Infallible;831832#[inline]833fntry_from(value: U) ->Result<Self,Self::Error> {834Ok(U::into(value))835 }836}837838////////////////////////////////////////////////////////////////////////////////839// CONCRETE IMPLS840////////////////////////////////////////////////////////////////////////////////841842#[stable(feature ="rust1", since ="1.0.0")]843impl<T> AsRef<[T]>for[T] {844#[inline(always)]845fnas_ref(&self) ->&[T] {846self847}848}849850#[stable(feature ="rust1", since ="1.0.0")]851impl<T> AsMut<[T]>for[T] {852#[inline(always)]853fnas_mut(&mutself) ->&mut[T] {854self855}856}857858#[stable(feature ="rust1", since ="1.0.0")]859implAsRef<str>forstr {860#[inline(always)]861fnas_ref(&self) ->&str {862self863}864}865866#[stable(feature ="as_mut_str_for_str", since ="1.51.0")]867implAsMut<str>forstr {868#[inline(always)]869fnas_mut(&mutself) ->&mutstr {870self871}872}873874////////////////////////////////////////////////////////////////////////////////875// THE NO-ERROR ERROR TYPE876////////////////////////////////////////////////////////////////////////////////877878/// The error type for errors that can never happen.879///880/// Since this enum has no variant, a value of this type can never actually exist.881/// This can be useful for generic APIs that use [`Result`] and parameterize the error type,882/// to indicate that the result is always [`Ok`].883///884/// For example, the [`TryFrom`] trait (conversion that returns a [`Result`])885/// has a blanket implementation for all types where a reverse [`Into`] implementation exists.886///887/// ```ignore (illustrates std code, duplicating the impl in a doctest would be an error)888/// impl<T, U> TryFrom<U> for T where U: Into<T> {889/// type Error = Infallible;890///891/// fn try_from(value: U) -> Result<Self, Infallible> {892/// Ok(U::into(value)) // Never returns `Err`893/// }894/// }895/// ```896///897/// # Future compatibility898///899/// This enum has the same role as [the `!` “never” type][never],900/// which is unstable in this version of Rust.901/// When `!` is stabilized, we plan to make `Infallible` a type alias to it:902///903/// ```ignore (illustrates future std change)904/// pub type Infallible = !;905/// ```906///907/// … and eventually deprecate `Infallible`.908///909/// However there is one case where `!` syntax can be used910/// before `!` is stabilized as a full-fledged type: in the position of a function’s return type.911/// Specifically, it is possible to have implementations for two different function pointer types:912///913/// ```914/// trait MyTrait {}915/// impl MyTrait for fn() -> ! {}916/// impl MyTrait for fn() -> std::convert::Infallible {}917/// ```918///919/// With `Infallible` being an enum, this code is valid.920/// However when `Infallible` becomes an alias for the never type,921/// the two `impl`s will start to overlap922/// and therefore will be disallowed by the language’s trait coherence rules.923#[stable(feature ="convert_infallible", since ="1.34.0")]924#[derive(Copy)]925pub enumInfallible {}926927#[stable(feature ="convert_infallible", since ="1.34.0")]928implCloneforInfallible {929fnclone(&self) -> Infallible {930match*self{}931 }932}933934#[stable(feature ="convert_infallible", since ="1.34.0")]935implfmt::DebugforInfallible {936fnfmt(&self,_:&mutfmt::Formatter<'_>) -> fmt::Result {937match*self{}938 }939}940941#[stable(feature ="convert_infallible", since ="1.34.0")]942implfmt::DisplayforInfallible {943fnfmt(&self,_:&mutfmt::Formatter<'_>) -> fmt::Result {944match*self{}945 }946}947948#[stable(feature ="str_parse_error2", since ="1.8.0")]949implErrorforInfallible {950fndescription(&self) ->&str {951match*self{}952 }953}954955#[stable(feature ="convert_infallible", since ="1.34.0")]956implPartialEqforInfallible {957fneq(&self,_:&Infallible) -> bool {958match*self{}959 }960}961962#[stable(feature ="convert_infallible", since ="1.34.0")]963implEqforInfallible {}964965#[stable(feature ="convert_infallible", since ="1.34.0")]966implPartialOrdforInfallible {967fnpartial_cmp(&self, _other:&Self) ->Option<crate::cmp::Ordering> {968match*self{}969 }970}971972#[stable(feature ="convert_infallible", since ="1.34.0")]973implOrdforInfallible {974fncmp(&self, _other:&Self) ->crate::cmp::Ordering {975match*self{}976 }977}978979#[stable(feature ="convert_infallible", since ="1.34.0")]980implFrom<!>forInfallible {981#[inline]982fnfrom(x: !) ->Self{983 x984 }985}986987#[stable(feature ="convert_infallible_hash", since ="1.44.0")]988implHashforInfallible {989fnhash<H: Hasher>(&self,_:&mutH) {990match*self{}991 }992}