From 71bdeb022a9403707a17a62f51d9b35e5f76ff85 Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 20 Mar 2019 23:15:41 +0100 Subject: [PATCH 1/7] Initial version of the documentation change of std::convert. --- src/libcore/convert.rs | 170 ++++++++++++++++++++--------------------- 1 file changed, 85 insertions(+), 85 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 774d648558b48..ca166abebdf2a 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -1,26 +1,24 @@ -//! Traits for conversions between types. //! -//! The traits in this module provide a general way to talk about conversions -//! from one type to another. They follow the standard Rust conventions of -//! `as`/`into`/`from`. +//! The traits in this module provide a way to convert from one type to another type. //! -//! Like many traits, these are often used as bounds for generic functions, to -//! support arguments of multiple types. +//! Each trait serves a different purpose: //! -//! - Implement the `As*` traits for reference-to-reference conversions -//! - Implement the [`Into`] trait when you want to consume the value in the conversion -//! - The [`From`] trait is the most flexible, useful for value _and_ reference conversions -//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], but allow for the -//! conversion to fail +//! - Implement the [`AsRef`] trait for cheap reference-to-reference conversions +//! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions +//! - Implement the [`From`] trait for consuming value-to-value conversions +//! - Implement the [`Into`] trait for consuming value-to-value conversions to types outside the current crate +//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], but should be implemented when +//! the conversion can fail. //! -//! As a library author, you should prefer implementing [`From`][`From`] or +//! The traits in this module are often used as trait bounds for generic functions such that to +//! arguments of multiple types are supported. See the documentation of each trait for examples. +//! +//! As a library author, you should always prefer implementing [`From`][`From`] or //! [`TryFrom`][`TryFrom`] rather than [`Into`][`Into`] or [`TryInto`][`TryInto`], //! as [`From`] and [`TryFrom`] provide greater flexibility and offer //! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a -//! blanket implementation in the standard library. However, there are some cases -//! where this is not possible, such as creating conversions into a type defined -//! outside your library, so implementing [`Into`] instead of [`From`] is -//! sometimes necessary. +//! blanket implementation in the standard library. Only implement [`Into`] or [`TryInto`] +//! when a conversion to a type outside the current crate is required. //! //! # Generic Implementations //! @@ -99,28 +97,20 @@ use fmt; #[inline] pub const fn identity(x: T) -> T { x } -/// A cheap reference-to-reference conversion. Used to convert a value to a -/// reference value within generic code. -/// -/// `AsRef` is very similar to, but serves a slightly different purpose than, -/// [`Borrow`]. +/// 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 to be used when wishing to convert to a reference of another -/// type. -/// `Borrow` is more related to the notion of taking the reference. It is -/// useful when wishing to abstract over the type of reference -/// (`&T`, `&mut T`) or allow both the referenced and owned type to be treated -/// in the same manner. -/// -/// The key difference between the two traits is the intention: /// +/// `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 /// /// [`Borrow`]: ../../std/borrow/trait.Borrow.html /// -/// **Note: this trait must not fail**. If the conversion can fail, use a +/// **Note: This trait must not fail**. If the conversion can fail, use a /// dedicated method which returns an [`Option`] or a [`Result`]. /// /// [`Option`]: ../../std/option/enum.Option.html @@ -134,7 +124,11 @@ pub const fn identity(x: T) -> T { x } /// /// # Examples /// -/// Both [`String`] and `&str` implement `AsRef`: +/// 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``` 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` we can accept both as input argument. /// /// [`String`]: ../../std/string/struct.String.html /// @@ -157,12 +151,12 @@ pub trait AsRef { fn as_ref(&self) -> &T; } -/// A cheap, mutable reference-to-mutable reference conversion. -/// -/// This trait is similar to `AsRef` but used for converting between mutable -/// references. +/// 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. /// -/// **Note: this trait must not fail**. If the conversion can fail, use a +/// **Note: This trait must not fail**. If the conversion can fail, use a /// dedicated method which returns an [`Option`] or a [`Result`]. /// /// [`Option`]: ../../std/option/enum.Option.html @@ -176,10 +170,11 @@ pub trait AsRef { /// /// # Examples /// -/// [`Box`] implements `AsMut`: -/// -/// [`Box`]: ../../std/boxed/struct.Box.html -/// +/// Using ```AsMut``` as trait bound for a generic function we can accept all mutable references +/// that can be converted to type ```&mut T```. Because [`Box`] implements ```AsMut``` we can +/// write a function ```add_one```that takes all arguments that can be converted to ```&mut u64```. +/// Because [`Box`] implements ```AsMut``` ```add_one``` accepts arguments of type +/// ```&mut Box``` as well: /// ``` /// fn add_one>(num: &mut T) { /// *num.as_mut() += 1; @@ -189,7 +184,7 @@ pub trait AsRef { /// add_one(&mut boxed_num); /// assert_eq!(*boxed_num, 1); /// ``` -/// +/// [`Box`]: ../../std/boxed/struct.Box.html /// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { @@ -198,29 +193,24 @@ pub trait AsMut { fn as_mut(&mut self) -> &mut T; } -/// A conversion that consumes `self`, which may or may not be expensive. The -/// reciprocal of [`From`][From]. +/// A value-to-value conversion that consumes the input value. The +/// opposite of [`From`]. /// -/// **Note: this trait must not fail**. If the conversion can fail, use -/// [`TryInto`] or a dedicated method which returns an [`Option`] or a -/// [`Result`]. +/// 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. /// -/// Library authors should not directly implement this trait, but should prefer -/// implementing the [`From`][From] trait, which offers greater flexibility and -/// provides an equivalent `Into` implementation for free, thanks to a blanket -/// implementation in the standard library. +/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`]. /// /// # Generic Implementations /// -/// - [`From`][From]` for U` implies `Into for T` -/// - [`into`] is reflexive, which means that `Into for T` is implemented -/// -/// # Implementing `Into` +/// - [`From`]` for U` implies `Into for T` +/// - [`Into`]` is reflexive, which means that `Into for T` is implemented /// -/// There is one exception to implementing `Into`, and it's kind of esoteric. -/// If the destination type is not part of the current crate, and it uses a -/// generic variable, then you can't implement `From` directly. For example, -/// take this crate: +/// # 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: /// /// ```compile_fail /// struct Wrapper(Vec); @@ -230,8 +220,9 @@ pub trait AsMut { /// } /// } /// ``` -/// -/// To fix this, you can implement `Into` directly: +/// This will fail to compile because we cannot implement a trait for a type +/// if both the trait and the type are not defined by the current crate. +/// This is due to Rust's orphaning rules. To bypass this, you can implement `Into` directly: /// /// ``` /// struct Wrapper(Vec); @@ -242,17 +233,21 @@ pub trait AsMut { /// } /// ``` /// -/// This won't always allow the conversion: for example, `try!` and `?` -/// always use `From`. However, in most cases, people use `Into` to do the -/// conversions, and this will allow that. +/// 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. /// -/// In almost all cases, you should try to implement `From`, then fall back -/// to `Into` if `From` can't be implemented. /// /// # Examples /// /// [`String`] implements `Into>`: /// +/// In order to express that we want a generic function to take all arguments that can be +/// converted to a specified type ```T```, we can use a trait bound of ```Into```. +/// For example: The function ```is_hello``` takes all arguments that can be converted into a +/// ```Vec```. +/// /// ``` /// fn is_hello>>(s: T) { /// let bytes = b"hello".to_vec(); @@ -276,36 +271,36 @@ pub trait Into: Sized { fn into(self) -> T; } -/// Simple and safe type conversions in to `Self`. It is the reciprocal of -/// `Into`. +/// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of +/// [`Into`]. /// -/// This trait is useful when performing error handling as described by -/// [the book][book] and is closely related to the `?` operator. +/// 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. /// -/// When constructing a function that is capable of failing the return type -/// will generally be of the form `Result`. -/// -/// The `From` trait allows for simplification of error handling by providing a -/// means of returning a single error type that encapsulates numerous possible -/// erroneous situations. +/// 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. /// -/// This trait is not limited to error handling, rather the general case for -/// this trait would be in any type conversions to have an explicit definition -/// of how they are performed. +/// 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`. +/// 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 for more details. /// -/// **Note: this trait must not fail**. If the conversion can fail, use -/// [`TryFrom`] or a dedicated method which returns an [`Option`] or a -/// [`Result`]. +/// **Note: This trait must not fail**. If the conversion can fail, use [`TryFrom`]. /// /// # Generic Implementations /// -/// - `From for U` implies [`Into`]` for T` -/// - [`from`] is reflexive, which means that `From for T` is implemented +/// - [`From`]` for U` implies [`Into`]` for T` +/// - [`From`] is reflexive, which means that `From for T` is implemented /// /// # Examples /// /// [`String`] implements `From<&str>`: /// +/// An explicit conversion from a &str to a String is done as follows: /// ``` /// let string = "hello".to_string(); /// let other_string = String::from("hello"); @@ -313,7 +308,12 @@ pub trait Into: Sized { /// assert_eq!(string, other_string); /// ``` /// -/// An example usage for error handling: +/// 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::into``` which is automatically provided when implementing ```From```. +/// The compiler then infers which implementation of ```Into``` should be used. /// /// ``` /// use std::fs; @@ -350,7 +350,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from -/// [book]: ../../book/ch09-00-error-handling.html +/// [book]: ../../book/first-edition/error-handling.html #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. From 49a9b349acda7bbf8d555cda4218351472534173 Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 21 Mar 2019 15:06:16 +0100 Subject: [PATCH 2/7] Reformatted the text such that the line length does not exceed 100. --- src/libcore/convert.rs | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index ca166abebdf2a..30c3823e0b4bc 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -6,8 +6,10 @@ //! - Implement the [`AsRef`] trait for cheap reference-to-reference conversions //! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions //! - Implement the [`From`] trait for consuming value-to-value conversions -//! - Implement the [`Into`] trait for consuming value-to-value conversions to types outside the current crate -//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], but should be implemented when +//! - Implement the [`Into`] trait for consuming value-to-value conversions to types +//! outside the current crate +//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], +//! but should be implemented when //! the conversion can fail. //! //! The traits in this module are often used as trait bounds for generic functions such that to @@ -196,9 +198,10 @@ pub trait AsMut { /// A value-to-value conversion that consumes the input value. The /// opposite of [`From`]. /// -/// 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. +/// 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. /// /// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`]. @@ -209,7 +212,8 @@ pub trait AsMut { /// - [`Into`]` is reflexive, which means that `Into 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. +/// If the destination type is not part of the current crate +/// then you can't implement [`From`] directly. /// For example, take this code: /// /// ```compile_fail @@ -233,8 +237,9 @@ pub trait AsMut { /// } /// ``` /// -/// 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. +/// 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. /// @@ -274,8 +279,9 @@ pub trait Into: Sized { /// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of /// [`Into`]. /// -/// 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. +/// 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. @@ -308,11 +314,12 @@ pub trait Into: Sized { /// 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::into``` which is automatically provided when implementing ```From```. +/// 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::into``` +/// which is automatically provided when implementing ```From```. /// The compiler then infers which implementation of ```Into``` should be used. /// /// ``` From d657d180835cee1e4b4ad4400d1f33f62ecd37b6 Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 21 Mar 2019 15:26:07 +0100 Subject: [PATCH 3/7] Fixed indentation of list items. --- src/libcore/convert.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 30c3823e0b4bc..ec15a7f68fb07 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -7,10 +7,9 @@ //! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions //! - Implement the [`From`] trait for consuming value-to-value conversions //! - Implement the [`Into`] trait for consuming value-to-value conversions to types -//! outside the current crate +//! outside the current crate //! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], -//! but should be implemented when -//! the conversion can fail. +//! but should be implemented when the conversion can fail. //! //! The traits in this module are often used as trait bounds for generic functions such that to //! arguments of multiple types are supported. See the documentation of each trait for examples. @@ -243,7 +242,6 @@ pub trait AsMut { /// 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. /// -/// /// # Examples /// /// [`String`] implements `Into>`: From a66fca459aeead957e0160b3bbe842c5d9951dfb Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 21 Mar 2019 18:42:15 +0100 Subject: [PATCH 4/7] Added back a reference to "the book" --- src/libcore/convert.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index ec15a7f68fb07..ce7472f33292a 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -291,7 +291,7 @@ pub trait Into: Sized { /// When constructing a function that is capable of failing, the return type /// will generally be of the form `Result`. /// 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 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`]. /// @@ -355,7 +355,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from -/// [book]: ../../book/first-edition/error-handling.html +/// [book]: ../../book/ch09-00-error-handling.html #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. From d7fcd219c5cc79af1d8f24d7f41d12466d349bdd Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 21 Mar 2019 18:49:12 +0100 Subject: [PATCH 5/7] Changed inline code by using a single quote. --- src/libcore/convert.rs | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index ce7472f33292a..4402dc2fa415d 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -101,7 +101,7 @@ pub const fn identity(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. +/// `&T` or write a custom function. /// /// /// `AsRef` is very similar to, but serves a slightly different purpose than [`Borrow`]: @@ -126,8 +126,8 @@ pub const fn identity(x: T) -> T { x } /// # Examples /// /// 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``` we express that we +/// converted a the specified type `T`. +/// For example: By creating a generic function that takes an `AsRef` 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` we can accept both as input argument. /// @@ -155,7 +155,7 @@ pub trait AsRef { /// 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. +/// implement [`From`] with type `&mut T` or write a custom function. /// /// **Note: This trait must not fail**. If the conversion can fail, use a /// dedicated method which returns an [`Option`] or a [`Result`]. @@ -171,11 +171,11 @@ pub trait AsRef { /// /// # Examples /// -/// Using ```AsMut``` as trait bound for a generic function we can accept all mutable references -/// that can be converted to type ```&mut T```. Because [`Box`] implements ```AsMut``` we can -/// write a function ```add_one```that takes all arguments that can be converted to ```&mut u64```. -/// Because [`Box`] implements ```AsMut``` ```add_one``` accepts arguments of type -/// ```&mut Box``` as well: +/// Using `AsMut` as trait bound for a generic function we can accept all mutable references +/// that can be converted to type `&mut T`. Because [`Box`] implements `AsMut` we can +/// write a function `add_one`that takes all arguments that can be converted to `&mut u64`. +/// Because [`Box`] implements `AsMut` `add_one` accepts arguments of type +/// `&mut Box` as well: /// ``` /// fn add_one>(num: &mut T) { /// *num.as_mut() += 1; @@ -236,20 +236,20 @@ pub trait AsMut { /// } /// ``` /// -/// 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`] +/// 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. +/// 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. /// /// # Examples /// /// [`String`] implements `Into>`: /// /// In order to express that we want a generic function to take all arguments that can be -/// converted to a specified type ```T```, we can use a trait bound of ```Into```. -/// For example: The function ```is_hello``` takes all arguments that can be converted into a -/// ```Vec```. +/// converted to a specified type `T`, we can use a trait bound of `Into`. +/// For example: The function `is_hello` takes all arguments that can be converted into a +/// `Vec`. /// /// ``` /// fn is_hello>>(s: T) { @@ -312,13 +312,13 @@ pub trait Into: Sized { /// assert_eq!(string, other_string); /// ``` /// -/// While performing error handling it is often useful to implement ```From``` +/// 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::into``` -/// which is automatically provided when implementing ```From```. -/// The compiler then infers which implementation of ```Into``` should be used. +/// the underlying error type to our custom error type by calling `Into::into` +/// which is automatically provided when implementing `From`. +/// The compiler then infers which implementation of `Into` should be used. /// /// ``` /// use std::fs; From 70ce4b168d697a55a5aaaebf39e4bda5c4b9db58 Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 21 Mar 2019 19:36:51 +0100 Subject: [PATCH 6/7] Wrapped a line such that it does not exceed 100 characters. --- src/libcore/convert.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 4402dc2fa415d..9f72d02d865d3 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -291,7 +291,8 @@ pub trait Into: Sized { /// When constructing a function that is capable of failing, the return type /// will generally be of the form `Result`. /// 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`]. /// From 6c479c3d02e134dbc8812582c3241fa8747c35d7 Mon Sep 17 00:00:00 2001 From: Christian Date: Mon, 25 Mar 2019 22:21:05 +0100 Subject: [PATCH 7/7] Formatting changes, including better wrapping and creating short summary lines. --- src/libcore/convert.rs | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 9f72d02d865d3..cee4fc6f49a71 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -1,6 +1,6 @@ +//! 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 @@ -99,12 +99,14 @@ use fmt; pub const fn identity(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 @@ -127,6 +129,7 @@ pub const fn identity(x: T) -> T { x } /// /// 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` 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` we can accept both as input argument. @@ -153,6 +156,7 @@ pub trait AsRef { } /// 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. @@ -199,9 +203,9 @@ pub trait AsMut { /// /// 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`]. /// @@ -211,6 +215,7 @@ pub trait AsMut { /// - [`Into`]` is reflexive, which means that `Into 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: @@ -239,6 +244,7 @@ pub trait AsMut { /// 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. /// @@ -280,6 +286,7 @@ pub trait Into: Sized { /// 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. @@ -287,12 +294,11 @@ pub trait Into: Sized { /// 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`. +/// 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`. /// 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`]. /// @@ -313,13 +319,12 @@ pub trait Into: Sized { /// 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::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::into` which is automatically provided when +/// implementing `From`. The compiler then infers which implementation of `Into` should be used. /// /// ``` /// use std::fs;