+//! Traits for conversions between types.
//!
//! The traits in this module provide a way to convert from one type to another type.
-//!
//! Each trait serves a different purpose:
//!
//! - Implement the [`AsRef`] trait for cheap reference-to-reference conversions
pub const fn identity<T>(x: T) -> T { x }
/// Used to do a cheap reference-to-reference conversion.
+///
/// This trait is similar to [`AsMut`] which is used for converting between mutable references.
/// If you need to do a costly conversion it is better to implement [`From`] with type
/// `&T` or write a custom function.
///
///
/// `AsRef` is very similar to, but serves a slightly different purpose than [`Borrow`]:
+///
/// - Use `AsRef` when the goal is to simply convert into a reference
/// - Use `Borrow` when the goal is related to writing code that is agnostic to
/// the type of borrow and whether it is a reference or value
///
/// By using trait bounds we can accept arguments of different types as long as they can be
/// converted a the specified type `T`.
+///
/// For example: By creating a generic function that takes an `AsRef<str>` we express that we
/// want to accept all references that can be converted to &str as an argument.
/// Since both [`String`] and `&str` implement `AsRef<str>` we can accept both as input argument.
}
/// Used to do a cheap mutable-to-mutable reference conversion.
+///
/// This trait is similar to [`AsRef`] but used for converting between mutable
/// references. If you need to do a costly conversion it is better to
/// implement [`From`] with type `&mut T` or write a custom function.
///
/// One should only implement [`Into`] if a conversion to a type outside the current crate is
/// required. Otherwise one should always prefer implementing [`From`] over [`Into`] because
-/// implementing [`From`] automatically provides one with a implementation of [`Into`]
-/// thanks to the blanket implementation in the standard library.
-/// [`From`] cannot do these type of conversions because of Rust's orphaning rules.
+/// implementing [`From`] automatically provides one with a implementation of [`Into`] thanks to
+/// the blanket implementation in the standard library. [`From`] cannot do these type of
+/// conversions because of Rust's orphaning rules.
///
/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`].
///
/// - [`Into`]` is reflexive, which means that `Into<T> for T` is implemented
///
/// # Implementing `Into` for conversions to external types
+///
/// If the destination type is not part of the current crate
/// then you can't implement [`From`] directly.
/// For example, take this code:
/// It is important to understand that `Into` does not provide a [`From`] implementation
/// (as [`From`] does with `Into`). Therefore, you should always try to implement [`From`]
/// and then fall back to `Into` if [`From`] can't be implemented.
+///
/// Prefer using `Into` over [`From`] when specifying trait bounds on a generic function
/// to ensure that types that only implement `Into` can be used as well.
///
/// One should always prefer implementing [`From`] over [`Into`]
/// because implementing [`From`] automatically provides one with a implementation of [`Into`]
/// thanks to the blanket implementation in the standard library.
+///
/// Only implement [`Into`] if a conversion to a type outside the current crate is required.
/// [`From`] cannot do these type of conversions because of Rust's orphaning rules.
/// See [`Into`] for more details.
/// Prefer using [`Into`] over using [`From`] when specifying trait bounds on a generic function.
/// This way, types that directly implement [`Into`] can be used as arguments as well.
///
-/// The [`From`] is also very useful when performing error handling.
-/// When constructing a function that is capable of failing, the return type
-/// will generally be of the form `Result<T, E>`.
+/// The [`From`] is also very useful when performing error handling. When constructing a function
+/// that is capable of failing, the return type will generally be of the form `Result<T, E>`.
/// The `From` trait simplifies error handling by allowing a function to return a single error type
-/// that encapsulate multiple error types. See the "Examples" section
-/// and [the book][book] for more details.
+/// that encapsulate multiple error types. See the "Examples" section and [the book][book] for more
+/// details.
///
/// **Note: This trait must not fail**. If the conversion can fail, use [`TryFrom`].
///
/// assert_eq!(string, other_string);
/// ```
///
-/// While performing error handling it is often useful to implement `From`
-/// for your own error type. By converting underlying error types to our own custom error type
-/// that encapsulates the underlying error type, we can return a single error type
-/// without losing information on the underlying cause. The '?' operator automatically converts
-/// the underlying error type to our custom error type by calling `Into<CliError>::into`
-/// which is automatically provided when implementing `From`.
-/// The compiler then infers which implementation of `Into` should be used.
+/// While performing error handling it is often useful to implement `From` for your own error type.
+/// By converting underlying error types to our own custom error type that encapsulates the
+/// underlying error type, we can return a single error type without losing information on the
+/// underlying cause. The '?' operator automatically converts the underlying error type to our
+/// custom error type by calling `Into<CliError>::into` which is automatically provided when
+/// implementing `From`. The compiler then infers which implementation of `Into` should be used.
///
/// ```
/// use std::fs;
projects / rust.git / commitdiff