core/convert/
mod.rs

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 conversions
7//! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions
8//! - Implement the [`From`] trait for consuming value-to-value conversions
9//! - Implement the [`Into`] trait for consuming value-to-value conversions to types
10//!   outside the current crate
11//! - 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 to
15//! 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`] or
18//! [`TryFrom<T>`][`TryFrom`] rather than [`Into<U>`][`Into`] or [`TryInto<U>`][`TryInto`],
19//! as [`From`] and [`TryFrom`] provide greater flexibility and offer
20//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a
21//! blanket implementation in the standard library. When targeting a version prior to Rust 1.41, it
22//! may be necessary to implement [`Into`] or [`TryInto`] directly when converting to a type
23//! outside the current crate.
24//!
25//! # Generic Implementations
26//!
27//! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference
28//!   (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 can
32//!   `into` themselves and `from` themselves
33//!
34//! See each trait for usage examples.
35
36#![stable(feature = "rust1", since = "1.0.0")]
37
38use crate::error::Error;
39use crate::fmt;
40use crate::hash::{Hash, Hasher};
41
42mod num;
43
44#[unstable(feature = "convert_float_to_int", issue = "67057")]
45pub use num::FloatToInt;
46
47/// The identity function.
48///
49/// Two things are important to note about this function:
50///
51/// - It is not always equivalent to a closure like `|x| x`, since the
52///   closure may coerce `x` into a different type.
53///
54/// - It moves the input `x` passed to the function.
55///
56/// While it might seem strange to have a function that just returns back the
57/// input, there are some interesting uses.
58///
59/// # Examples
60///
61/// Using `identity` to do nothing in a sequence of other, interesting,
62/// functions:
63///
64/// ```rust
65/// use std::convert::identity;
66///
67/// fn manipulation(x: u32) -> u32 {
68///     // Let's pretend that adding one is an interesting function.
69///     x + 1
70/// }
71///
72/// let _arr = &[identity, manipulation];
73/// ```
74///
75/// Using `identity` as a "do nothing" base case in a conditional:
76///
77/// ```rust
78/// use std::convert::identity;
79///
80/// # let condition = true;
81/// #
82/// # fn manipulation(x: u32) -> u32 { x + 1 }
83/// #
84/// let do_stuff = if condition { manipulation } else { identity };
85///
86/// // Do more interesting stuff...
87///
88/// let _results = do_stuff(42);
89/// ```
90///
91/// Using `identity` to keep the `Some` variants of an iterator of `Option<T>`:
92///
93/// ```rust
94/// use std::convert::identity;
95///
96/// let iter = [Some(1), None, Some(3)].into_iter();
97/// let filtered = iter.filter_map(identity).collect::<Vec<_>>();
98/// assert_eq!(vec![1, 3], filtered);
99/// ```
100#[stable(feature = "convert_id", since = "1.33.0")]
101#[rustc_const_stable(feature = "const_identity", since = "1.33.0")]
102#[inline(always)]
103#[rustc_diagnostic_item = "convert_identity"]
104pub const fn identity<T>(x: T) -> T {
105    x
106}
107
108/// Used to do a cheap reference-to-reference conversion.
109///
110/// This trait is similar to [`AsMut`] which is used for converting between mutable references.
111/// If you need to do a costly conversion it is better to implement [`From`] with type
112/// `&T` or write a custom function.
113///
114/// # Relation to `Borrow`
115///
116/// `AsRef` has the same signature as [`Borrow`], but [`Borrow`] is different in a few aspects:
117///
118/// - Unlike `AsRef`, [`Borrow`] has a blanket impl for any `T`, and can be used to accept either
119///   a reference or a value. (See also note on `AsRef`'s reflexibility below.)
120/// - [`Borrow`] also requires that [`Hash`], [`Eq`] and [`Ord`] for a borrowed value are
121///   equivalent to those of the owned value. For this reason, if you want to
122///   borrow only a single field of a struct you can implement `AsRef`, but not [`Borrow`].
123///
124/// **Note: This trait must not fail**. If the conversion can fail, use a
125/// dedicated method which returns an [`Option<T>`] or a [`Result<T, E>`].
126///
127/// # Generic Implementations
128///
129/// `AsRef` auto-dereferences if the inner type is a reference or a mutable reference
130/// (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`).
131///
132/// Note that due to historic reasons, the above currently does not hold generally for all
133/// [dereferenceable types], e.g. `foo.as_ref()` will *not* work the same as
134/// `Box::new(foo).as_ref()`. Instead, many smart pointers provide an `as_ref` implementation which
135/// simply returns a reference to the [pointed-to value] (but do not perform a cheap
136/// reference-to-reference conversion for that value). However, [`AsRef::as_ref`] should not be
137/// used for the sole purpose of dereferencing; instead ['`Deref` coercion'] can be used:
138///
139/// [dereferenceable types]: core::ops::Deref
140/// [pointed-to value]: core::ops::Deref::Target
141/// ['`Deref` coercion']: core::ops::Deref#deref-coercion
142///
143/// ```
144/// let x = Box::new(5i32);
145/// // Avoid this:
146/// // let y: &i32 = x.as_ref();
147/// // Better just write:
148/// let y: &i32 = &x;
149/// ```
150///
151/// Types which implement [`Deref`] should consider implementing `AsRef<T>` as follows:
152///
153/// [`Deref`]: core::ops::Deref
154///
155/// ```
156/// # use core::ops::Deref;
157/// # struct SomeType;
158/// # impl Deref for SomeType {
159/// #     type Target = [u8];
160/// #     fn deref(&self) -> &[u8] {
161/// #         &[]
162/// #     }
163/// # }
164/// impl<T> AsRef<T> for SomeType
165/// where
166///     T: ?Sized,
167///     <SomeType as Deref>::Target: AsRef<T>,
168/// {
169///     fn as_ref(&self) -> &T {
170///         self.deref().as_ref()
171///     }
172/// }
173/// ```
174///
175/// # Reflexivity
176///
177/// Ideally, `AsRef` would be reflexive, i.e. there would be an `impl<T: ?Sized> AsRef<T> for T`
178/// with [`as_ref`] simply returning its argument unchanged.
179/// Such a blanket implementation is currently *not* provided due to technical restrictions of
180/// Rust's type system (it would be overlapping with another existing blanket implementation for
181/// `&T where T: AsRef<U>` which allows `AsRef` to auto-dereference, see "Generic Implementations"
182/// above).
183///
184/// [`as_ref`]: AsRef::as_ref
185///
186/// A trivial implementation of `AsRef<T> for T` must be added explicitly for a particular type `T`
187/// where needed or desired. Note, however, that not all types from `std` contain such an
188/// implementation, and those cannot be added by external code due to orphan rules.
189///
190/// # Examples
191///
192/// By using trait bounds we can accept arguments of different types as long as they can be
193/// converted to the specified type `T`.
194///
195/// For example: By creating a generic function that takes an `AsRef<str>` we express that we
196/// want to accept all references that can be converted to [`&str`] as an argument.
197/// Since both [`String`] and [`&str`] implement `AsRef<str>` we can accept both as input argument.
198///
199/// [`&str`]: primitive@str
200/// [`Borrow`]: crate::borrow::Borrow
201/// [`Eq`]: crate::cmp::Eq
202/// [`Ord`]: crate::cmp::Ord
203/// [`String`]: ../../std/string/struct.String.html
204///
205/// ```
206/// fn is_hello<T: AsRef<str>>(s: T) {
207///    assert_eq!("hello", s.as_ref());
208/// }
209///
210/// let s = "hello";
211/// is_hello(s);
212///
213/// let s = "hello".to_string();
214/// is_hello(s);
215/// ```
216#[stable(feature = "rust1", since = "1.0.0")]
217#[rustc_diagnostic_item = "AsRef"]
218pub trait AsRef<T: ?Sized> {
219    /// Converts this type into a shared reference of the (usually inferred) input type.
220    #[stable(feature = "rust1", since = "1.0.0")]
221    fn as_ref(&self) -> &T;
222}
223
224/// Used to do a cheap mutable-to-mutable reference conversion.
225///
226/// This trait is similar to [`AsRef`] but used for converting between mutable
227/// references. If you need to do a costly conversion it is better to
228/// implement [`From`] with type `&mut T` or write a custom function.
229///
230/// **Note: This trait must not fail**. If the conversion can fail, use a
231/// dedicated method which returns an [`Option<T>`] or a [`Result<T, E>`].
232///
233/// # Generic Implementations
234///
235/// `AsMut` auto-dereferences if the inner type is a mutable reference
236/// (e.g.: `foo.as_mut()` will work the same if `foo` has type `&mut Foo` or `&mut &mut Foo`).
237///
238/// Note that due to historic reasons, the above currently does not hold generally for all
239/// [mutably dereferenceable types], e.g. `foo.as_mut()` will *not* work the same as
240/// `Box::new(foo).as_mut()`. Instead, many smart pointers provide an `as_mut` implementation which
241/// simply returns a reference to the [pointed-to value] (but do not perform a cheap
242/// reference-to-reference conversion for that value). However, [`AsMut::as_mut`] should not be
243/// used for the sole purpose of mutable dereferencing; instead ['`Deref` coercion'] can be used:
244///
245/// [mutably dereferenceable types]: core::ops::DerefMut
246/// [pointed-to value]: core::ops::Deref::Target
247/// ['`Deref` coercion']: core::ops::DerefMut#mutable-deref-coercion
248///
249/// ```
250/// let mut x = Box::new(5i32);
251/// // Avoid this:
252/// // let y: &mut i32 = x.as_mut();
253/// // Better just write:
254/// let y: &mut i32 = &mut x;
255/// ```
256///
257/// Types which implement [`DerefMut`] should consider to add an implementation of `AsMut<T>` as
258/// follows:
259///
260/// [`DerefMut`]: core::ops::DerefMut
261///
262/// ```
263/// # use core::ops::{Deref, DerefMut};
264/// # struct SomeType;
265/// # impl Deref for SomeType {
266/// #     type Target = [u8];
267/// #     fn deref(&self) -> &[u8] {
268/// #         &[]
269/// #     }
270/// # }
271/// # impl DerefMut for SomeType {
272/// #     fn deref_mut(&mut self) -> &mut [u8] {
273/// #         &mut []
274/// #     }
275/// # }
276/// impl<T> AsMut<T> for SomeType
277/// where
278///     <SomeType as Deref>::Target: AsMut<T>,
279/// {
280///     fn as_mut(&mut self) -> &mut T {
281///         self.deref_mut().as_mut()
282///     }
283/// }
284/// ```
285///
286/// # Reflexivity
287///
288/// Ideally, `AsMut` would be reflexive, i.e. there would be an `impl<T: ?Sized> AsMut<T> for T`
289/// with [`as_mut`] simply returning its argument unchanged.
290/// Such a blanket implementation is currently *not* provided due to technical restrictions of
291/// Rust's type system (it would be overlapping with another existing blanket implementation for
292/// `&mut T where T: AsMut<U>` which allows `AsMut` to auto-dereference, see "Generic
293/// Implementations" above).
294///
295/// [`as_mut`]: AsMut::as_mut
296///
297/// A trivial implementation of `AsMut<T> for T` must be added explicitly for a particular type `T`
298/// where needed or desired. Note, however, that not all types from `std` contain such an
299/// implementation, and those cannot be added by external code due to orphan rules.
300///
301/// # Examples
302///
303/// Using `AsMut` as trait bound for a generic function, we can accept all mutable references that
304/// can be converted to type `&mut T`. Unlike [dereference], which has a single [target type],
305/// there can be multiple implementations of `AsMut` for a type. In particular, `Vec<T>` implements
306/// both `AsMut<Vec<T>>` and `AsMut<[T]>`.
307///
308/// In the following, the example functions `caesar` and `null_terminate` provide a generic
309/// interface which work with any type that can be converted by cheap mutable-to-mutable conversion
310/// into a byte slice (`[u8]`) or byte vector (`Vec<u8>`), respectively.
311///
312/// [dereference]: core::ops::DerefMut
313/// [target type]: core::ops::Deref::Target
314///
315/// ```
316/// struct Document {
317///     info: String,
318///     content: Vec<u8>,
319/// }
320///
321/// impl<T: ?Sized> AsMut<T> for Document
322/// where
323///     Vec<u8>: AsMut<T>,
324/// {
325///     fn as_mut(&mut self) -> &mut T {
326///         self.content.as_mut()
327///     }
328/// }
329///
330/// fn caesar<T: AsMut<[u8]>>(data: &mut T, key: u8) {
331///     for byte in data.as_mut() {
332///         *byte = byte.wrapping_add(key);
333///     }
334/// }
335///
336/// fn null_terminate<T: AsMut<Vec<u8>>>(data: &mut T) {
337///     // Using a non-generic inner function, which contains most of the
338///     // functionality, helps to minimize monomorphization overhead.
339///     fn doit(data: &mut Vec<u8>) {
340///         let len = data.len();
341///         if len == 0 || data[len-1] != 0 {
342///             data.push(0);
343///         }
344///     }
345///     doit(data.as_mut());
346/// }
347///
348/// fn main() {
349///     let mut v: Vec<u8> = vec![1, 2, 3];
350///     caesar(&mut v, 5);
351///     assert_eq!(v, [6, 7, 8]);
352///     null_terminate(&mut v);
353///     assert_eq!(v, [6, 7, 8, 0]);
354///     let mut doc = Document {
355///         info: String::from("Example"),
356///         content: vec![17, 19, 8],
357///     };
358///     caesar(&mut doc, 1);
359///     assert_eq!(doc.content, [18, 20, 9]);
360///     null_terminate(&mut doc);
361///     assert_eq!(doc.content, [18, 20, 9, 0]);
362/// }
363/// ```
364///
365/// Note, however, that APIs don't need to be generic. In many cases taking a `&mut [u8]` or
366/// `&mut Vec<u8>`, for example, is the better choice (callers need to pass the correct type then).
367#[stable(feature = "rust1", since = "1.0.0")]
368#[rustc_diagnostic_item = "AsMut"]
369pub trait AsMut<T: ?Sized> {
370    /// Converts this type into a mutable reference of the (usually inferred) input type.
371    #[stable(feature = "rust1", since = "1.0.0")]
372    fn as_mut(&mut self) -> &mut T;
373}
374
375/// A value-to-value conversion that consumes the input value. The
376/// opposite of [`From`].
377///
378/// One should avoid implementing [`Into`] and implement [`From`] instead.
379/// Implementing [`From`] automatically provides one with an implementation of [`Into`]
380/// thanks to the blanket implementation in the standard library.
381///
382/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function
383/// to ensure that types that only implement [`Into`] can be used as well.
384///
385/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`].
386///
387/// # Generic Implementations
388///
389/// - [`From`]`<T> for U` implies `Into<U> for T`
390/// - [`Into`] is reflexive, which means that `Into<T> for T` is implemented
391///
392/// # Implementing [`Into`] for conversions to external types in old versions of Rust
393///
394/// Prior to Rust 1.41, if the destination type was not part of the current crate
395/// then you couldn't implement [`From`] directly.
396/// For example, take this code:
397///
398/// ```
399/// # #![allow(non_local_definitions)]
400/// struct Wrapper<T>(Vec<T>);
401/// impl<T> From<Wrapper<T>> for Vec<T> {
402///     fn from(w: Wrapper<T>) -> Vec<T> {
403///         w.0
404///     }
405/// }
406/// ```
407/// This will fail to compile in older versions of the language because Rust's orphaning rules
408/// used to be a little bit more strict. To bypass this, you could implement [`Into`] directly:
409///
410/// ```
411/// struct Wrapper<T>(Vec<T>);
412/// impl<T> Into<Vec<T>> for Wrapper<T> {
413///     fn into(self) -> Vec<T> {
414///         self.0
415///     }
416/// }
417/// ```
418///
419/// It is important to understand that [`Into`] does not provide a [`From`] implementation
420/// (as [`From`] does with [`Into`]). Therefore, you should always try to implement [`From`]
421/// and then fall back to [`Into`] if [`From`] can't be implemented.
422///
423/// # Examples
424///
425/// [`String`] implements [`Into`]`<`[`Vec`]`<`[`u8`]`>>`:
426///
427/// In order to express that we want a generic function to take all arguments that can be
428/// converted to a specified type `T`, we can use a trait bound of [`Into`]`<T>`.
429/// For example: The function `is_hello` takes all arguments that can be converted into a
430/// [`Vec`]`<`[`u8`]`>`.
431///
432/// ```
433/// fn is_hello<T: Into<Vec<u8>>>(s: T) {
434///    let bytes = b"hello".to_vec();
435///    assert_eq!(bytes, s.into());
436/// }
437///
438/// let s = "hello".to_string();
439/// is_hello(s);
440/// ```
441///
442/// [`String`]: ../../std/string/struct.String.html
443/// [`Vec`]: ../../std/vec/struct.Vec.html
444#[rustc_diagnostic_item = "Into"]
445#[stable(feature = "rust1", since = "1.0.0")]
446#[doc(search_unbox)]
447pub trait Into<T>: Sized {
448    /// Converts this type into the (usually inferred) input type.
449    #[must_use]
450    #[stable(feature = "rust1", since = "1.0.0")]
451    fn into(self) -> T;
452}
453
454/// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of
455/// [`Into`].
456///
457/// One should always prefer implementing `From` over [`Into`]
458/// because implementing `From` automatically provides one with an implementation of [`Into`]
459/// thanks to the blanket implementation in the standard library.
460///
461/// Only implement [`Into`] when targeting a version prior to Rust 1.41 and converting to a type
462/// outside the current crate.
463/// `From` was not able to do these types of conversions in earlier versions because of Rust's
464/// orphaning rules.
465/// See [`Into`] for more details.
466///
467/// Prefer using [`Into`] over using `From` when specifying trait bounds on a generic function.
468/// This way, types that directly implement [`Into`] can be used as arguments as well.
469///
470/// The `From` trait is also very useful when performing error handling. When constructing a function
471/// that is capable of failing, the return type will generally be of the form `Result<T, E>`.
472/// `From` simplifies error handling by allowing a function to return a single error type
473/// that encapsulates multiple error types. See the "Examples" section and [the book][book] for more
474/// details.
475///
476/// **Note: This trait must not fail**. The `From` trait is intended for perfect conversions.
477/// If the conversion can fail or is not perfect, use [`TryFrom`].
478///
479/// # Generic Implementations
480///
481/// - `From<T> for U` implies [`Into`]`<U> for T`
482/// - `From` is reflexive, which means that `From<T> for T` is implemented
483///
484/// # When to implement `From`
485///
486/// While there's no technical restrictions on which conversions can be done using
487/// a `From` implementation, the general expectation is that the conversions
488/// should typically be restricted as follows:
489///
490/// * The conversion is *infallible*: if the conversion can fail, use [`TryFrom`]
491///   instead; don't provide a `From` impl that panics.
492///
493/// * The conversion is *lossless*: semantically, it should not lose or discard
494///   information. For example, `i32: From<u16>` exists, where the original
495///   value can be recovered using `u16: TryFrom<i32>`.  And `String: From<&str>`
496///   exists, where you can get something equivalent to the original value via
497///   `Deref`.  But `From` cannot be used to convert from `u32` to `u16`, since
498///   that cannot succeed in a lossless way.  (There's some wiggle room here for
499///   information not considered semantically relevant.  For example,
500///   `Box<[T]>: From<Vec<T>>` exists even though it might not preserve capacity,
501///   like how two vectors can be equal despite differing capacities.)
502///
503/// * The conversion is *value-preserving*: the conceptual kind and meaning of
504///   the resulting value is the same, even though the Rust type and technical
505///   representation might be different.  For example `-1_i8 as u8` is *lossless*,
506///   since `as` casting back can recover the original value, but that conversion
507///   is *not* available via `From` because `-1` and `255` are different conceptual
508///   values (despite being identical bit patterns technically).  But
509///   `f32: From<i16>` *is* available because `1_i16` and `1.0_f32` are conceptually
510///   the same real number (despite having very different bit patterns technically).
511///   `String: From<char>` is available because they're both *text*, but
512///   `String: From<u32>` is *not* available, since `1` (a number) and `"1"`
513///   (text) are too different.  (Converting values to text is instead covered
514///   by the [`Display`](crate::fmt::Display) trait.)
515///
516/// * The conversion is *obvious*: it's the only reasonable conversion between
517///   the two types.  Otherwise it's better to have it be a named method or
518///   constructor, like how [`str::as_bytes`] is a method and how integers have
519///   methods like [`u32::from_ne_bytes`], [`u32::from_le_bytes`], and
520///   [`u32::from_be_bytes`], none of which are `From` implementations.  Whereas
521///   there's only one reasonable way to wrap an [`Ipv6Addr`](crate::net::Ipv6Addr)
522///   into an [`IpAddr`](crate::net::IpAddr), thus `IpAddr: From<Ipv6Addr>` exists.
523///
524/// # Examples
525///
526/// [`String`] implements `From<&str>`:
527///
528/// An explicit conversion from a `&str` to a String is done as follows:
529///
530/// ```
531/// let string = "hello".to_string();
532/// let other_string = String::from("hello");
533///
534/// assert_eq!(string, other_string);
535/// ```
536///
537/// While performing error handling it is often useful to implement `From` for your own error type.
538/// By converting underlying error types to our own custom error type that encapsulates the
539/// underlying error type, we can return a single error type without losing information on the
540/// underlying cause. The '?' operator automatically converts the underlying error type to our
541/// custom error type with `From::from`.
542///
543/// ```
544/// use std::fs;
545/// use std::io;
546/// use std::num;
547///
548/// enum CliError {
549///     IoError(io::Error),
550///     ParseError(num::ParseIntError),
551/// }
552///
553/// impl From<io::Error> for CliError {
554///     fn from(error: io::Error) -> Self {
555///         CliError::IoError(error)
556///     }
557/// }
558///
559/// impl From<num::ParseIntError> for CliError {
560///     fn from(error: num::ParseIntError) -> Self {
561///         CliError::ParseError(error)
562///     }
563/// }
564///
565/// fn open_and_parse_file(file_name: &str) -> Result<i32, CliError> {
566///     let mut contents = fs::read_to_string(&file_name)?;
567///     let num: i32 = contents.trim().parse()?;
568///     Ok(num)
569/// }
570/// ```
571///
572/// [`String`]: ../../std/string/struct.String.html
573/// [`from`]: From::from
574/// [book]: ../../book/ch09-00-error-handling.html
575#[rustc_diagnostic_item = "From"]
576#[stable(feature = "rust1", since = "1.0.0")]
577#[rustc_on_unimplemented(on(
578    all(_Self = "&str", T = "alloc::string::String"),
579    note = "to coerce a `{T}` into a `{Self}`, use `&*` as a prefix",
580))]
581#[doc(search_unbox)]
582pub trait From<T>: Sized {
583    /// Converts to this type from the input type.
584    #[rustc_diagnostic_item = "from_fn"]
585    #[must_use]
586    #[stable(feature = "rust1", since = "1.0.0")]
587    fn from(value: T) -> Self;
588}
589
590/// An attempted conversion that consumes `self`, which may or may not be
591/// expensive.
592///
593/// Library authors should usually not directly implement this trait,
594/// but should prefer implementing the [`TryFrom`] trait, which offers
595/// greater flexibility and provides an equivalent `TryInto`
596/// implementation for free, thanks to a blanket implementation in the
597/// standard library. For more information on this, see the
598/// documentation for [`Into`].
599///
600/// # Implementing `TryInto`
601///
602/// This suffers the same restrictions and reasoning as implementing
603/// [`Into`], see there for details.
604#[rustc_diagnostic_item = "TryInto"]
605#[stable(feature = "try_from", since = "1.34.0")]
606pub trait TryInto<T>: Sized {
607    /// The type returned in the event of a conversion error.
608    #[stable(feature = "try_from", since = "1.34.0")]
609    type Error;
610
611    /// Performs the conversion.
612    #[stable(feature = "try_from", since = "1.34.0")]
613    fn try_into(self) -> Result<T, Self::Error>;
614}
615
616/// Simple and safe type conversions that may fail in a controlled
617/// way under some circumstances. It is the reciprocal of [`TryInto`].
618///
619/// This is useful when you are doing a type conversion that may
620/// trivially succeed but may also need special handling.
621/// For example, there is no way to convert an [`i64`] into an [`i32`]
622/// using the [`From`] trait, because an [`i64`] may contain a value
623/// that an [`i32`] cannot represent and so the conversion would lose data.
624/// This might be handled by truncating the [`i64`] to an [`i32`] or by
625/// simply returning [`i32::MAX`], or by some other method.  The [`From`]
626/// trait is intended for perfect conversions, so the `TryFrom` trait
627/// informs the programmer when a type conversion could go bad and lets
628/// them decide how to handle it.
629///
630/// # Generic Implementations
631///
632/// - `TryFrom<T> for U` implies [`TryInto`]`<U> for T`
633/// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`
634/// is implemented and cannot fail -- the associated `Error` type for
635/// calling `T::try_from()` on a value of type `T` is [`Infallible`].
636/// When the [`!`] type is stabilized [`Infallible`] and [`!`] will be
637/// equivalent.
638///
639/// `TryFrom<T>` can be implemented as follows:
640///
641/// ```
642/// struct GreaterThanZero(i32);
643///
644/// impl TryFrom<i32> for GreaterThanZero {
645///     type Error = &'static str;
646///
647///     fn try_from(value: i32) -> Result<Self, Self::Error> {
648///         if value <= 0 {
649///             Err("GreaterThanZero only accepts values greater than zero!")
650///         } else {
651///             Ok(GreaterThanZero(value))
652///         }
653///     }
654/// }
655/// ```
656///
657/// # Examples
658///
659/// As described, [`i32`] implements `TryFrom<`[`i64`]`>`:
660///
661/// ```
662/// let big_number = 1_000_000_000_000i64;
663/// // Silently truncates `big_number`, requires detecting
664/// // and handling the truncation after the fact.
665/// let smaller_number = big_number as i32;
666/// assert_eq!(smaller_number, -727379968);
667///
668/// // Returns an error because `big_number` is too big to
669/// // fit in an `i32`.
670/// let try_smaller_number = i32::try_from(big_number);
671/// assert!(try_smaller_number.is_err());
672///
673/// // Returns `Ok(3)`.
674/// let try_successful_smaller_number = i32::try_from(3);
675/// assert!(try_successful_smaller_number.is_ok());
676/// ```
677///
678/// [`try_from`]: TryFrom::try_from
679#[rustc_diagnostic_item = "TryFrom"]
680#[stable(feature = "try_from", since = "1.34.0")]
681pub trait TryFrom<T>: Sized {
682    /// The type returned in the event of a conversion error.
683    #[stable(feature = "try_from", since = "1.34.0")]
684    type Error;
685
686    /// Performs the conversion.
687    #[stable(feature = "try_from", since = "1.34.0")]
688    #[rustc_diagnostic_item = "try_from_fn"]
689    fn try_from(value: T) -> Result<Self, Self::Error>;
690}
691
692////////////////////////////////////////////////////////////////////////////////
693// GENERIC IMPLS
694////////////////////////////////////////////////////////////////////////////////
695
696// As lifts over &
697#[stable(feature = "rust1", since = "1.0.0")]
698impl<T: ?Sized, U: ?Sized> AsRef<U> for &T
699where
700    T: AsRef<U>,
701{
702    #[inline]
703    fn as_ref(&self) -> &U {
704        <T as AsRef<U>>::as_ref(*self)
705    }
706}
707
708// As lifts over &mut
709#[stable(feature = "rust1", since = "1.0.0")]
710impl<T: ?Sized, U: ?Sized> AsRef<U> for &mut T
711where
712    T: AsRef<U>,
713{
714    #[inline]
715    fn as_ref(&self) -> &U {
716        <T as AsRef<U>>::as_ref(*self)
717    }
718}
719
720// FIXME (#45742): replace the above impls for &/&mut with the following more general one:
721// // As lifts over Deref
722// impl<D: ?Sized + Deref<Target: AsRef<U>>, U: ?Sized> AsRef<U> for D {
723//     fn as_ref(&self) -> &U {
724//         self.deref().as_ref()
725//     }
726// }
727
728// AsMut lifts over &mut
729#[stable(feature = "rust1", since = "1.0.0")]
730impl<T: ?Sized, U: ?Sized> AsMut<U> for &mut T
731where
732    T: AsMut<U>,
733{
734    #[inline]
735    fn as_mut(&mut self) -> &mut U {
736        (*self).as_mut()
737    }
738}
739
740// FIXME (#45742): replace the above impl for &mut with the following more general one:
741// // AsMut lifts over DerefMut
742// impl<D: ?Sized + Deref<Target: AsMut<U>>, U: ?Sized> AsMut<U> for D {
743//     fn as_mut(&mut self) -> &mut U {
744//         self.deref_mut().as_mut()
745//     }
746// }
747
748// From implies Into
749#[stable(feature = "rust1", since = "1.0.0")]
750impl<T, U> Into<U> for T
751where
752    U: From<T>,
753{
754    /// Calls `U::from(self)`.
755    ///
756    /// That is, this conversion is whatever the implementation of
757    /// <code>[From]&lt;T&gt; for U</code> chooses to do.
758    #[inline]
759    #[track_caller]
760    fn into(self) -> U {
761        U::from(self)
762    }
763}
764
765// From (and thus Into) is reflexive
766#[stable(feature = "rust1", since = "1.0.0")]
767impl<T> From<T> for T {
768    /// Returns the argument unchanged.
769    #[inline(always)]
770    fn from(t: T) -> T {
771        t
772    }
773}
774
775/// **Stability note:** This impl does not yet exist, but we are
776/// "reserving space" to add it in the future. See
777/// [rust-lang/rust#64715][#64715] for details.
778///
779/// [#64715]: https://github.com/rust-lang/rust/issues/64715
780#[stable(feature = "convert_infallible", since = "1.34.0")]
781#[rustc_reservation_impl = "permitting this impl would forbid us from adding \
782                            `impl<T> From<!> for T` later; see rust-lang/rust#64715 for details"]
783impl<T> From<!> for T {
784    fn from(t: !) -> T {
785        t
786    }
787}
788
789// TryFrom implies TryInto
790#[stable(feature = "try_from", since = "1.34.0")]
791impl<T, U> TryInto<U> for T
792where
793    U: TryFrom<T>,
794{
795    type Error = U::Error;
796
797    #[inline]
798    fn try_into(self) -> Result<U, U::Error> {
799        U::try_from(self)
800    }
801}
802
803// Infallible conversions are semantically equivalent to fallible conversions
804// with an uninhabited error type.
805#[stable(feature = "try_from", since = "1.34.0")]
806impl<T, U> TryFrom<U> for T
807where
808    U: Into<T>,
809{
810    type Error = Infallible;
811
812    #[inline]
813    fn try_from(value: U) -> Result<Self, Self::Error> {
814        Ok(U::into(value))
815    }
816}
817
818////////////////////////////////////////////////////////////////////////////////
819// CONCRETE IMPLS
820////////////////////////////////////////////////////////////////////////////////
821
822#[stable(feature = "rust1", since = "1.0.0")]
823impl<T> AsRef<[T]> for [T] {
824    #[inline(always)]
825    fn as_ref(&self) -> &[T] {
826        self
827    }
828}
829
830#[stable(feature = "rust1", since = "1.0.0")]
831impl<T> AsMut<[T]> for [T] {
832    #[inline(always)]
833    fn as_mut(&mut self) -> &mut [T] {
834        self
835    }
836}
837
838#[stable(feature = "rust1", since = "1.0.0")]
839impl AsRef<str> for str {
840    #[inline(always)]
841    fn as_ref(&self) -> &str {
842        self
843    }
844}
845
846#[stable(feature = "as_mut_str_for_str", since = "1.51.0")]
847impl AsMut<str> for str {
848    #[inline(always)]
849    fn as_mut(&mut self) -> &mut str {
850        self
851    }
852}
853
854////////////////////////////////////////////////////////////////////////////////
855// THE NO-ERROR ERROR TYPE
856////////////////////////////////////////////////////////////////////////////////
857
858/// The error type for errors that can never happen.
859///
860/// Since this enum has no variant, a value of this type can never actually exist.
861/// This can be useful for generic APIs that use [`Result`] and parameterize the error type,
862/// to indicate that the result is always [`Ok`].
863///
864/// For example, the [`TryFrom`] trait (conversion that returns a [`Result`])
865/// has a blanket implementation for all types where a reverse [`Into`] implementation exists.
866///
867/// ```ignore (illustrates std code, duplicating the impl in a doctest would be an error)
868/// impl<T, U> TryFrom<U> for T where U: Into<T> {
869///     type Error = Infallible;
870///
871///     fn try_from(value: U) -> Result<Self, Infallible> {
872///         Ok(U::into(value))  // Never returns `Err`
873///     }
874/// }
875/// ```
876///
877/// # Future compatibility
878///
879/// This enum has the same role as [the `!` “never” type][never],
880/// which is unstable in this version of Rust.
881/// When `!` is stabilized, we plan to make `Infallible` a type alias to it:
882///
883/// ```ignore (illustrates future std change)
884/// pub type Infallible = !;
885/// ```
886///
887/// … and eventually deprecate `Infallible`.
888///
889/// However there is one case where `!` syntax can be used
890/// before `!` is stabilized as a full-fledged type: in the position of a function’s return type.
891/// Specifically, it is possible to have implementations for two different function pointer types:
892///
893/// ```
894/// trait MyTrait {}
895/// impl MyTrait for fn() -> ! {}
896/// impl MyTrait for fn() -> std::convert::Infallible {}
897/// ```
898///
899/// With `Infallible` being an enum, this code is valid.
900/// However when `Infallible` becomes an alias for the never type,
901/// the two `impl`s will start to overlap
902/// and therefore will be disallowed by the language’s trait coherence rules.
903#[stable(feature = "convert_infallible", since = "1.34.0")]
904#[derive(Copy)]
905pub enum Infallible {}
906
907#[stable(feature = "convert_infallible", since = "1.34.0")]
908impl Clone for Infallible {
909    fn clone(&self) -> Infallible {
910        match *self {}
911    }
912}
913
914#[stable(feature = "convert_infallible", since = "1.34.0")]
915impl fmt::Debug for Infallible {
916    fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result {
917        match *self {}
918    }
919}
920
921#[stable(feature = "convert_infallible", since = "1.34.0")]
922impl fmt::Display for Infallible {
923    fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result {
924        match *self {}
925    }
926}
927
928#[stable(feature = "str_parse_error2", since = "1.8.0")]
929impl Error for Infallible {
930    fn description(&self) -> &str {
931        match *self {}
932    }
933}
934
935#[stable(feature = "convert_infallible", since = "1.34.0")]
936impl PartialEq for Infallible {
937    fn eq(&self, _: &Infallible) -> bool {
938        match *self {}
939    }
940}
941
942#[stable(feature = "convert_infallible", since = "1.34.0")]
943impl Eq for Infallible {}
944
945#[stable(feature = "convert_infallible", since = "1.34.0")]
946impl PartialOrd for Infallible {
947    fn partial_cmp(&self, _other: &Self) -> Option<crate::cmp::Ordering> {
948        match *self {}
949    }
950}
951
952#[stable(feature = "convert_infallible", since = "1.34.0")]
953impl Ord for Infallible {
954    fn cmp(&self, _other: &Self) -> crate::cmp::Ordering {
955        match *self {}
956    }
957}
958
959#[stable(feature = "convert_infallible", since = "1.34.0")]
960impl From<!> for Infallible {
961    #[inline]
962    fn from(x: !) -> Self {
963        x
964    }
965}
966
967#[stable(feature = "convert_infallible_hash", since = "1.44.0")]
968impl Hash for Infallible {
969    fn hash<H: Hasher>(&self, _: &mut H) {
970        match *self {}
971    }
972}
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy