diff options
Diffstat (limited to 'src/libcore')
| -rw-r--r-- | src/libcore/convert.rs | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index b02b2a06b75..c207ad16595 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -17,6 +17,24 @@ //! Like many traits, these are often used as bounds for generic functions, to //! support arguments of multiple types. //! +//! - Impl the `As*` traits for reference-to-reference conversions +//! - Impl the `Into` trait when you want to consume the value in the conversion +//! - The `From` trait is the most flexible, usefull for values _and_ references conversions +//! +//! As a library writer, you should prefer implementing `From<T>` rather than +//! `Into<U>`, as `From` provides greater flexibility and offer the equivalent `Into` +//! implementation for free, thanks to a blanket implementation in the standard library. +//! +//! **Note: these traits must not fail**. If the conversion can fail, you must use a dedicated +//! method which return an `Option<T>` or a `Result<T, E>`. +//! +//! # Generic impl +//! +//! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference +//! - `From<U> for T` implies `Into<T> for U` +//! - `From` and `Into` are reflexive, which means that all types can `into()` +//! themselves and `from()` themselves +//! //! See each trait for usage examples. #![stable(feature = "rust1", since = "1.0.0")] @@ -30,6 +48,9 @@ use marker::Sized; /// /// [book]: ../../book/borrow-and-asref.html /// +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option<T>` or a `Result<T, E>`. +/// /// # Examples /// /// Both `String` and `&str` implement `AsRef<str>`: @@ -45,6 +66,12 @@ use marker::Sized; /// let s = "hello".to_string(); /// is_hello(s); /// ``` +/// +/// # Generic Impls +/// +/// - `AsRef` auto-dereference if the inner type is a reference or a mutable +/// reference (eg: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsRef<T: ?Sized> { /// Performs the conversion. @@ -53,6 +80,15 @@ pub trait AsRef<T: ?Sized> { } /// A cheap, mutable reference-to-mutable reference conversion. +/// +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option<T>` or a `Result<T, E>`. +/// +/// # Generic Impls +/// +/// - `AsMut` auto-dereference if the inner type is a reference or a mutable +/// reference (eg: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut<T: ?Sized> { /// Performs the conversion. @@ -62,6 +98,13 @@ pub trait AsMut<T: ?Sized> { /// A conversion that consumes `self`, which may or may not be expensive. /// +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option<T>` or a `Result<T, E>`. +/// +/// Library writer should not implement directly this trait, but should prefer the implementation +/// of the `From` trait, which offer greater flexibility and provide the equivalent `Into` +/// implementation for free, thanks to a blanket implementation in the standard library. +/// /// # Examples /// /// `String` implements `Into<Vec<u8>>`: @@ -75,6 +118,12 @@ pub trait AsMut<T: ?Sized> { /// let s = "hello".to_string(); /// is_hello(s); /// ``` +/// +/// # Generic Impls +/// +/// - `From<T> for U` implies `Into<U> for T` +/// - `into()` is reflexive, which means that `Into<T> for T` is implemented +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait Into<T>: Sized { /// Performs the conversion. @@ -84,6 +133,9 @@ pub trait Into<T>: Sized { /// Construct `Self` via a conversion. /// +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option<T>` or a `Result<T, E>`. +/// /// # Examples /// /// `String` implements `From<&str>`: @@ -94,6 +146,11 @@ pub trait Into<T>: Sized { /// /// assert_eq!(string, other_string); /// ``` +/// # Generic impls +/// +/// - `From<T> for U` implies `Into<U> for T` +/// - `from()` is reflexive, which means that `From<T> for T` is implemented +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait From<T>: Sized { /// Performs the conversion. |