diff --git a/core/src/result.rs b/core/src/result.rs index 6a77f9f63a88d..77c4ef957ac52 100644 --- a/core/src/result.rs +++ b/core/src/result.rs @@ -2,8 +2,8 @@ //! //! [`Result`][`Result`] is the type used for returning and propagating //! errors. It is an enum with the variants, [`Ok(T)`], representing success and -//! containing a value, and [`Err(E)`], representing error and containing an -//! error value. +//! success and containing a value, and [`Err(E)`], representing error +//! and containing an error value. //! //! ``` //! # #[allow(dead_code)] @@ -14,10 +14,11 @@ //! ``` //! //! Functions return [`Result`] whenever errors are expected and recoverable. In -//! the `std` crate, [`Result`] is most prominently used for -//! [I/O](../../std/io/index.html). +//! recoverable. In the `std` crate, [`Result`] is most prominently used +//! for [I/O](../../std/io/index.html). //! -//! A simple function returning [`Result`] might be defined and used like so: +//! A simple function returning [`Result`] might be +//! defined and used like so: //! //! ``` //! #[derive(Debug)] @@ -40,8 +41,8 @@ //! ``` //! //! Pattern matching on [`Result`]s is clear and straightforward for simple -//! cases, but [`Result`] comes with some convenience methods that make working -//! with it more succinct. +//! simple cases, but [`Result`] comes with some convenience methods +//! that make working with it more succinct. //! //! ``` //! let good_result: Result = Ok(10); @@ -67,15 +68,16 @@ //! //! # Results must be used //! -//! A common problem with using return values to indicate errors is that it is -//! easy to ignore the return value, thus failing to handle the error. -//! [`Result`] is annotated with the `#[must_use]` attribute, which will cause -//! the compiler to issue a warning when a Result value is ignored. This makes -//! [`Result`] especially useful with functions that may encounter errors but -//! don't otherwise return a useful value. +//! A common problem with using return values to indicate errors is +//! that it is easy to ignore the return value, thus failing to handle +//! the error. [`Result`] is annotated with the `#[must_use]` attribute, +//! which will cause the compiler to issue a warning when a Result +//! value is ignored. This makes [`Result`] especially useful with +//! functions that may encounter errors but don't otherwise return a +//! useful value. //! -//! Consider the [`write_all`] method defined for I/O types by the [`Write`] -//! trait: +//! Consider the [`write_all`] method defined for I/O types +//! by the [`Write`] trait: //! //! ``` //! use std::io; @@ -85,11 +87,12 @@ //! } //! ``` //! -//! *Note: The actual definition of [`Write`] uses [`io::Result`], which is just -//! a synonym for [Result].* +//! *Note: The actual definition of [`Write`] uses [`io::Result`], which +//! is just a synonym for [Result].* //! -//! This method doesn't produce a value, but the write may fail. It's crucial to -//! handle the error case, and *not* write something like this: +//! This method doesn't produce a value, but the write may +//! fail. It's crucial to handle the error case, and *not* write +//! something like this: //! //! ```no_run //! # #![allow(unused_must_use)] // \o/ @@ -102,12 +105,12 @@ //! file.write_all(b"important message"); //! ``` //! -//! If you *do* write that in Rust, the compiler will give you a warning (by -//! default, controlled by the `unused_must_use` lint). +//! If you *do* write that in Rust, the compiler will give you a +//! warning (by default, controlled by the `unused_must_use` lint). //! -//! You might instead, if you don't want to handle the error, simply assert -//! success with [`expect`]. This will panic if the write fails, providing a -//! marginally useful message indicating why: +//! You might instead, if you don't want to handle the error, simply +//! assert success with [`expect`]. This will panic if the +//! write fails, providing a marginally useful message indicating why: //! //! ```no_run //! use std::fs::File; @@ -142,9 +145,10 @@ //! //! # The question mark operator, `?` //! -//! When writing code that calls many functions that return the [`Result`] type, -//! the error handling can be tedious. The question mark operator, [`?`], hides -//! some of the boilerplate of propagating errors up the call stack. +//! When writing code that calls many functions that return the +//! [`Result`] type, the error handling can be tedious. The question mark +//! operator, [`?`], hides some of the boilerplate of propagating errors +//! up the call stack. //! //! It replaces this: //! @@ -205,17 +209,15 @@ //! //! *It's much nicer!* //! -//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped -//! value, unless the result is [`Err`], in which case [`Err`] is returned early -//! from the enclosing function. +//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped value, unless the result +//! is [`Err`], in which case [`Err`] is returned early from the enclosing function. //! -//! [`?`] can be used in functions that return [`Result`] because of the early -//! return of [`Err`] that it provides. +//! [`?`] can be used in functions that return [`Result`] because of the +//! early return of [`Err`] that it provides. //! //! [`expect`]: Result::expect //! [`Write`]: ../../std/io/trait.Write.html "io::Write" -//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all -//! "io::Write::write_all" +//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all "io::Write::write_all" //! [`io::Result`]: ../../std/io/type.Result.html "io::Result" //! [`?`]: crate::ops::Try //! [`Ok(T)`]: Ok @@ -250,8 +252,8 @@ //! //! ## Querying the variant //! -//! The [`is_ok`] and [`is_err`] methods return [`true`] if the [`Result`] is -//! [`Ok`] or [`Err`], respectively. +//! In addition to working with pattern matching, [`Result`] provides a +//! wide variety of different methods. //! //! [`is_err`]: Result::is_err //! [`is_ok`]: Result::is_ok @@ -261,8 +263,8 @@ //! * [`as_ref`] converts from `&Result` to `Result<&T, &E>` //! * [`as_mut`] converts from `&mut Result` to `Result<&mut T, &mut E>` //! * [`as_deref`] converts from `&Result` to `Result<&T::Target, &E>` -//! * [`as_deref_mut`] converts from `&mut Result` to `Result<&mut -//! T::Target, &mut E>` +//! * [`as_deref_mut`] converts from `&mut Result` to +//! `Result<&mut T::Target, &mut E>` //! //! [`as_deref`]: Result::as_deref //! [`as_deref_mut`]: Result::as_deref_mut @@ -271,18 +273,19 @@ //! //! ## Extracting contained values //! -//! These methods extract the contained value in a [`Result`] when it is -//! the [`Ok`] variant. If the [`Result`] is [`Err`]: +//! These methods extract the contained value in a [`Result`] when it +//! is the [`Ok`] variant. If the [`Result`] is [`Err`]: //! //! * [`expect`] panics with a provided custom message //! * [`unwrap`] panics with a generic message //! * [`unwrap_or`] returns the provided default value -//! * [`unwrap_or_default`] returns the default value of the type `T` (which -//! must implement the [`Default`] trait) -//! * [`unwrap_or_else`] returns the result of evaluating the provided function +//! * [`unwrap_or_default`] returns the default value of the type `T` +//! (which must implement the [`Default`] trait) +//! * [`unwrap_or_else`] returns the result of evaluating the provided +//! function //! -//! The panicking methods [`expect`] and [`unwrap`] require `E` to implement the -//! [`Debug`] trait. +//! The panicking methods [`expect`] and [`unwrap`] require `E` to +//! implement the [`Debug`] trait. //! //! [`Debug`]: crate::fmt::Debug //! [`expect`]: Result::expect @@ -291,9 +294,9 @@ //! [`unwrap_or_default`]: Result::unwrap_or_default //! [`unwrap_or_else`]: Result::unwrap_or_else //! -//! These methods extract the contained value in a [`Result`] when it is -//! the [`Err`] variant. They require `T` to implement the [`Debug`] trait. If -//! the [`Result`] is [`Ok`]: +//! These methods extract the contained value in a [`Result`] when it +//! is the [`Err`] variant. They require `T` to implement the [`Debug`] +//! trait. If the [`Result`] is [`Ok`]: //! //! * [`expect_err`] panics with a provided custom message //! * [`unwrap_err`] panics with a generic message @@ -308,10 +311,10 @@ //! //! * [`err`][Result::err] transforms [`Result`] into [`Option`], //! mapping [`Err(e)`] to [`Some(e)`] and [`Ok(v)`] to [`None`] -//! * [`ok`][Result::ok] transforms [`Result`] into [`Option`], mapping -//! [`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`] -//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an [`Option`] -//! of a [`Result`] +//! * [`ok`][Result::ok] transforms [`Result`] into [`Option`], +//! mapping [`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`] +//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an +//! [`Option`] of a [`Result`] //! // Do NOT add link reference definitions for `err` or `ok`, because they // will generate numerous incorrect URLs for `Err` and `Ok` elsewhere, due