From 7897e168bdd9708f83514a9c3e88d83278de4334 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Sat, 1 Apr 2017 15:35:03 +1100 Subject: [PATCH 1/5] Convert docs clean up. --- src/libcore/convert.rs | 145 ++++++++++++++++++++++++++++++++--------- 1 file changed, 114 insertions(+), 31 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 0b0f831f093b0..5546d2a13c478 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -17,8 +17,8 @@ //! 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 +//! - 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 @@ -29,7 +29,7 @@ //! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a blanket implementation //! in the standard library. //! -//! # Generic impl +//! # Generic Implementations //! //! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference //! - [`From`]` for T` implies [`Into`]` for U` @@ -50,10 +50,20 @@ use str::FromStr; -/// A cheap, reference-to-reference conversion. +/// A cheap reference-to-reference conversion. Used to convert a value to a reference value +/// within generic code. /// -/// `AsRef` is very similar to, but different than, [`Borrow`]. See -/// [the book][book] for more. +/// `AsRef` is very similar to, but serves a slightly different purpose than, [`Borrow`]. +/// +/// `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: +/// +/// - Use `AsRef` when goal is to simply convert into a reference +/// - Use `Borrow` when goal is related to writing code that is agnostic to the type of borrow and if is reference or value +/// +/// See [the book][book] for a more detailed comparison. /// /// [book]: ../../book/borrow-and-asref.html /// [`Borrow`]: ../../std/borrow/trait.Borrow.html @@ -64,7 +74,23 @@ use str::FromStr; /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html /// +/// # Generic Implementations +/// +/// - `AsRef` auto-dereferences if the inner type is a reference or a mutable +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// /// # Examples +/// An example implementation of the trait is [`Path`]. +/// +/// [`Path`]: ../../std/struct.Path.html +/// +/// ``` +/// impl AsRef for str { +/// fn as_ref(&self) -> &Path { +/// Path::new(self) +/// } +/// } +/// ``` /// /// Both [`String`] and `&str` implement `AsRef`: /// @@ -82,11 +108,6 @@ use str::FromStr; /// is_hello(s); /// ``` /// -/// # Generic Impls -/// -/// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `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 { /// Performs the conversion. @@ -96,12 +117,19 @@ pub trait AsRef { /// A cheap, mutable reference-to-mutable reference conversion. /// +/// This trait is similar to `AsRef` but used for converting mutable references. +/// /// **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 /// [`Result`]: ../../std/result/enum.Result.html /// +/// # Generic Implementations +/// +/// - `AsMut` auto-dereferences if the inner type is a reference or a mutable +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// /// # Examples /// /// [`Box`] implements `AsMut`: @@ -118,10 +146,13 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// # Generic Impls +/// Implementing `AsMut`: /// -/// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// ``` +/// impl Type { +/// let a = 1; +/// } +/// ``` /// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { @@ -130,7 +161,7 @@ pub trait AsMut { fn as_mut(&mut self) -> &mut T; } -/// A conversion that consumes `self`, which may or may not be expensive. +/// A conversion that consumes `self`, which may or may not be expensive. The reciprocal of [`From`][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`]. @@ -139,6 +170,11 @@ pub trait AsMut { /// 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. /// +/// # Generic Implementations +/// +/// - [`From`][From]` for U` implies `Into for T` +/// - [`into`] is reflexive, which means that `Into for T` is implemented +/// /// # Examples /// /// [`String`] implements `Into>`: @@ -153,11 +189,6 @@ pub trait AsMut { /// is_hello(s); /// ``` /// -/// # Generic Impls -/// -/// - [`From`][From]` for U` implies `Into for T` -/// - [`into`] is reflexive, which means that `Into for T` is implemented -/// /// [`TryInto`]: trait.TryInto.html /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html @@ -171,11 +202,24 @@ pub trait Into: Sized { fn into(self) -> T; } -/// Construct `Self` via a conversion. +/// Simple and safe type conversions in to `Self`. 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. +/// +/// 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. +/// 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. /// /// **Note: this trait must not fail**. If the conversion can fail, use [`TryFrom`] or a dedicated /// method which returns an [`Option`] or a [`Result`]. /// +/// # Generic Implementations +/// +/// - `From for U` implies [`Into`]` for T` +/// - [`from`] is reflexive, which means that `From for T` is implemented +/// /// # Examples /// /// [`String`] implements `From<&str>`: @@ -186,10 +230,34 @@ 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 +/// An example usage for error handling: +/// +/// ``` +/// enum CliError { +/// IoError(io::Error), +/// ParseError(num::ParseIntError), +/// } +/// +/// impl From for MyError { +/// fn from(error: io::Error) -> Self { +/// CliError::IoError(error) +/// } +/// } +/// +/// impl From for MyError { +/// fn from(error: io::Error) -> Self { +/// CliError::ParseError(error) +/// } +/// } +/// +/// fn open_and_parse_file(file_name: &str) -> Result { +/// let file = std::fs::File::open("test")?; +/// let mut contents = String::new(); +/// file.read_to_string(&mut contents)?; +/// let num: i32 = contents.trim().parse()?; +/// } +/// ``` /// /// [`TryFrom`]: trait.TryFrom.html /// [`Option`]: ../../std/option/enum.Option.html @@ -197,6 +265,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from +/// [book]: ../../book/error-handling.html#the-from-trait #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. @@ -236,7 +305,9 @@ pub trait TryFrom: Sized { // As lifts over & #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T + where T: AsRef +{ fn as_ref(&self) -> &U { >::as_ref(*self) } @@ -244,7 +315,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { // As lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T + where T: AsRef +{ fn as_ref(&self) -> &U { >::as_ref(*self) } @@ -260,7 +333,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { // AsMut lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { +impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T + where T: AsMut +{ fn as_mut(&mut self) -> &mut U { (*self).as_mut() } @@ -276,7 +351,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { // From implies Into #[stable(feature = "rust1", since = "1.0.0")] -impl Into for T where U: From { +impl Into for T + where U: From +{ fn into(self) -> U { U::from(self) } @@ -285,13 +362,17 @@ impl Into for T where U: From { // From (and thus Into) is reflexive #[stable(feature = "rust1", since = "1.0.0")] impl From for T { - fn from(t: T) -> T { t } + fn from(t: T) -> T { + t + } } // TryFrom implies TryInto #[unstable(feature = "try_from", issue = "33417")] -impl TryInto for T where U: TryFrom { +impl TryInto for T + where U: TryFrom +{ type Error = U::Error; fn try_into(self) -> Result { @@ -327,7 +408,9 @@ impl AsRef for str { // FromStr implies TryFrom<&str> #[unstable(feature = "try_from", issue = "33417")] -impl<'a, T> TryFrom<&'a str> for T where T: FromStr { +impl<'a, T> TryFrom<&'a str> for T + where T: FromStr +{ type Error = ::Err; fn try_from(s: &'a str) -> Result { From 79efca10934b3ea0a172db0ab514fdd72ddeacfb Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Mon, 3 Apr 2017 07:57:20 +1000 Subject: [PATCH 2/5] Wrapped to 80 characters. Fix links. --- src/libcore/convert.rs | 98 +++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 40 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 5546d2a13c478..19cd2d3398f39 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -26,16 +26,16 @@ //! As a library author, you should 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. +//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a +//! blanket implementation in the standard library. //! //! # Generic Implementations //! //! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference //! - [`From`]` for T` implies [`Into`]` for U` //! - [`TryFrom`]` for T` implies [`TryInto`]` for U` -//! - [`From`] and [`Into`] are reflexive, which means that all types can `into()` -//! themselves and `from()` themselves +//! - [`From`] and [`Into`] are reflexive, which means that all types can +//! `into()` themselves and `from()` themselves //! //! See each trait for usage examples. //! @@ -50,26 +50,31 @@ use str::FromStr; -/// 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`]. -/// -/// `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. +/// 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`]. +/// +/// `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: /// /// - Use `AsRef` when goal is to simply convert into a reference -/// - Use `Borrow` when goal is related to writing code that is agnostic to the type of borrow and if is reference or value +/// - Use `Borrow` when goal is related to writing code that is agnostic to the +/// type of borrow and if is reference or value /// /// See [the book][book] for a more detailed comparison. /// /// [book]: ../../book/borrow-and-asref.html /// [`Borrow`]: ../../std/borrow/trait.Borrow.html /// -/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which -/// returns an [`Option`] or a [`Result`]. +/// **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 /// [`Result`]: ../../std/result/enum.Result.html @@ -77,12 +82,13 @@ use str::FromStr; /// # Generic Implementations /// /// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// An example implementation of the trait is [`Path`]. /// -/// [`Path`]: ../../std/struct.Path.html +/// [`Path`]: ../../std/path/struct.Path.html /// /// ``` /// impl AsRef for str { @@ -119,8 +125,8 @@ pub trait AsRef { /// /// This trait is similar to `AsRef` but used for converting mutable references. /// -/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which -/// returns an [`Option`] or a [`Result`]. +/// **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 /// [`Result`]: ../../std/result/enum.Result.html @@ -128,7 +134,8 @@ pub trait AsRef { /// # Generic Implementations /// /// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -161,14 +168,17 @@ 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 conversion that consumes `self`, which may or may not be expensive. The +/// reciprocal of [`From`][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`]. +/// **Note: this trait must not fail**. If the conversion can fail, use +/// [`TryInto`] or a dedicated method which returns an [`Option`] or a +/// [`Result`]. /// -/// 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. +/// 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. /// /// # Generic Implementations /// @@ -202,18 +212,24 @@ pub trait Into: Sized { fn into(self) -> T; } -/// Simple and safe type conversions in to `Self`. It is the reciprocal of `Into`. +/// Simple and safe type conversions in to `Self`. 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. +/// This trait is useful when performing error handling as described by +/// [the book][book] and is closely related to the `?` operator. /// -/// 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. -/// 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. +/// 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. +/// 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. /// -/// **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`] or a dedicated method which returns an [`Option`] or a +/// [`Result`]. /// /// # Generic Implementations /// @@ -265,7 +281,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from -/// [book]: ../../book/error-handling.html#the-from-trait +/// [book]: ../../book/error-handling.html #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. @@ -273,11 +289,13 @@ pub trait From: Sized { fn from(T) -> Self; } -/// An attempted conversion that consumes `self`, which may or may not be expensive. +/// An attempted conversion that consumes `self`, which may or may not be +/// expensive. /// -/// Library authors should not directly implement this trait, but should prefer implementing -/// the [`TryFrom`] trait, which offers greater flexibility and provides an equivalent `TryInto` -/// implementation for free, thanks to a blanket implementation in the standard library. +/// Library authors should not directly implement this trait, but should prefer +/// implementing the [`TryFrom`] trait, which offers greater flexibility and +/// provides an equivalent `TryInto` implementation for free, thanks to a +/// blanket implementation in the standard library. /// /// [`TryFrom`]: trait.TryFrom.html #[unstable(feature = "try_from", issue = "33417")] From bb8474682366592fa9d52cb11723a5fd5cd9421e Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Tue, 4 Apr 2017 08:27:20 +1000 Subject: [PATCH 3/5] AsMut example --- src/libcore/convert.rs | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 19cd2d3398f39..0bc0550641363 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -91,6 +91,8 @@ use str::FromStr; /// [`Path`]: ../../std/path/struct.Path.html /// /// ``` +/// use std::path::Path; +/// /// impl AsRef for str { /// fn as_ref(&self) -> &Path { /// Path::new(self) @@ -123,7 +125,8 @@ pub trait AsRef { /// A cheap, mutable reference-to-mutable reference conversion. /// -/// This trait is similar to `AsRef` but used for converting mutable references. +/// This trait is similar to `AsRef` but used for converting between mutable +/// references. /// /// **Note: this trait must not fail**. If the conversion can fail, use a /// dedicated method which returns an [`Option`] or a [`Result`]. @@ -153,11 +156,13 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// Implementing `AsMut`: +/// `Vec` implements `AsMut` for converting between itself and a primitive array: /// /// ``` -/// impl Type { -/// let a = 1; +/// impl AsMut<[T]> for Vec { +/// fn as_mut(&mut self) -> &mut [T] { +/// self +/// } /// } /// ``` /// @@ -250,19 +255,22 @@ pub trait Into: Sized { /// An example usage for error handling: /// /// ``` +/// use std::io::{self, Read}; +/// use std::num; +/// /// enum CliError { /// IoError(io::Error), /// ParseError(num::ParseIntError), /// } /// -/// impl From for MyError { +/// impl From for CliError { /// fn from(error: io::Error) -> Self { /// CliError::IoError(error) /// } /// } /// -/// impl From for MyError { -/// fn from(error: io::Error) -> Self { +/// impl From for CliError { +/// fn from(error: num::ParseIntError) -> Self { /// CliError::ParseError(error) /// } /// } From d35fa1e98b244773129f18b0e8bcc81fa099ae68 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Fri, 7 Apr 2017 18:26:36 +1000 Subject: [PATCH 4/5] Removing broken examples --- src/libcore/convert.rs | 27 +++------------------------ 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 0bc0550641363..abab4bb0f63b4 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -86,19 +86,6 @@ use str::FromStr; /// `&mut Foo` or `&&mut Foo`) /// /// # Examples -/// An example implementation of the trait is [`Path`]. -/// -/// [`Path`]: ../../std/path/struct.Path.html -/// -/// ``` -/// use std::path::Path; -/// -/// impl AsRef for str { -/// fn as_ref(&self) -> &Path { -/// Path::new(self) -/// } -/// } -/// ``` /// /// Both [`String`] and `&str` implement `AsRef`: /// @@ -156,15 +143,6 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// `Vec` implements `AsMut` for converting between itself and a primitive array: -/// -/// ``` -/// impl AsMut<[T]> for Vec { -/// fn as_mut(&mut self) -> &mut [T] { -/// self -/// } -/// } -/// ``` /// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { @@ -275,11 +253,12 @@ pub trait Into: Sized { /// } /// } /// -/// fn open_and_parse_file(file_name: &str) -> Result { -/// let file = std::fs::File::open("test")?; +/// fn open_and_parse_file(file_name: &str) -> Result { +/// let mut file = std::fs::File::open("test")?; /// let mut contents = String::new(); /// file.read_to_string(&mut contents)?; /// let num: i32 = contents.trim().parse()?; +/// Ok(num) /// } /// ``` /// From 2877a01febe7a0667051463ed1bb431fe17c4d18 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Tue, 18 Apr 2017 08:29:05 +1000 Subject: [PATCH 5/5] Address review comments --- src/libcore/convert.rs | 43 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index abab4bb0f63b4..084736685e3a7 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -35,7 +35,7 @@ //! - [`From`]` for T` implies [`Into`]` for U` //! - [`TryFrom`]` for T` implies [`TryInto`]` for U` //! - [`From`] and [`Into`] are reflexive, which means that all types can -//! `into()` themselves and `from()` themselves +//! `into` themselves and `from` themselves //! //! See each trait for usage examples. //! @@ -59,14 +59,15 @@ use str::FromStr; /// `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. +/// 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: /// /// - Use `AsRef` when goal is to simply convert into a reference /// - Use `Borrow` when goal is related to writing code that is agnostic to the -/// type of borrow and if is reference or value +/// type of borrow and if is reference or value /// /// See [the book][book] for a more detailed comparison. /// @@ -82,8 +83,8 @@ use str::FromStr; /// # Generic Implementations /// /// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type -/// `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -124,8 +125,8 @@ pub trait AsRef { /// # Generic Implementations /// /// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type -/// `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -203,9 +204,11 @@ 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 allows for simplification of error handling by providing a /// means of returning a single error type that encapsulates numerous possible /// erroneous situations. +/// /// 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. @@ -310,8 +313,7 @@ pub trait TryFrom: Sized { // As lifts over & #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T - where T: AsRef +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { fn as_ref(&self) -> &U { >::as_ref(*self) @@ -320,8 +322,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T // As lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T - where T: AsRef +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { fn as_ref(&self) -> &U { >::as_ref(*self) @@ -338,8 +339,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T // AsMut lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T - where T: AsMut +impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { fn as_mut(&mut self) -> &mut U { (*self).as_mut() @@ -356,8 +356,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T // From implies Into #[stable(feature = "rust1", since = "1.0.0")] -impl Into for T - where U: From +impl Into for T where U: From { fn into(self) -> U { U::from(self) @@ -367,16 +366,13 @@ impl Into for T // From (and thus Into) is reflexive #[stable(feature = "rust1", since = "1.0.0")] impl From for T { - fn from(t: T) -> T { - t - } + fn from(t: T) -> T { t } } // TryFrom implies TryInto #[unstable(feature = "try_from", issue = "33417")] -impl TryInto for T - where U: TryFrom +impl TryInto for T where U: TryFrom { type Error = U::Error; @@ -413,8 +409,7 @@ impl AsRef for str { // FromStr implies TryFrom<&str> #[unstable(feature = "try_from", issue = "33417")] -impl<'a, T> TryFrom<&'a str> for T - where T: FromStr +impl<'a, T> TryFrom<&'a str> for T where T: FromStr { type Error = ::Err;