|
2 | 2 | //! |
3 | 3 | //! [`Result<T, E>`][`Result`] is the type used for returning and propagating |
4 | 4 | //! errors. It is an enum with the variants, [`Ok(T)`], representing success and |
5 | | -//! containing a value, and [`Err(E)`], representing error and containing an |
6 | | -//! error value. |
| 5 | +//!success andcontaining a value, and [`Err(E)`], representing error |
| 6 | +//!and containing anerror value. |
7 | 7 | //! |
8 | 8 | //! ``` |
9 | 9 | //! # #[allow(dead_code)] |
|
14 | 14 | //! ``` |
15 | 15 | //! |
16 | 16 | //! Functions return [`Result`] whenever errors are expected and recoverable. In |
17 | | -//! the `std` crate, [`Result`] is most prominently used for |
18 | | -//! [I/O](../../std/io/index.html). |
| 17 | +//!recoverable. Inthe `std` crate, [`Result`] is most prominently used |
| 18 | +//!for[I/O](../../std/io/index.html). |
19 | 19 | //! |
20 | | -//! A simple function returning [`Result`] might be defined and used like so: |
| 20 | +//! A simple function returning [`Result`] might be |
| 21 | +//! defined and used like so: |
21 | 22 | //! |
22 | 23 | //! ``` |
23 | 24 | //! #[derive(Debug)] |
|
40 | 41 | //! ``` |
41 | 42 | //! |
42 | 43 | //! Pattern matching on [`Result`]s is clear and straightforward for simple |
43 | | -//! cases, but [`Result`] comes with some convenience methods that make working |
44 | | -//! with it more succinct. |
| 44 | +//!simplecases, but [`Result`] comes with some convenience methods |
| 45 | +//!that make workingwith it more succinct. |
45 | 46 | //! |
46 | 47 | //! ``` |
47 | 48 | //! let good_result: Result<i32, i32> = Ok(10); |
|
67 | 68 | //! |
68 | 69 | //! # Results must be used |
69 | 70 | //! |
70 | | -//! A common problem with using return values to indicate errors is that it is |
71 | | -//! easy to ignore the return value, thus failing to handle the error. |
72 | | -//! [`Result`] is annotated with the `#[must_use]` attribute, which will cause |
73 | | -//! the compiler to issue a warning when a Result value is ignored. This makes |
74 | | -//! [`Result`] especially useful with functions that may encounter errors but |
75 | | -//! don't otherwise return a useful value. |
| 71 | +//! A common problem with using return values to indicate errors is |
| 72 | +//! that it is easy to ignore the return value, thus failing to handle |
| 73 | +//! the error. [`Result`] is annotated with the `#[must_use]` attribute, |
| 74 | +//! which will cause the compiler to issue a warning when a Result |
| 75 | +//! value is ignored. This makes [`Result`] especially useful with |
| 76 | +//! functions that may encounter errors but don't otherwise return a |
| 77 | +//! useful value. |
76 | 78 | //! |
77 | | -//! Consider the [`write_all`] method defined for I/O types by the [`Write`] |
78 | | -//! trait: |
| 79 | +//! Consider the [`write_all`] method defined for I/O types |
| 80 | +//!by the [`Write`]trait: |
79 | 81 | //! |
80 | 82 | //! ``` |
81 | 83 | //! use std::io; |
|
85 | 87 | //! } |
86 | 88 | //! ``` |
87 | 89 | //! |
88 | | -//! *Note: The actual definition of [`Write`] uses [`io::Result`], which is just |
89 | | -//! a synonym for <code>[Result]<T, [io::Error]></code>.* |
| 90 | +//! *Note: The actual definition of [`Write`] uses [`io::Result`], which |
| 91 | +//!is justa synonym for <code>[Result]<T, [io::Error]></code>.* |
90 | 92 | //! |
91 | | -//! This method doesn't produce a value, but the write may fail. It's crucial to |
92 | | -//! handle the error case, and *not* write something like this: |
| 93 | +//! This method doesn't produce a value, but the write may |
| 94 | +//! fail. It's crucial to handle the error case, and *not* write |
| 95 | +//! something like this: |
93 | 96 | //! |
94 | 97 | //! ```no_run |
95 | 98 | //! # #![allow(unused_must_use)] // \o/ |
|
102 | 105 | //! file.write_all(b"important message"); |
103 | 106 | //! ``` |
104 | 107 | //! |
105 | | -//! If you *do* write that in Rust, the compiler will give you a warning (by |
106 | | -//! default, controlled by the `unused_must_use` lint). |
| 108 | +//! If you *do* write that in Rust, the compiler will give you a |
| 109 | +//!warning (bydefault, controlled by the `unused_must_use` lint). |
107 | 110 | //! |
108 | | -//! You might instead, if you don't want to handle the error, simply assert |
109 | | -//! success with [`expect`]. This will panic if the write fails, providing a |
110 | | -//! marginally useful message indicating why: |
| 111 | +//! You might instead, if you don't want to handle the error, simply |
| 112 | +//!assertsuccess with [`expect`]. This will panic if the |
| 113 | +//!write fails, providing amarginally useful message indicating why: |
111 | 114 | //! |
112 | 115 | //! ```no_run |
113 | 116 | //! use std::fs::File; |
|
142 | 145 | //! |
143 | 146 | //! # The question mark operator, `?` |
144 | 147 | //! |
145 | | -//! When writing code that calls many functions that return the [`Result`] type, |
146 | | -//! the error handling can be tedious. The question mark operator, [`?`], hides |
147 | | -//! some of the boilerplate of propagating errors up the call stack. |
| 148 | +//! When writing code that calls many functions that return the |
| 149 | +//! [`Result`] type, the error handling can be tedious. The question mark |
| 150 | +//! operator, [`?`], hides some of the boilerplate of propagating errors |
| 151 | +//! up the call stack. |
148 | 152 | //! |
149 | 153 | //! It replaces this: |
150 | 154 | //! |
|
205 | 209 | //! |
206 | 210 | //! *It's much nicer!* |
207 | 211 | //! |
208 | | -//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped |
209 | | -//! value, unless the result is [`Err`], in which case [`Err`] is returned early |
210 | | -//! from the enclosing function. |
| 212 | +//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped value, unless the result |
| 213 | +//! is [`Err`], in which case [`Err`] is returned early from the enclosing function. |
211 | 214 | //! |
212 | | -//! [`?`] can be used in functions that return [`Result`] because of the early |
213 | | -//! return of [`Err`] that it provides. |
| 215 | +//! [`?`] can be used in functions that return [`Result`] because of the |
| 216 | +//!earlyreturn of [`Err`] that it provides. |
214 | 217 | //! |
215 | 218 | //! [`expect`]: Result::expect |
216 | 219 | //! [`Write`]: ../../std/io/trait.Write.html "io::Write" |
217 | | -//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all |
218 | | -//! "io::Write::write_all" |
| 220 | +//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all "io::Write::write_all" |
219 | 221 | //! [`io::Result`]: ../../std/io/type.Result.html "io::Result" |
220 | 222 | //! [`?`]: crate::ops::Try |
221 | 223 | //! [`Ok(T)`]: Ok |
|
250 | 252 | //! |
251 | 253 | //! ## Querying the variant |
252 | 254 | //! |
253 | | -//!The [`is_ok`] and [`is_err`] methods return [`true`] if the[`Result`]is |
254 | | -//![`Ok`] or [`Err`], respectively. |
| 255 | +//!In addition to working with pattern matching,[`Result`]provides a |
| 256 | +//!wide variety of different methods. |
255 | 257 | //! |
256 | 258 | //! [`is_err`]: Result::is_err |
257 | 259 | //! [`is_ok`]: Result::is_ok |
|
261 | 263 | //! * [`as_ref`] converts from `&Result<T, E>` to `Result<&T, &E>` |
262 | 264 | //! * [`as_mut`] converts from `&mut Result<T, E>` to `Result<&mut T, &mut E>` |
263 | 265 | //! * [`as_deref`] converts from `&Result<T, E>` to `Result<&T::Target, &E>` |
264 | | -//! * [`as_deref_mut`] converts from `&mut Result<T, E>` to `Result<&mut |
265 | | -//! T::Target, &mut E>` |
| 266 | +//! * [`as_deref_mut`] converts from `&mut Result<T, E>` to |
| 267 | +//!`Result<&mutT::Target, &mut E>` |
266 | 268 | //! |
267 | 269 | //! [`as_deref`]: Result::as_deref |
268 | 270 | //! [`as_deref_mut`]: Result::as_deref_mut |
|
271 | 273 | //! |
272 | 274 | //! ## Extracting contained values |
273 | 275 | //! |
274 | | -//! These methods extract the contained value in a [`Result<T, E>`] when it is |
275 | | -//! the [`Ok`] variant. If the [`Result`] is [`Err`]: |
| 276 | +//! These methods extract the contained value in a [`Result<T, E>`] when it |
| 277 | +//!isthe [`Ok`] variant. If the [`Result`] is [`Err`]: |
276 | 278 | //! |
277 | 279 | //! * [`expect`] panics with a provided custom message |
278 | 280 | //! * [`unwrap`] panics with a generic message |
279 | 281 | //! * [`unwrap_or`] returns the provided default value |
280 | | -//! * [`unwrap_or_default`] returns the default value of the type `T` (which |
281 | | -//! must implement the [`Default`] trait) |
282 | | -//! * [`unwrap_or_else`] returns the result of evaluating the provided function |
| 282 | +//! * [`unwrap_or_default`] returns the default value of the type `T` |
| 283 | +//! (which must implement the [`Default`] trait) |
| 284 | +//! * [`unwrap_or_else`] returns the result of evaluating the provided |
| 285 | +//! function |
283 | 286 | //! |
284 | | -//! The panicking methods [`expect`] and [`unwrap`] require `E` to implement the |
285 | | -//! [`Debug`] trait. |
| 287 | +//! The panicking methods [`expect`] and [`unwrap`] require `E` to |
| 288 | +//!implement the[`Debug`] trait. |
286 | 289 | //! |
287 | 290 | //! [`Debug`]: crate::fmt::Debug |
288 | 291 | //! [`expect`]: Result::expect |
|
291 | 294 | //! [`unwrap_or_default`]: Result::unwrap_or_default |
292 | 295 | //! [`unwrap_or_else`]: Result::unwrap_or_else |
293 | 296 | //! |
294 | | -//! These methods extract the contained value in a [`Result<T, E>`] when it is |
295 | | -//! the [`Err`] variant. They require `T` to implement the [`Debug`] trait. If |
296 | | -//! the [`Result`] is [`Ok`]: |
| 297 | +//! These methods extract the contained value in a [`Result<T, E>`] when it |
| 298 | +//!isthe [`Err`] variant. They require `T` to implement the [`Debug`] |
| 299 | +//!trait. Ifthe [`Result`] is [`Ok`]: |
297 | 300 | //! |
298 | 301 | //! * [`expect_err`] panics with a provided custom message |
299 | 302 | //! * [`unwrap_err`] panics with a generic message |
|
308 | 311 | //! |
309 | 312 | //! * [`err`][Result::err] transforms [`Result<T, E>`] into [`Option<E>`], |
310 | 313 | //! mapping [`Err(e)`] to [`Some(e)`] and [`Ok(v)`] to [`None`] |
311 | | -//! * [`ok`][Result::ok] transforms [`Result<T, E>`] into [`Option<T>`], mapping |
312 | | -//! [`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`] |
313 | | -//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an [`Option`] |
314 | | -//! of a [`Result`] |
| 314 | +//! * [`ok`][Result::ok] transforms [`Result<T, E>`] into [`Option<T>`], |
| 315 | +//!mapping[`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`] |
| 316 | +//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an |
| 317 | +//![`Option`]of a [`Result`] |
315 | 318 | //! |
316 | 319 | // Do NOT add link reference definitions for `err` or `ok`, because they |
317 | 320 | // will generate numerous incorrect URLs for `Err` and `Ok` elsewhere, due |
|