From 7897e168bdd9708f83514a9c3e88d83278de4334 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Sat, 1 Apr 2017 15:35:03 +1100 Subject: [PATCH] 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 0b0f831f093b..5546d2a13c47 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 {