From 58d2c7909f9f9310971fcd517fc895cb878b74c3 Mon Sep 17 00:00:00 2001 From: Thomas Wickham Date: Thu, 14 Jan 2016 16:06:53 +0100 Subject: [PATCH 1/3] Doc:std::convert explicitely list generic impls Also add a note about the necessary simplicity of the conversion. Related issue: #29349 --- src/libcore/convert.rs | 59 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index b02b2a06b75d5..a0021d2adda3e 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -17,6 +17,26 @@ //! Like many traits, these are often used as bounds for generic functions, to //! support arguments of multiple types. //! +//! - Use `as` for reference-to-reference conversions +//! - Use `into` when you want to consume the value +//! - `from` is the more flexible way, which can convert values and references +//! +//! As a library writer, you should prefer implementing `From` rather than +//! `Into`, as `From` is more flexible (you can't `Into` a reference, where +//! you can impl `From` for a reference). `From` is also used for generic +//! implementations. +//! +//! **Note:** these traits are for trivial conversion. **They must not fail**. If +//! they can fail, use a dedicated method which return an `Option` or +//! a `Result`. +//! +//! # Generic impl +//! +//! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference +//! - `From for T` implies `Into for U` +//! - `From` and `Into` are reflexive, which means that all types can `into()` +//! themselve and `from()` themselve +//! //! See each trait for usage examples. #![stable(feature = "rust1", since = "1.0.0")] @@ -30,6 +50,10 @@ use marker::Sized; /// /// [book]: ../../book/borrow-and-asref.html /// +/// **Note:** these traits are for trivial conversion. **They must not fail**. If +/// they can fail, use a dedicated method which return an `Option` or +/// a `Result`. +/// /// # Examples /// /// Both `String` and `&str` implement `AsRef`: @@ -45,6 +69,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 +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsRef { /// Performs the conversion. @@ -53,6 +83,16 @@ pub trait AsRef { } /// A cheap, mutable reference-to-mutable reference conversion. +/// +/// **Note:** these traits are for trivial conversion. **They must not fail**. If +/// they can fail, use a dedicated method which return an `Option` or +/// a `Result`. +/// +/// # Generic Impls +/// +/// - `AsMut` auto-dereference if the inner type is a reference or a mutable +/// reference +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { /// Performs the conversion. @@ -62,6 +102,10 @@ pub trait AsMut { /// A conversion that consumes `self`, which may or may not be expensive. /// +/// **Note:** these traits are for trivial conversion. **They must not fail**. If +/// they can fail, use a dedicated method which return an `Option` or +/// a `Result`. +/// /// # Examples /// /// `String` implements `Into>`: @@ -75,6 +119,12 @@ pub trait AsMut { /// let s = "hello".to_string(); /// is_hello(s); /// ``` +/// +/// #Generic Impls +/// +/// - `From for U` implies `Into for T` +/// - `into()` is reflexive, which means that `Into for T` is implemented +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait Into: Sized { /// Performs the conversion. @@ -84,6 +134,10 @@ pub trait Into: Sized { /// Construct `Self` via a conversion. /// +/// **Note:** these traits are for trivial conversion. **They must not fail**. If +/// they can fail, use a dedicated method which return an `Option` or +/// a `Result`. +/// /// # Examples /// /// `String` implements `From<&str>`: @@ -94,6 +148,11 @@ pub trait Into: Sized { /// /// assert_eq!(string, other_string); /// ``` +/// # Generic impls +/// +/// - `From for U` implies `Into for T` +/// - `from()` is reflexive, which means that `From for T` is implemented +/// #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. From 6cda8e4eaac843471dd33d93d9d5cc892d29cc4c Mon Sep 17 00:00:00 2001 From: Thomas Wickham Date: Fri, 15 Jan 2016 01:24:33 +0100 Subject: [PATCH 2/3] Doc:std::convert: be more specific + typo --- src/libcore/convert.rs | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index a0021d2adda3e..f67bfe34e8f6a 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -22,20 +22,18 @@ //! - `from` is the more flexible way, which can convert values and references //! //! As a library writer, you should prefer implementing `From` rather than -//! `Into`, as `From` is more flexible (you can't `Into` a reference, where -//! you can impl `From` for a reference). `From` is also used for generic -//! implementations. +//! `Into`, 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 are for trivial conversion. **They must not fail**. If -//! they can fail, use a dedicated method which return an `Option` or -//! a `Result`. +//! **Note: these traits must not fail**. If the conversion can fail, you must use a dedicated +//! method which return an `Option` or a `Result`. //! //! # Generic impl //! //! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference //! - `From for T` implies `Into for U` //! - `From` and `Into` are reflexive, which means that all types can `into()` -//! themselve and `from()` themselve +//! themselves and `from()` themselves //! //! See each trait for usage examples. @@ -50,9 +48,8 @@ use marker::Sized; /// /// [book]: ../../book/borrow-and-asref.html /// -/// **Note:** these traits are for trivial conversion. **They must not fail**. If -/// they can fail, use a dedicated method which return an `Option` or -/// a `Result`. +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option` or a `Result`. /// /// # Examples /// @@ -73,7 +70,7 @@ use marker::Sized; /// # Generic Impls /// /// - `AsRef` auto-dereference if the inner type is a reference or a mutable -/// reference +/// 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 { @@ -84,14 +81,13 @@ pub trait AsRef { /// A cheap, mutable reference-to-mutable reference conversion. /// -/// **Note:** these traits are for trivial conversion. **They must not fail**. If -/// they can fail, use a dedicated method which return an `Option` or -/// a `Result`. +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option` or a `Result`. /// /// # Generic Impls /// /// - `AsMut` auto-dereference if the inner type is a reference or a mutable -/// reference +/// 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 { @@ -102,9 +98,12 @@ pub trait AsMut { /// A conversion that consumes `self`, which may or may not be expensive. /// -/// **Note:** these traits are for trivial conversion. **They must not fail**. If -/// they can fail, use a dedicated method which return an `Option` or -/// a `Result`. +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option` or a `Result`. +/// +/// 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 /// @@ -134,9 +133,8 @@ pub trait Into: Sized { /// Construct `Self` via a conversion. /// -/// **Note:** these traits are for trivial conversion. **They must not fail**. If -/// they can fail, use a dedicated method which return an `Option` or -/// a `Result`. +/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which +/// return an `Option` or a `Result`. /// /// # Examples /// From a0cd46554d850d99f985be911215ac41978533a2 Mon Sep 17 00:00:00 2001 From: Thomas Wickham Date: Sun, 31 Jan 2016 12:26:15 +0100 Subject: [PATCH 3/3] Doc:std::convert: disambiguate traits and keywords --- src/libcore/convert.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index f67bfe34e8f6a..c207ad16595d1 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -17,13 +17,13 @@ //! Like many traits, these are often used as bounds for generic functions, to //! support arguments of multiple types. //! -//! - Use `as` for reference-to-reference conversions -//! - Use `into` when you want to consume the value -//! - `from` is the more flexible way, which can convert values and references +//! - 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` rather than //! `Into`, as `From` provides greater flexibility and offer the equivalent `Into` -//! implementation for free thanks to a blanket implementation in the standard library. +//! 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` or a `Result`. @@ -103,7 +103,7 @@ pub trait AsMut { /// /// 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. +/// implementation for free, thanks to a blanket implementation in the standard library. /// /// # Examples /// @@ -119,7 +119,7 @@ pub trait AsMut { /// is_hello(s); /// ``` /// -/// #Generic Impls +/// # Generic Impls /// /// - `From for U` implies `Into for T` /// - `into()` is reflexive, which means that `Into for T` is implemented