1//! Error handling with the `Result` type.
2//!
3//! [`Result<T, E>`][`Result`] is the type used for returning and propagating
4//! errors. It is an enum with the variants, [`Ok(T)`], representing
5//! success and containing a value, and [`Err(E)`], representing error
6//! and containing an error value.
7//!
8//! ```
9//! # #[allow(dead_code)]
10//! enum Result<T, E> {
11//! Ok(T),
12//! Err(E),
13//! }
14//! ```
15//!
16//! Functions return [`Result`] whenever errors are expected and
17//! recoverable. In the `std` crate, [`Result`] is most prominently used
18//! for [I/O](../../std/io/index.html).
19//!
20//! A simple function returning [`Result`] might be
21//! defined and used like so:
22//!
23//! ```
24//! #[derive(Debug)]
25//! enum Version { Version1, Version2 }
26//!
27//! fn parse_version(header: &[u8]) -> Result<Version, &'static str> {
28//! match header.get(0) {
29//! None => Err("invalid header length"),
30//! Some(&1) => Ok(Version::Version1),
31//! Some(&2) => Ok(Version::Version2),
32//! Some(_) => Err("invalid version"),
33//! }
34//! }
35//!
36//! let version = parse_version(&[1, 2, 3, 4]);
37//! match version {
38//! Ok(v) => println!("working with version: {v:?}"),
39//! Err(e) => println!("error parsing header: {e:?}"),
40//! }
41//! ```
42//!
43//! Pattern matching on [`Result`]s is clear and straightforward for
44//! simple cases, but [`Result`] comes with some convenience methods
45//! that make working with it more succinct.
46//!
47//! ```
48//! // The `is_ok` and `is_err` methods do what they say.
49//! let good_result: Result<i32, i32> = Ok(10);
50//! let bad_result: Result<i32, i32> = Err(10);
51//! assert!(good_result.is_ok() && !good_result.is_err());
52//! assert!(bad_result.is_err() && !bad_result.is_ok());
53//!
54//! // `map` and `map_err` consume the `Result` and produce another.
55//! let good_result: Result<i32, i32> = good_result.map(|i| i + 1);
56//! let bad_result: Result<i32, i32> = bad_result.map_err(|i| i - 1);
57//! assert_eq!(good_result, Ok(11));
58//! assert_eq!(bad_result, Err(9));
59//!
60//! // Use `and_then` to continue the computation.
61//! let good_result: Result<bool, i32> = good_result.and_then(|i| Ok(i == 11));
62//! assert_eq!(good_result, Ok(true));
63//!
64//! // Use `or_else` to handle the error.
65//! let bad_result: Result<i32, i32> = bad_result.or_else(|i| Ok(i + 20));
66//! assert_eq!(bad_result, Ok(29));
67//!
68//! // Consume the result and return the contents with `unwrap`.
69//! let final_awesome_result = good_result.unwrap();
70//! assert!(final_awesome_result)
71//! ```
72//!
73//! # Results must be used
74//!
75//! A common problem with using return values to indicate errors is
76//! that it is easy to ignore the return value, thus failing to handle
77//! the error. [`Result`] is annotated with the `#[must_use]` attribute,
78//! which will cause the compiler to issue a warning when a Result
79//! value is ignored. This makes [`Result`] especially useful with
80//! functions that may encounter errors but don't otherwise return a
81//! useful value.
82//!
83//! Consider the [`write_all`] method defined for I/O types
84//! by the [`Write`] trait:
85//!
86//! ```
87//! use std::io;
88//!
89//! trait Write {
90//! fn write_all(&mut self, bytes: &[u8]) -> Result<(), io::Error>;
91//! }
92//! ```
93//!
94//! *Note: The actual definition of [`Write`] uses [`io::Result`], which
95//! is just a synonym for <code>[Result]<T, [io::Error]></code>.*
96//!
97//! This method doesn't produce a value, but the write may
98//! fail. It's crucial to handle the error case, and *not* write
99//! something like this:
100//!
101//! ```no_run
102//! # #![allow(unused_must_use)] // \o/
103//! use std::fs::File;
104//! use std::io::prelude::*;
105//!
106//! let mut file = File::create("valuable_data.txt").unwrap();
107//! // If `write_all` errors, then we'll never know, because the return
108//! // value is ignored.
109//! file.write_all(b"important message");
110//! ```
111//!
112//! If you *do* write that in Rust, the compiler will give you a
113//! warning (by default, controlled by the `unused_must_use` lint).
114//!
115//! You might instead, if you don't want to handle the error, simply
116//! assert success with [`expect`]. This will panic if the
117//! write fails, providing a marginally useful message indicating why:
118//!
119//! ```no_run
120//! use std::fs::File;
121//! use std::io::prelude::*;
122//!
123//! let mut file = File::create("valuable_data.txt").unwrap();
124//! file.write_all(b"important message").expect("failed to write message");
125//! ```
126//!
127//! You might also simply assert success:
128//!
129//! ```no_run
130//! # use std::fs::File;
131//! # use std::io::prelude::*;
132//! # let mut file = File::create("valuable_data.txt").unwrap();
133//! assert!(file.write_all(b"important message").is_ok());
134//! ```
135//!
136//! Or propagate the error up the call stack with [`?`]:
137//!
138//! ```
139//! # use std::fs::File;
140//! # use std::io::prelude::*;
141//! # use std::io;
142//! # #[allow(dead_code)]
143//! fn write_message() -> io::Result<()> {
144//! let mut file = File::create("valuable_data.txt")?;
145//! file.write_all(b"important message")?;
146//! Ok(())
147//! }
148//! ```
149//!
150//! # The question mark operator, `?`
151//!
152//! When writing code that calls many functions that return the
153//! [`Result`] type, the error handling can be tedious. The question mark
154//! operator, [`?`], hides some of the boilerplate of propagating errors
155//! up the call stack.
156//!
157//! It replaces this:
158//!
159//! ```
160//! # #![allow(dead_code)]
161//! use std::fs::File;
162//! use std::io::prelude::*;
163//! use std::io;
164//!
165//! struct Info {
166//! name: String,
167//! age: i32,
168//! rating: i32,
169//! }
170//!
171//! fn write_info(info: &Info) -> io::Result<()> {
172//! // Early return on error
173//! let mut file = match File::create("my_best_friends.txt") {
174//! Err(e) => return Err(e),
175//! Ok(f) => f,
176//! };
177//! if let Err(e) = file.write_all(format!("name: {}\n", info.name).as_bytes()) {
178//! return Err(e)
179//! }
180//! if let Err(e) = file.write_all(format!("age: {}\n", info.age).as_bytes()) {
181//! return Err(e)
182//! }
183//! if let Err(e) = file.write_all(format!("rating: {}\n", info.rating).as_bytes()) {
184//! return Err(e)
185//! }
186//! Ok(())
187//! }
188//! ```
189//!
190//! With this:
191//!
192//! ```
193//! # #![allow(dead_code)]
194//! use std::fs::File;
195//! use std::io::prelude::*;
196//! use std::io;
197//!
198//! struct Info {
199//! name: String,
200//! age: i32,
201//! rating: i32,
202//! }
203//!
204//! fn write_info(info: &Info) -> io::Result<()> {
205//! let mut file = File::create("my_best_friends.txt")?;
206//! // Early return on error
207//! file.write_all(format!("name: {}\n", info.name).as_bytes())?;
208//! file.write_all(format!("age: {}\n", info.age).as_bytes())?;
209//! file.write_all(format!("rating: {}\n", info.rating).as_bytes())?;
210//! Ok(())
211//! }
212//! ```
213//!
214//! *It's much nicer!*
215//!
216//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped value, unless the result
217//! is [`Err`], in which case [`Err`] is returned early from the enclosing function.
218//!
219//! [`?`] can be used in functions that return [`Result`] because of the
220//! early return of [`Err`] that it provides.
221//!
222//! [`expect`]: Result::expect
223//! [`Write`]: ../../std/io/trait.Write.html "io::Write"
224//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all "io::Write::write_all"
225//! [`io::Result`]: ../../std/io/type.Result.html "io::Result"
226//! [`?`]: crate::ops::Try
227//! [`Ok(T)`]: Ok
228//! [`Err(E)`]: Err
229//! [io::Error]: ../../std/io/struct.Error.html "io::Error"
230//!
231//! # Representation
232//!
233//! In some cases, [`Result<T, E>`] will gain the same size, alignment, and ABI
234//! guarantees as [`Option<U>`] has. One of either the `T` or `E` type must be a
235//! type that qualifies for the `Option` [representation guarantees][opt-rep],
236//! and the *other* type must meet all of the following conditions:
237//! * Is a zero-sized type with alignment 1 (a "1-ZST").
238//! * Has no fields.
239//! * Does not have the `#[non_exhaustive]` attribute.
240//!
241//! For example, `NonZeroI32` qualifies for the `Option` representation
242//! guarantees, and `()` is a zero-sized type with alignment 1, no fields, and
243//! it isn't `non_exhaustive`. This means that both `Result<NonZeroI32, ()>` and
244//! `Result<(), NonZeroI32>` have the same size, alignment, and ABI guarantees
245//! as `Option<NonZeroI32>`. The only difference is the implied semantics:
246//! * `Option<NonZeroI32>` is "a non-zero i32 might be present"
247//! * `Result<NonZeroI32, ()>` is "a non-zero i32 success result, if any"
248//! * `Result<(), NonZeroI32>` is "a non-zero i32 error result, if any"
249//!
250//! [opt-rep]: ../option/index.html#representation "Option Representation"
251//!
252//! # Method overview
253//!
254//! In addition to working with pattern matching, [`Result`] provides a
255//! wide variety of different methods.
256//!
257//! ## Querying the variant
258//!
259//! The [`is_ok`] and [`is_err`] methods return [`true`] if the [`Result`]
260//! is [`Ok`] or [`Err`], respectively.
261//!
262//! The [`is_ok_and`] and [`is_err_and`] methods apply the provided function
263//! to the contents of the [`Result`] to produce a boolean value. If the [`Result`] does not have the expected variant
264//! then [`false`] is returned instead without executing the function.
265//!
266//! [`is_err`]: Result::is_err
267//! [`is_ok`]: Result::is_ok
268//! [`is_ok_and`]: Result::is_ok_and
269//! [`is_err_and`]: Result::is_err_and
270//!
271//! ## Adapters for working with references
272//!
273//! * [`as_ref`] converts from `&Result<T, E>` to `Result<&T, &E>`
274//! * [`as_mut`] converts from `&mut Result<T, E>` to `Result<&mut T, &mut E>`
275//! * [`as_deref`] converts from `&Result<T, E>` to `Result<&T::Target, &E>`
276//! * [`as_deref_mut`] converts from `&mut Result<T, E>` to
277//! `Result<&mut T::Target, &mut E>`
278//!
279//! [`as_deref`]: Result::as_deref
280//! [`as_deref_mut`]: Result::as_deref_mut
281//! [`as_mut`]: Result::as_mut
282//! [`as_ref`]: Result::as_ref
283//!
284//! ## Extracting contained values
285//!
286//! These methods extract the contained value in a [`Result<T, E>`] when it
287//! is the [`Ok`] variant. If the [`Result`] is [`Err`]:
288//!
289//! * [`expect`] panics with a provided custom message
290//! * [`unwrap`] panics with a generic message
291//! * [`unwrap_or`] returns the provided default value
292//! * [`unwrap_or_default`] returns the default value of the type `T`
293//! (which must implement the [`Default`] trait)
294//! * [`unwrap_or_else`] returns the result of evaluating the provided
295//! function
296//! * [`unwrap_unchecked`] produces *[undefined behavior]*
297//!
298//! The panicking methods [`expect`] and [`unwrap`] require `E` to
299//! implement the [`Debug`] trait.
300//!
301//! [`Debug`]: crate::fmt::Debug
302//! [`expect`]: Result::expect
303//! [`unwrap`]: Result::unwrap
304//! [`unwrap_or`]: Result::unwrap_or
305//! [`unwrap_or_default`]: Result::unwrap_or_default
306//! [`unwrap_or_else`]: Result::unwrap_or_else
307//! [`unwrap_unchecked`]: Result::unwrap_unchecked
308//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
309//!
310//! These methods extract the contained value in a [`Result<T, E>`] when it
311//! is the [`Err`] variant. They require `T` to implement the [`Debug`]
312//! trait. If the [`Result`] is [`Ok`]:
313//!
314//! * [`expect_err`] panics with a provided custom message
315//! * [`unwrap_err`] panics with a generic message
316//! * [`unwrap_err_unchecked`] produces *[undefined behavior]*
317//!
318//! [`Debug`]: crate::fmt::Debug
319//! [`expect_err`]: Result::expect_err
320//! [`unwrap_err`]: Result::unwrap_err
321//! [`unwrap_err_unchecked`]: Result::unwrap_err_unchecked
322//! [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
323//!
324//! ## Transforming contained values
325//!
326//! These methods transform [`Result`] to [`Option`]:
327//!
328//! * [`err`][Result::err] transforms [`Result<T, E>`] into [`Option<E>`],
329//! mapping [`Err(e)`] to [`Some(e)`] and [`Ok(v)`] to [`None`]
330//! * [`ok`][Result::ok] transforms [`Result<T, E>`] into [`Option<T>`],
331//! mapping [`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`]
332//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an
333//! [`Option`] of a [`Result`]
334//!
335// Do NOT add link reference definitions for `err` or `ok`, because they
336// will generate numerous incorrect URLs for `Err` and `Ok` elsewhere, due
337// to case folding.
338//!
339//! [`Err(e)`]: Err
340//! [`Ok(v)`]: Ok
341//! [`Some(e)`]: Option::Some
342//! [`Some(v)`]: Option::Some
343//! [`transpose`]: Result::transpose
344//!
345//! These methods transform the contained value of the [`Ok`] variant:
346//!
347//! * [`map`] transforms [`Result<T, E>`] into [`Result<U, E>`] by applying
348//! the provided function to the contained value of [`Ok`] and leaving
349//! [`Err`] values unchanged
350//! * [`inspect`] takes ownership of the [`Result`], applies the
351//! provided function to the contained value by reference,
352//! and then returns the [`Result`]
353//!
354//! [`map`]: Result::map
355//! [`inspect`]: Result::inspect
356//!
357//! These methods transform the contained value of the [`Err`] variant:
358//!
359//! * [`map_err`] transforms [`Result<T, E>`] into [`Result<T, F>`] by
360//! applying the provided function to the contained value of [`Err`] and
361//! leaving [`Ok`] values unchanged
362//! * [`inspect_err`] takes ownership of the [`Result`], applies the
363//! provided function to the contained value of [`Err`] by reference,
364//! and then returns the [`Result`]
365//!
366//! [`map_err`]: Result::map_err
367//! [`inspect_err`]: Result::inspect_err
368//!
369//! These methods transform a [`Result<T, E>`] into a value of a possibly
370//! different type `U`:
371//!
372//! * [`map_or`] applies the provided function to the contained value of
373//! [`Ok`], or returns the provided default value if the [`Result`] is
374//! [`Err`]
375//! * [`map_or_else`] applies the provided function to the contained value
376//! of [`Ok`], or applies the provided default fallback function to the
377//! contained value of [`Err`]
378//!
379//! [`map_or`]: Result::map_or
380//! [`map_or_else`]: Result::map_or_else
381//!
382//! ## Boolean operators
383//!
384//! These methods treat the [`Result`] as a boolean value, where [`Ok`]
385//! acts like [`true`] and [`Err`] acts like [`false`]. There are two
386//! categories of these methods: ones that take a [`Result`] as input, and
387//! ones that take a function as input (to be lazily evaluated).
388//!
389//! The [`and`] and [`or`] methods take another [`Result`] as input, and
390//! produce a [`Result`] as output. The [`and`] method can produce a
391//! [`Result<U, E>`] value having a different inner type `U` than
392//! [`Result<T, E>`]. The [`or`] method can produce a [`Result<T, F>`]
393//! value having a different error type `F` than [`Result<T, E>`].
394//!
395//! | method | self | input | output |
396//! |---------|----------|-----------|----------|
397//! | [`and`] | `Err(e)` | (ignored) | `Err(e)` |
398//! | [`and`] | `Ok(x)` | `Err(d)` | `Err(d)` |
399//! | [`and`] | `Ok(x)` | `Ok(y)` | `Ok(y)` |
400//! | [`or`] | `Err(e)` | `Err(d)` | `Err(d)` |
401//! | [`or`] | `Err(e)` | `Ok(y)` | `Ok(y)` |
402//! | [`or`] | `Ok(x)` | (ignored) | `Ok(x)` |
403//!
404//! [`and`]: Result::and
405//! [`or`]: Result::or
406//!
407//! The [`and_then`] and [`or_else`] methods take a function as input, and
408//! only evaluate the function when they need to produce a new value. The
409//! [`and_then`] method can produce a [`Result<U, E>`] value having a
410//! different inner type `U` than [`Result<T, E>`]. The [`or_else`] method
411//! can produce a [`Result<T, F>`] value having a different error type `F`
412//! than [`Result<T, E>`].
413//!
414//! | method | self | function input | function result | output |
415//! |--------------|----------|----------------|-----------------|----------|
416//! | [`and_then`] | `Err(e)` | (not provided) | (not evaluated) | `Err(e)` |
417//! | [`and_then`] | `Ok(x)` | `x` | `Err(d)` | `Err(d)` |
418//! | [`and_then`] | `Ok(x)` | `x` | `Ok(y)` | `Ok(y)` |
419//! | [`or_else`] | `Err(e)` | `e` | `Err(d)` | `Err(d)` |
420//! | [`or_else`] | `Err(e)` | `e` | `Ok(y)` | `Ok(y)` |
421//! | [`or_else`] | `Ok(x)` | (not provided) | (not evaluated) | `Ok(x)` |
422//!
423//! [`and_then`]: Result::and_then
424//! [`or_else`]: Result::or_else
425//!
426//! ## Comparison operators
427//!
428//! If `T` and `E` both implement [`PartialOrd`] then [`Result<T, E>`] will
429//! derive its [`PartialOrd`] implementation. With this order, an [`Ok`]
430//! compares as less than any [`Err`], while two [`Ok`] or two [`Err`]
431//! compare as their contained values would in `T` or `E` respectively. If `T`
432//! and `E` both also implement [`Ord`], then so does [`Result<T, E>`].
433//!
434//! ```
435//! assert!(Ok(1) < Err(0));
436//! let x: Result<i32, ()> = Ok(0);
437//! let y = Ok(1);
438//! assert!(x < y);
439//! let x: Result<(), i32> = Err(0);
440//! let y = Err(1);
441//! assert!(x < y);
442//! ```
443//!
444//! ## Iterating over `Result`
445//!
446//! A [`Result`] can be iterated over. This can be helpful if you need an
447//! iterator that is conditionally empty. The iterator will either produce
448//! a single value (when the [`Result`] is [`Ok`]), or produce no values
449//! (when the [`Result`] is [`Err`]). For example, [`into_iter`] acts like
450//! [`once(v)`] if the [`Result`] is [`Ok(v)`], and like [`empty()`] if the
451//! [`Result`] is [`Err`].
452//!
453//! [`Ok(v)`]: Ok
454//! [`empty()`]: crate::iter::empty
455//! [`once(v)`]: crate::iter::once
456//!
457//! Iterators over [`Result<T, E>`] come in three types:
458//!
459//! * [`into_iter`] consumes the [`Result`] and produces the contained
460//! value
461//! * [`iter`] produces an immutable reference of type `&T` to the
462//! contained value
463//! * [`iter_mut`] produces a mutable reference of type `&mut T` to the
464//! contained value
465//!
466//! See [Iterating over `Option`] for examples of how this can be useful.
467//!
468//! [Iterating over `Option`]: crate::option#iterating-over-option
469//! [`into_iter`]: Result::into_iter
470//! [`iter`]: Result::iter
471//! [`iter_mut`]: Result::iter_mut
472//!
473//! You might want to use an iterator chain to do multiple instances of an
474//! operation that can fail, but would like to ignore failures while
475//! continuing to process the successful results. In this example, we take
476//! advantage of the iterable nature of [`Result`] to select only the
477//! [`Ok`] values using [`flatten`][Iterator::flatten].
478//!
479//! ```
480//! # use std::str::FromStr;
481//! let mut results = vec![];
482//! let mut errs = vec![];
483//! let nums: Vec<_> = ["17", "not a number", "99", "-27", "768"]
484//! .into_iter()
485//! .map(u8::from_str)
486//! // Save clones of the raw `Result` values to inspect
487//! .inspect(|x| results.push(x.clone()))
488//! // Challenge: explain how this captures only the `Err` values
489//! .inspect(|x| errs.extend(x.clone().err()))
490//! .flatten()
491//! .collect();
492//! assert_eq!(errs.len(), 3);
493//! assert_eq!(nums, [17, 99]);
494//! println!("results {results:?}");
495//! println!("errs {errs:?}");
496//! println!("nums {nums:?}");
497//! ```
498//!
499//! ## Collecting into `Result`
500//!
501//! [`Result`] implements the [`FromIterator`][impl-FromIterator] trait,
502//! which allows an iterator over [`Result`] values to be collected into a
503//! [`Result`] of a collection of each contained value of the original
504//! [`Result`] values, or [`Err`] if any of the elements was [`Err`].
505//!
506//! [impl-FromIterator]: Result#impl-FromIterator%3CResult%3CA,+E%3E%3E-for-Result%3CV,+E%3E
507//!
508//! ```
509//! let v = [Ok(2), Ok(4), Err("err!"), Ok(8)];
510//! let res: Result<Vec<_>, &str> = v.into_iter().collect();
511//! assert_eq!(res, Err("err!"));
512//! let v = [Ok(2), Ok(4), Ok(8)];
513//! let res: Result<Vec<_>, &str> = v.into_iter().collect();
514//! assert_eq!(res, Ok(vec![2, 4, 8]));
515//! ```
516//!
517//! [`Result`] also implements the [`Product`][impl-Product] and
518//! [`Sum`][impl-Sum] traits, allowing an iterator over [`Result`] values
519//! to provide the [`product`][Iterator::product] and
520//! [`sum`][Iterator::sum] methods.
521//!
522//! [impl-Product]: Result#impl-Product%3CResult%3CU,+E%3E%3E-for-Result%3CT,+E%3E
523//! [impl-Sum]: Result#impl-Sum%3CResult%3CU,+E%3E%3E-for-Result%3CT,+E%3E
524//!
525//! ```
526//! let v = [Err("error!"), Ok(1), Ok(2), Ok(3), Err("foo")];
527//! let res: Result<i32, &str> = v.into_iter().sum();
528//! assert_eq!(res, Err("error!"));
529//! let v = [Ok(1), Ok(2), Ok(21)];
530//! let res: Result<i32, &str> = v.into_iter().product();
531//! assert_eq!(res, Ok(42));
532//! ```
533
534#![stable(feature = "rust1", since = "1.0.0")]
535
536use crate::iter::{self, FusedIterator, TrustedLen};
537use crate::ops::{self, ControlFlow, Deref, DerefMut};
538use crate::{convert, fmt, hint};
539
540/// `Result` is a type that represents either success ([`Ok`]) or failure ([`Err`]).
541///
542/// See the [module documentation](self) for details.
543#[doc(search_unbox)]
544#[derive(Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
545#[must_use = "this `Result` may be an `Err` variant, which should be handled"]
546#[rustc_diagnostic_item = "Result"]
547#[stable(feature = "rust1", since = "1.0.0")]
548pub enum Result<T, E> {
549 /// Contains the success value
550 #[lang = "Ok"]
551 #[stable(feature = "rust1", since = "1.0.0")]
552 Ok(#[stable(feature = "rust1", since = "1.0.0")] T),
553
554 /// Contains the error value
555 #[lang = "Err"]
556 #[stable(feature = "rust1", since = "1.0.0")]
557 Err(#[stable(feature = "rust1", since = "1.0.0")] E),
558}
559
560/////////////////////////////////////////////////////////////////////////////
561// Type implementation
562/////////////////////////////////////////////////////////////////////////////
563
564impl<T, E> Result<T, E> {
565 /////////////////////////////////////////////////////////////////////////
566 // Querying the contained values
567 /////////////////////////////////////////////////////////////////////////
568
569 /// Returns `true` if the result is [`Ok`].
570 ///
571 /// # Examples
572 ///
573 /// ```
574 /// let x: Result<i32, &str> = Ok(-3);
575 /// assert_eq!(x.is_ok(), true);
576 ///
577 /// let x: Result<i32, &str> = Err("Some error message");
578 /// assert_eq!(x.is_ok(), false);
579 /// ```
580 #[must_use = "if you intended to assert that this is ok, consider `.unwrap()` instead"]
581 #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")]
582 #[inline]
583 #[stable(feature = "rust1", since = "1.0.0")]
584 pub const fn is_ok(&self) -> bool {
585 matches!(*self, Ok(_))
586 }
587
588 /// Returns `true` if the result is [`Ok`] and the value inside of it matches a predicate.
589 ///
590 /// # Examples
591 ///
592 /// ```
593 /// let x: Result<u32, &str> = Ok(2);
594 /// assert_eq!(x.is_ok_and(|x| x > 1), true);
595 ///
596 /// let x: Result<u32, &str> = Ok(0);
597 /// assert_eq!(x.is_ok_and(|x| x > 1), false);
598 ///
599 /// let x: Result<u32, &str> = Err("hey");
600 /// assert_eq!(x.is_ok_and(|x| x > 1), false);
601 ///
602 /// let x: Result<String, &str> = Ok("ownership".to_string());
603 /// assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
604 /// println!("still alive {:?}", x);
605 /// ```
606 #[must_use]
607 #[inline]
608 #[stable(feature = "is_some_and", since = "1.70.0")]
609 pub fn is_ok_and(self, f: impl FnOnce(T) -> bool) -> bool {
610 match self {
611 Err(_) => false,
612 Ok(x) => f(x),
613 }
614 }
615
616 /// Returns `true` if the result is [`Err`].
617 ///
618 /// # Examples
619 ///
620 /// ```
621 /// let x: Result<i32, &str> = Ok(-3);
622 /// assert_eq!(x.is_err(), false);
623 ///
624 /// let x: Result<i32, &str> = Err("Some error message");
625 /// assert_eq!(x.is_err(), true);
626 /// ```
627 #[must_use = "if you intended to assert that this is err, consider `.unwrap_err()` instead"]
628 #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")]
629 #[inline]
630 #[stable(feature = "rust1", since = "1.0.0")]
631 pub const fn is_err(&self) -> bool {
632 !self.is_ok()
633 }
634
635 /// Returns `true` if the result is [`Err`] and the value inside of it matches a predicate.
636 ///
637 /// # Examples
638 ///
639 /// ```
640 /// use std::io::{Error, ErrorKind};
641 ///
642 /// let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
643 /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);
644 ///
645 /// let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
646 /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);
647 ///
648 /// let x: Result<u32, Error> = Ok(123);
649 /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);
650 ///
651 /// let x: Result<u32, String> = Err("ownership".to_string());
652 /// assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
653 /// println!("still alive {:?}", x);
654 /// ```
655 #[must_use]
656 #[inline]
657 #[stable(feature = "is_some_and", since = "1.70.0")]
658 pub fn is_err_and(self, f: impl FnOnce(E) -> bool) -> bool {
659 match self {
660 Ok(_) => false,
661 Err(e) => f(e),
662 }
663 }
664
665 /////////////////////////////////////////////////////////////////////////
666 // Adapter for each variant
667 /////////////////////////////////////////////////////////////////////////
668
669 /// Converts from `Result<T, E>` to [`Option<T>`].
670 ///
671 /// Converts `self` into an [`Option<T>`], consuming `self`,
672 /// and discarding the error, if any.
673 ///
674 /// # Examples
675 ///
676 /// ```
677 /// let x: Result<u32, &str> = Ok(2);
678 /// assert_eq!(x.ok(), Some(2));
679 ///
680 /// let x: Result<u32, &str> = Err("Nothing here");
681 /// assert_eq!(x.ok(), None);
682 /// ```
683 #[inline]
684 #[stable(feature = "rust1", since = "1.0.0")]
685 #[rustc_diagnostic_item = "result_ok_method"]
686 pub fn ok(self) -> Option<T> {
687 match self {
688 Ok(x) => Some(x),
689 Err(_) => None,
690 }
691 }
692
693 /// Converts from `Result<T, E>` to [`Option<E>`].
694 ///
695 /// Converts `self` into an [`Option<E>`], consuming `self`,
696 /// and discarding the success value, if any.
697 ///
698 /// # Examples
699 ///
700 /// ```
701 /// let x: Result<u32, &str> = Ok(2);
702 /// assert_eq!(x.err(), None);
703 ///
704 /// let x: Result<u32, &str> = Err("Nothing here");
705 /// assert_eq!(x.err(), Some("Nothing here"));
706 /// ```
707 #[inline]
708 #[stable(feature = "rust1", since = "1.0.0")]
709 pub fn err(self) -> Option<E> {
710 match self {
711 Ok(_) => None,
712 Err(x) => Some(x),
713 }
714 }
715
716 /////////////////////////////////////////////////////////////////////////
717 // Adapter for working with references
718 /////////////////////////////////////////////////////////////////////////
719
720 /// Converts from `&Result<T, E>` to `Result<&T, &E>`.
721 ///
722 /// Produces a new `Result`, containing a reference
723 /// into the original, leaving the original in place.
724 ///
725 /// # Examples
726 ///
727 /// ```
728 /// let x: Result<u32, &str> = Ok(2);
729 /// assert_eq!(x.as_ref(), Ok(&2));
730 ///
731 /// let x: Result<u32, &str> = Err("Error");
732 /// assert_eq!(x.as_ref(), Err(&"Error"));
733 /// ```
734 #[inline]
735 #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")]
736 #[stable(feature = "rust1", since = "1.0.0")]
737 pub const fn as_ref(&self) -> Result<&T, &E> {
738 match *self {
739 Ok(ref x) => Ok(x),
740 Err(ref x) => Err(x),
741 }
742 }
743
744 /// Converts from `&mut Result<T, E>` to `Result<&mut T, &mut E>`.
745 ///
746 /// # Examples
747 ///
748 /// ```
749 /// fn mutate(r: &mut Result<i32, i32>) {
750 /// match r.as_mut() {
751 /// Ok(v) => *v = 42,
752 /// Err(e) => *e = 0,
753 /// }
754 /// }
755 ///
756 /// let mut x: Result<i32, i32> = Ok(2);
757 /// mutate(&mut x);
758 /// assert_eq!(x.unwrap(), 42);
759 ///
760 /// let mut x: Result<i32, i32> = Err(13);
761 /// mutate(&mut x);
762 /// assert_eq!(x.unwrap_err(), 0);
763 /// ```
764 #[inline]
765 #[stable(feature = "rust1", since = "1.0.0")]
766 #[rustc_const_stable(feature = "const_result", since = "1.83.0")]
767 pub const fn as_mut(&mut self) -> Result<&mut T, &mut E> {
768 match *self {
769 Ok(ref mut x) => Ok(x),
770 Err(ref mut x) => Err(x),
771 }
772 }
773
774 /////////////////////////////////////////////////////////////////////////
775 // Transforming contained values
776 /////////////////////////////////////////////////////////////////////////
777
778 /// Maps a `Result<T, E>` to `Result<U, E>` by applying a function to a
779 /// contained [`Ok`] value, leaving an [`Err`] value untouched.
780 ///
781 /// This function can be used to compose the results of two functions.
782 ///
783 /// # Examples
784 ///
785 /// Print the numbers on each line of a string multiplied by two.
786 ///
787 /// ```
788 /// let line = "1\n2\n3\n4\n";
789 ///
790 /// for num in line.lines() {
791 /// match num.parse::<i32>().map(|i| i * 2) {
792 /// Ok(n) => println!("{n}"),
793 /// Err(..) => {}
794 /// }
795 /// }
796 /// ```
797 #[inline]
798 #[stable(feature = "rust1", since = "1.0.0")]
799 pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Result<U, E> {
800 match self {
801 Ok(t) => Ok(op(t)),
802 Err(e) => Err(e),
803 }
804 }
805
806 /// Returns the provided default (if [`Err`]), or
807 /// applies a function to the contained value (if [`Ok`]).
808 ///
809 /// Arguments passed to `map_or` are eagerly evaluated; if you are passing
810 /// the result of a function call, it is recommended to use [`map_or_else`],
811 /// which is lazily evaluated.
812 ///
813 /// [`map_or_else`]: Result::map_or_else
814 ///
815 /// # Examples
816 ///
817 /// ```
818 /// let x: Result<_, &str> = Ok("foo");
819 /// assert_eq!(x.map_or(42, |v| v.len()), 3);
820 ///
821 /// let x: Result<&str, _> = Err("bar");
822 /// assert_eq!(x.map_or(42, |v| v.len()), 42);
823 /// ```
824 #[inline]
825 #[stable(feature = "result_map_or", since = "1.41.0")]
826 #[must_use = "if you don't need the returned value, use `if let` instead"]
827 pub fn map_or<U, F: FnOnce(T) -> U>(self, default: U, f: F) -> U {
828 match self {
829 Ok(t) => f(t),
830 Err(_) => default,
831 }
832 }
833
834 /// Maps a `Result<T, E>` to `U` by applying fallback function `default` to
835 /// a contained [`Err`] value, or function `f` to a contained [`Ok`] value.
836 ///
837 /// This function can be used to unpack a successful result
838 /// while handling an error.
839 ///
840 ///
841 /// # Examples
842 ///
843 /// ```
844 /// let k = 21;
845 ///
846 /// let x : Result<_, &str> = Ok("foo");
847 /// assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);
848 ///
849 /// let x : Result<&str, _> = Err("bar");
850 /// assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);
851 /// ```
852 #[inline]
853 #[stable(feature = "result_map_or_else", since = "1.41.0")]
854 pub fn map_or_else<U, D: FnOnce(E) -> U, F: FnOnce(T) -> U>(self, default: D, f: F) -> U {
855 match self {
856 Ok(t) => f(t),
857 Err(e) => default(e),
858 }
859 }
860
861 /// Maps a `Result<T, E>` to a `U` by applying function `f` to the contained
862 /// value if the result is [`Ok`], otherwise if [`Err`], returns the
863 /// [default value] for the type `U`.
864 ///
865 /// # Examples
866 ///
867 /// ```
868 /// #![feature(result_option_map_or_default)]
869 ///
870 /// let x: Result<_, &str> = Ok("foo");
871 /// let y: Result<&str, _> = Err("bar");
872 ///
873 /// assert_eq!(x.map_or_default(|x| x.len()), 3);
874 /// assert_eq!(y.map_or_default(|y| y.len()), 0);
875 /// ```
876 ///
877 /// [default value]: Default::default
878 #[inline]
879 #[unstable(feature = "result_option_map_or_default", issue = "138099")]
880 pub fn map_or_default<U, F>(self, f: F) -> U
881 where
882 U: Default,
883 F: FnOnce(T) -> U,
884 {
885 match self {
886 Ok(t) => f(t),
887 Err(_) => U::default(),
888 }
889 }
890
891 /// Maps a `Result<T, E>` to `Result<T, F>` by applying a function to a
892 /// contained [`Err`] value, leaving an [`Ok`] value untouched.
893 ///
894 /// This function can be used to pass through a successful result while handling
895 /// an error.
896 ///
897 ///
898 /// # Examples
899 ///
900 /// ```
901 /// fn stringify(x: u32) -> String { format!("error code: {x}") }
902 ///
903 /// let x: Result<u32, u32> = Ok(2);
904 /// assert_eq!(x.map_err(stringify), Ok(2));
905 ///
906 /// let x: Result<u32, u32> = Err(13);
907 /// assert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));
908 /// ```
909 #[inline]
910 #[stable(feature = "rust1", since = "1.0.0")]
911 pub fn map_err<F, O: FnOnce(E) -> F>(self, op: O) -> Result<T, F> {
912 match self {
913 Ok(t) => Ok(t),
914 Err(e) => Err(op(e)),
915 }
916 }
917
918 /// Calls a function with a reference to the contained value if [`Ok`].
919 ///
920 /// Returns the original result.
921 ///
922 /// # Examples
923 ///
924 /// ```
925 /// let x: u8 = "4"
926 /// .parse::<u8>()
927 /// .inspect(|x| println!("original: {x}"))
928 /// .map(|x| x.pow(3))
929 /// .expect("failed to parse number");
930 /// ```
931 #[inline]
932 #[stable(feature = "result_option_inspect", since = "1.76.0")]
933 pub fn inspect<F: FnOnce(&T)>(self, f: F) -> Self {
934 if let Ok(ref t) = self {
935 f(t);
936 }
937
938 self
939 }
940
941 /// Calls a function with a reference to the contained value if [`Err`].
942 ///
943 /// Returns the original result.
944 ///
945 /// # Examples
946 ///
947 /// ```
948 /// use std::{fs, io};
949 ///
950 /// fn read() -> io::Result<String> {
951 /// fs::read_to_string("address.txt")
952 /// .inspect_err(|e| eprintln!("failed to read file: {e}"))
953 /// }
954 /// ```
955 #[inline]
956 #[stable(feature = "result_option_inspect", since = "1.76.0")]
957 pub fn inspect_err<F: FnOnce(&E)>(self, f: F) -> Self {
958 if let Err(ref e) = self {
959 f(e);
960 }
961
962 self
963 }
964
965 /// Converts from `Result<T, E>` (or `&Result<T, E>`) to `Result<&<T as Deref>::Target, &E>`.
966 ///
967 /// Coerces the [`Ok`] variant of the original [`Result`] via [`Deref`](crate::ops::Deref)
968 /// and returns the new [`Result`].
969 ///
970 /// # Examples
971 ///
972 /// ```
973 /// let x: Result<String, u32> = Ok("hello".to_string());
974 /// let y: Result<&str, &u32> = Ok("hello");
975 /// assert_eq!(x.as_deref(), y);
976 ///
977 /// let x: Result<String, u32> = Err(42);
978 /// let y: Result<&str, &u32> = Err(&42);
979 /// assert_eq!(x.as_deref(), y);
980 /// ```
981 #[inline]
982 #[stable(feature = "inner_deref", since = "1.47.0")]
983 pub fn as_deref(&self) -> Result<&T::Target, &E>
984 where
985 T: Deref,
986 {
987 self.as_ref().map(|t| t.deref())
988 }
989
990 /// Converts from `Result<T, E>` (or `&mut Result<T, E>`) to `Result<&mut <T as DerefMut>::Target, &mut E>`.
991 ///
992 /// Coerces the [`Ok`] variant of the original [`Result`] via [`DerefMut`](crate::ops::DerefMut)
993 /// and returns the new [`Result`].
994 ///
995 /// # Examples
996 ///
997 /// ```
998 /// let mut s = "HELLO".to_string();
999 /// let mut x: Result<String, u32> = Ok("hello".to_string());
1000 /// let y: Result<&mut str, &mut u32> = Ok(&mut s);
1001 /// assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
1002 ///
1003 /// let mut i = 42;
1004 /// let mut x: Result<String, u32> = Err(42);
1005 /// let y: Result<&mut str, &mut u32> = Err(&mut i);
1006 /// assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);
1007 /// ```
1008 #[inline]
1009 #[stable(feature = "inner_deref", since = "1.47.0")]
1010 pub fn as_deref_mut(&mut self) -> Result<&mut T::Target, &mut E>
1011 where
1012 T: DerefMut,
1013 {
1014 self.as_mut().map(|t| t.deref_mut())
1015 }
1016
1017 /////////////////////////////////////////////////////////////////////////
1018 // Iterator constructors
1019 /////////////////////////////////////////////////////////////////////////
1020
1021 /// Returns an iterator over the possibly contained value.
1022 ///
1023 /// The iterator yields one value if the result is [`Result::Ok`], otherwise none.
1024 ///
1025 /// # Examples
1026 ///
1027 /// ```
1028 /// let x: Result<u32, &str> = Ok(7);
1029 /// assert_eq!(x.iter().next(), Some(&7));
1030 ///
1031 /// let x: Result<u32, &str> = Err("nothing!");
1032 /// assert_eq!(x.iter().next(), None);
1033 /// ```
1034 #[inline]
1035 #[stable(feature = "rust1", since = "1.0.0")]
1036 pub fn iter(&self) -> Iter<'_, T> {
1037 Iter { inner: self.as_ref().ok() }
1038 }
1039
1040 /// Returns a mutable iterator over the possibly contained value.
1041 ///
1042 /// The iterator yields one value if the result is [`Result::Ok`], otherwise none.
1043 ///
1044 /// # Examples
1045 ///
1046 /// ```
1047 /// let mut x: Result<u32, &str> = Ok(7);
1048 /// match x.iter_mut().next() {
1049 /// Some(v) => *v = 40,
1050 /// None => {},
1051 /// }
1052 /// assert_eq!(x, Ok(40));
1053 ///
1054 /// let mut x: Result<u32, &str> = Err("nothing!");
1055 /// assert_eq!(x.iter_mut().next(), None);
1056 /// ```
1057 #[inline]
1058 #[stable(feature = "rust1", since = "1.0.0")]
1059 pub fn iter_mut(&mut self) -> IterMut<'_, T> {
1060 IterMut { inner: self.as_mut().ok() }
1061 }
1062
1063 /////////////////////////////////////////////////////////////////////////
1064 // Extract a value
1065 /////////////////////////////////////////////////////////////////////////
1066
1067 /// Returns the contained [`Ok`] value, consuming the `self` value.
1068 ///
1069 /// Because this function may panic, its use is generally discouraged.
1070 /// Instead, prefer to use pattern matching and handle the [`Err`]
1071 /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or
1072 /// [`unwrap_or_default`].
1073 ///
1074 /// [`unwrap_or`]: Result::unwrap_or
1075 /// [`unwrap_or_else`]: Result::unwrap_or_else
1076 /// [`unwrap_or_default`]: Result::unwrap_or_default
1077 ///
1078 /// # Panics
1079 ///
1080 /// Panics if the value is an [`Err`], with a panic message including the
1081 /// passed message, and the content of the [`Err`].
1082 ///
1083 ///
1084 /// # Examples
1085 ///
1086 /// ```should_panic
1087 /// let x: Result<u32, &str> = Err("emergency failure");
1088 /// x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
1089 /// ```
1090 ///
1091 /// # Recommended Message Style
1092 ///
1093 /// We recommend that `expect` messages are used to describe the reason you
1094 /// _expect_ the `Result` should be `Ok`.
1095 ///
1096 /// ```should_panic
1097 /// let path = std::env::var("IMPORTANT_PATH")
1098 /// .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
1099 /// ```
1100 ///
1101 /// **Hint**: If you're having trouble remembering how to phrase expect
1102 /// error messages remember to focus on the word "should" as in "env
1103 /// variable should be set by blah" or "the given binary should be available
1104 /// and executable by the current user".
1105 ///
1106 /// For more detail on expect message styles and the reasoning behind our recommendation please
1107 /// refer to the section on ["Common Message
1108 /// Styles"](../../std/error/index.html#common-message-styles) in the
1109 /// [`std::error`](../../std/error/index.html) module docs.
1110 #[inline]
1111 #[track_caller]
1112 #[stable(feature = "result_expect", since = "1.4.0")]
1113 pub fn expect(self, msg: &str) -> T
1114 where
1115 E: fmt::Debug,
1116 {
1117 match self {
1118 Ok(t) => t,
1119 Err(e) => unwrap_failed(msg, &e),
1120 }
1121 }
1122
1123 /// Returns the contained [`Ok`] value, consuming the `self` value.
1124 ///
1125 /// Because this function may panic, its use is generally discouraged.
1126 /// Panics are meant for unrecoverable errors, and
1127 /// [may abort the entire program][panic-abort].
1128 ///
1129 /// Instead, prefer to use [the `?` (try) operator][try-operator], or pattern matching
1130 /// to handle the [`Err`] case explicitly, or call [`unwrap_or`],
1131 /// [`unwrap_or_else`], or [`unwrap_or_default`].
1132 ///
1133 /// [panic-abort]: https://doc.rust-lang.org/book/ch09-01-unrecoverable-errors-with-panic.html
1134 /// [try-operator]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator
1135 /// [`unwrap_or`]: Result::unwrap_or
1136 /// [`unwrap_or_else`]: Result::unwrap_or_else
1137 /// [`unwrap_or_default`]: Result::unwrap_or_default
1138 ///
1139 /// # Panics
1140 ///
1141 /// Panics if the value is an [`Err`], with a panic message provided by the
1142 /// [`Err`]'s value.
1143 ///
1144 ///
1145 /// # Examples
1146 ///
1147 /// Basic usage:
1148 ///
1149 /// ```
1150 /// let x: Result<u32, &str> = Ok(2);
1151 /// assert_eq!(x.unwrap(), 2);
1152 /// ```
1153 ///
1154 /// ```should_panic
1155 /// let x: Result<u32, &str> = Err("emergency failure");
1156 /// x.unwrap(); // panics with `emergency failure`
1157 /// ```
1158 #[inline(always)]
1159 #[track_caller]
1160 #[stable(feature = "rust1", since = "1.0.0")]
1161 pub fn unwrap(self) -> T
1162 where
1163 E: fmt::Debug,
1164 {
1165 match self {
1166 Ok(t) => t,
1167 Err(e) => unwrap_failed("called `Result::unwrap()` on an `Err` value", &e),
1168 }
1169 }
1170
1171 /// Returns the contained [`Ok`] value or a default
1172 ///
1173 /// Consumes the `self` argument then, if [`Ok`], returns the contained
1174 /// value, otherwise if [`Err`], returns the default value for that
1175 /// type.
1176 ///
1177 /// # Examples
1178 ///
1179 /// Converts a string to an integer, turning poorly-formed strings
1180 /// into 0 (the default value for integers). [`parse`] converts
1181 /// a string to any other type that implements [`FromStr`], returning an
1182 /// [`Err`] on error.
1183 ///
1184 /// ```
1185 /// let good_year_from_input = "1909";
1186 /// let bad_year_from_input = "190blarg";
1187 /// let good_year = good_year_from_input.parse().unwrap_or_default();
1188 /// let bad_year = bad_year_from_input.parse().unwrap_or_default();
1189 ///
1190 /// assert_eq!(1909, good_year);
1191 /// assert_eq!(0, bad_year);
1192 /// ```
1193 ///
1194 /// [`parse`]: str::parse
1195 /// [`FromStr`]: crate::str::FromStr
1196 #[inline]
1197 #[stable(feature = "result_unwrap_or_default", since = "1.16.0")]
1198 pub fn unwrap_or_default(self) -> T
1199 where
1200 T: Default,
1201 {
1202 match self {
1203 Ok(x) => x,
1204 Err(_) => Default::default(),
1205 }
1206 }
1207
1208 /// Returns the contained [`Err`] value, consuming the `self` value.
1209 ///
1210 /// # Panics
1211 ///
1212 /// Panics if the value is an [`Ok`], with a panic message including the
1213 /// passed message, and the content of the [`Ok`].
1214 ///
1215 ///
1216 /// # Examples
1217 ///
1218 /// ```should_panic
1219 /// let x: Result<u32, &str> = Ok(10);
1220 /// x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
1221 /// ```
1222 #[inline]
1223 #[track_caller]
1224 #[stable(feature = "result_expect_err", since = "1.17.0")]
1225 pub fn expect_err(self, msg: &str) -> E
1226 where
1227 T: fmt::Debug,
1228 {
1229 match self {
1230 Ok(t) => unwrap_failed(msg, &t),
1231 Err(e) => e,
1232 }
1233 }
1234
1235 /// Returns the contained [`Err`] value, consuming the `self` value.
1236 ///
1237 /// # Panics
1238 ///
1239 /// Panics if the value is an [`Ok`], with a custom panic message provided
1240 /// by the [`Ok`]'s value.
1241 ///
1242 /// # Examples
1243 ///
1244 /// ```should_panic
1245 /// let x: Result<u32, &str> = Ok(2);
1246 /// x.unwrap_err(); // panics with `2`
1247 /// ```
1248 ///
1249 /// ```
1250 /// let x: Result<u32, &str> = Err("emergency failure");
1251 /// assert_eq!(x.unwrap_err(), "emergency failure");
1252 /// ```
1253 #[inline]
1254 #[track_caller]
1255 #[stable(feature = "rust1", since = "1.0.0")]
1256 pub fn unwrap_err(self) -> E
1257 where
1258 T: fmt::Debug,
1259 {
1260 match self {
1261 Ok(t) => unwrap_failed("called `Result::unwrap_err()` on an `Ok` value", &t),
1262 Err(e) => e,
1263 }
1264 }
1265
1266 /// Returns the contained [`Ok`] value, but never panics.
1267 ///
1268 /// Unlike [`unwrap`], this method is known to never panic on the
1269 /// result types it is implemented for. Therefore, it can be used
1270 /// instead of `unwrap` as a maintainability safeguard that will fail
1271 /// to compile if the error type of the `Result` is later changed
1272 /// to an error that can actually occur.
1273 ///
1274 /// [`unwrap`]: Result::unwrap
1275 ///
1276 /// # Examples
1277 ///
1278 /// ```
1279 /// # #![feature(never_type)]
1280 /// # #![feature(unwrap_infallible)]
1281 ///
1282 /// fn only_good_news() -> Result<String, !> {
1283 /// Ok("this is fine".into())
1284 /// }
1285 ///
1286 /// let s: String = only_good_news().into_ok();
1287 /// println!("{s}");
1288 /// ```
1289 #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")]
1290 #[inline]
1291 pub fn into_ok(self) -> T
1292 where
1293 E: Into<!>,
1294 {
1295 match self {
1296 Ok(x) => x,
1297 Err(e) => e.into(),
1298 }
1299 }
1300
1301 /// Returns the contained [`Err`] value, but never panics.
1302 ///
1303 /// Unlike [`unwrap_err`], this method is known to never panic on the
1304 /// result types it is implemented for. Therefore, it can be used
1305 /// instead of `unwrap_err` as a maintainability safeguard that will fail
1306 /// to compile if the ok type of the `Result` is later changed
1307 /// to a type that can actually occur.
1308 ///
1309 /// [`unwrap_err`]: Result::unwrap_err
1310 ///
1311 /// # Examples
1312 ///
1313 /// ```
1314 /// # #![feature(never_type)]
1315 /// # #![feature(unwrap_infallible)]
1316 ///
1317 /// fn only_bad_news() -> Result<!, String> {
1318 /// Err("Oops, it failed".into())
1319 /// }
1320 ///
1321 /// let error: String = only_bad_news().into_err();
1322 /// println!("{error}");
1323 /// ```
1324 #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")]
1325 #[inline]
1326 pub fn into_err(self) -> E
1327 where
1328 T: Into<!>,
1329 {
1330 match self {
1331 Ok(x) => x.into(),
1332 Err(e) => e,
1333 }
1334 }
1335
1336 ////////////////////////////////////////////////////////////////////////
1337 // Boolean operations on the values, eager and lazy
1338 /////////////////////////////////////////////////////////////////////////
1339
1340 /// Returns `res` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`.
1341 ///
1342 /// Arguments passed to `and` are eagerly evaluated; if you are passing the
1343 /// result of a function call, it is recommended to use [`and_then`], which is
1344 /// lazily evaluated.
1345 ///
1346 /// [`and_then`]: Result::and_then
1347 ///
1348 /// # Examples
1349 ///
1350 /// ```
1351 /// let x: Result<u32, &str> = Ok(2);
1352 /// let y: Result<&str, &str> = Err("late error");
1353 /// assert_eq!(x.and(y), Err("late error"));
1354 ///
1355 /// let x: Result<u32, &str> = Err("early error");
1356 /// let y: Result<&str, &str> = Ok("foo");
1357 /// assert_eq!(x.and(y), Err("early error"));
1358 ///
1359 /// let x: Result<u32, &str> = Err("not a 2");
1360 /// let y: Result<&str, &str> = Err("late error");
1361 /// assert_eq!(x.and(y), Err("not a 2"));
1362 ///
1363 /// let x: Result<u32, &str> = Ok(2);
1364 /// let y: Result<&str, &str> = Ok("different result type");
1365 /// assert_eq!(x.and(y), Ok("different result type"));
1366 /// ```
1367 #[inline]
1368 #[stable(feature = "rust1", since = "1.0.0")]
1369 pub fn and<U>(self, res: Result<U, E>) -> Result<U, E> {
1370 match self {
1371 Ok(_) => res,
1372 Err(e) => Err(e),
1373 }
1374 }
1375
1376 /// Calls `op` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`.
1377 ///
1378 ///
1379 /// This function can be used for control flow based on `Result` values.
1380 ///
1381 /// # Examples
1382 ///
1383 /// ```
1384 /// fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
1385 /// x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
1386 /// }
1387 ///
1388 /// assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
1389 /// assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
1390 /// assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
1391 /// ```
1392 ///
1393 /// Often used to chain fallible operations that may return [`Err`].
1394 ///
1395 /// ```
1396 /// use std::{io::ErrorKind, path::Path};
1397 ///
1398 /// // Note: on Windows "/" maps to "C:\"
1399 /// let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
1400 /// assert!(root_modified_time.is_ok());
1401 ///
1402 /// let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
1403 /// assert!(should_fail.is_err());
1404 /// assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
1405 /// ```
1406 #[inline]
1407 #[stable(feature = "rust1", since = "1.0.0")]
1408 #[rustc_confusables("flat_map", "flatmap")]
1409 pub fn and_then<U, F: FnOnce(T) -> Result<U, E>>(self, op: F) -> Result<U, E> {
1410 match self {
1411 Ok(t) => op(t),
1412 Err(e) => Err(e),
1413 }
1414 }
1415
1416 /// Returns `res` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`.
1417 ///
1418 /// Arguments passed to `or` are eagerly evaluated; if you are passing the
1419 /// result of a function call, it is recommended to use [`or_else`], which is
1420 /// lazily evaluated.
1421 ///
1422 /// [`or_else`]: Result::or_else
1423 ///
1424 /// # Examples
1425 ///
1426 /// ```
1427 /// let x: Result<u32, &str> = Ok(2);
1428 /// let y: Result<u32, &str> = Err("late error");
1429 /// assert_eq!(x.or(y), Ok(2));
1430 ///
1431 /// let x: Result<u32, &str> = Err("early error");
1432 /// let y: Result<u32, &str> = Ok(2);
1433 /// assert_eq!(x.or(y), Ok(2));
1434 ///
1435 /// let x: Result<u32, &str> = Err("not a 2");
1436 /// let y: Result<u32, &str> = Err("late error");
1437 /// assert_eq!(x.or(y), Err("late error"));
1438 ///
1439 /// let x: Result<u32, &str> = Ok(2);
1440 /// let y: Result<u32, &str> = Ok(100);
1441 /// assert_eq!(x.or(y), Ok(2));
1442 /// ```
1443 #[inline]
1444 #[stable(feature = "rust1", since = "1.0.0")]
1445 pub fn or<F>(self, res: Result<T, F>) -> Result<T, F> {
1446 match self {
1447 Ok(v) => Ok(v),
1448 Err(_) => res,
1449 }
1450 }
1451
1452 /// Calls `op` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`.
1453 ///
1454 /// This function can be used for control flow based on result values.
1455 ///
1456 ///
1457 /// # Examples
1458 ///
1459 /// ```
1460 /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
1461 /// fn err(x: u32) -> Result<u32, u32> { Err(x) }
1462 ///
1463 /// assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
1464 /// assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
1465 /// assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
1466 /// assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
1467 /// ```
1468 #[inline]
1469 #[stable(feature = "rust1", since = "1.0.0")]
1470 pub fn or_else<F, O: FnOnce(E) -> Result<T, F>>(self, op: O) -> Result<T, F> {
1471 match self {
1472 Ok(t) => Ok(t),
1473 Err(e) => op(e),
1474 }
1475 }
1476
1477 /// Returns the contained [`Ok`] value or a provided default.
1478 ///
1479 /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing
1480 /// the result of a function call, it is recommended to use [`unwrap_or_else`],
1481 /// which is lazily evaluated.
1482 ///
1483 /// [`unwrap_or_else`]: Result::unwrap_or_else
1484 ///
1485 /// # Examples
1486 ///
1487 /// ```
1488 /// let default = 2;
1489 /// let x: Result<u32, &str> = Ok(9);
1490 /// assert_eq!(x.unwrap_or(default), 9);
1491 ///
1492 /// let x: Result<u32, &str> = Err("error");
1493 /// assert_eq!(x.unwrap_or(default), default);
1494 /// ```
1495 #[inline]
1496 #[stable(feature = "rust1", since = "1.0.0")]
1497 pub fn unwrap_or(self, default: T) -> T {
1498 match self {
1499 Ok(t) => t,
1500 Err(_) => default,
1501 }
1502 }
1503
1504 /// Returns the contained [`Ok`] value or computes it from a closure.
1505 ///
1506 ///
1507 /// # Examples
1508 ///
1509 /// ```
1510 /// fn count(x: &str) -> usize { x.len() }
1511 ///
1512 /// assert_eq!(Ok(2).unwrap_or_else(count), 2);
1513 /// assert_eq!(Err("foo").unwrap_or_else(count), 3);
1514 /// ```
1515 #[inline]
1516 #[track_caller]
1517 #[stable(feature = "rust1", since = "1.0.0")]
1518 pub fn unwrap_or_else<F: FnOnce(E) -> T>(self, op: F) -> T {
1519 match self {
1520 Ok(t) => t,
1521 Err(e) => op(e),
1522 }
1523 }
1524
1525 /// Returns the contained [`Ok`] value, consuming the `self` value,
1526 /// without checking that the value is not an [`Err`].
1527 ///
1528 /// # Safety
1529 ///
1530 /// Calling this method on an [`Err`] is *[undefined behavior]*.
1531 ///
1532 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
1533 ///
1534 /// # Examples
1535 ///
1536 /// ```
1537 /// let x: Result<u32, &str> = Ok(2);
1538 /// assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
1539 /// ```
1540 ///
1541 /// ```no_run
1542 /// let x: Result<u32, &str> = Err("emergency failure");
1543 /// unsafe { x.unwrap_unchecked(); } // Undefined behavior!
1544 /// ```
1545 #[inline]
1546 #[track_caller]
1547 #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")]
1548 pub unsafe fn unwrap_unchecked(self) -> T {
1549 match self {
1550 Ok(t) => t,
1551 // SAFETY: the safety contract must be upheld by the caller.
1552 Err(_) => unsafe { hint::unreachable_unchecked() },
1553 }
1554 }
1555
1556 /// Returns the contained [`Err`] value, consuming the `self` value,
1557 /// without checking that the value is not an [`Ok`].
1558 ///
1559 /// # Safety
1560 ///
1561 /// Calling this method on an [`Ok`] is *[undefined behavior]*.
1562 ///
1563 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
1564 ///
1565 /// # Examples
1566 ///
1567 /// ```no_run
1568 /// let x: Result<u32, &str> = Ok(2);
1569 /// unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
1570 /// ```
1571 ///
1572 /// ```
1573 /// let x: Result<u32, &str> = Err("emergency failure");
1574 /// assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
1575 /// ```
1576 #[inline]
1577 #[track_caller]
1578 #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")]
1579 pub unsafe fn unwrap_err_unchecked(self) -> E {
1580 match self {
1581 // SAFETY: the safety contract must be upheld by the caller.
1582 Ok(_) => unsafe { hint::unreachable_unchecked() },
1583 Err(e) => e,
1584 }
1585 }
1586}
1587
1588impl<T, E> Result<&T, E> {
1589 /// Maps a `Result<&T, E>` to a `Result<T, E>` by copying the contents of the
1590 /// `Ok` part.
1591 ///
1592 /// # Examples
1593 ///
1594 /// ```
1595 /// let val = 12;
1596 /// let x: Result<&i32, i32> = Ok(&val);
1597 /// assert_eq!(x, Ok(&12));
1598 /// let copied = x.copied();
1599 /// assert_eq!(copied, Ok(12));
1600 /// ```
1601 #[inline]
1602 #[stable(feature = "result_copied", since = "1.59.0")]
1603 #[rustc_const_stable(feature = "const_result", since = "1.83.0")]
1604 #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
1605 pub const fn copied(self) -> Result<T, E>
1606 where
1607 T: Copy,
1608 {
1609 // FIXME(const-hack): this implementation, which sidesteps using `Result::map` since it's not const
1610 // ready yet, should be reverted when possible to avoid code repetition
1611 match self {
1612 Ok(&v) => Ok(v),
1613 Err(e) => Err(e),
1614 }
1615 }
1616
1617 /// Maps a `Result<&T, E>` to a `Result<T, E>` by cloning the contents of the
1618 /// `Ok` part.
1619 ///
1620 /// # Examples
1621 ///
1622 /// ```
1623 /// let val = 12;
1624 /// let x: Result<&i32, i32> = Ok(&val);
1625 /// assert_eq!(x, Ok(&12));
1626 /// let cloned = x.cloned();
1627 /// assert_eq!(cloned, Ok(12));
1628 /// ```
1629 #[inline]
1630 #[stable(feature = "result_cloned", since = "1.59.0")]
1631 pub fn cloned(self) -> Result<T, E>
1632 where
1633 T: Clone,
1634 {
1635 self.map(|t| t.clone())
1636 }
1637}
1638
1639impl<T, E> Result<&mut T, E> {
1640 /// Maps a `Result<&mut T, E>` to a `Result<T, E>` by copying the contents of the
1641 /// `Ok` part.
1642 ///
1643 /// # Examples
1644 ///
1645 /// ```
1646 /// let mut val = 12;
1647 /// let x: Result<&mut i32, i32> = Ok(&mut val);
1648 /// assert_eq!(x, Ok(&mut 12));
1649 /// let copied = x.copied();
1650 /// assert_eq!(copied, Ok(12));
1651 /// ```
1652 #[inline]
1653 #[stable(feature = "result_copied", since = "1.59.0")]
1654 #[rustc_const_stable(feature = "const_result", since = "1.83.0")]
1655 #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
1656 pub const fn copied(self) -> Result<T, E>
1657 where
1658 T: Copy,
1659 {
1660 // FIXME(const-hack): this implementation, which sidesteps using `Result::map` since it's not const
1661 // ready yet, should be reverted when possible to avoid code repetition
1662 match self {
1663 Ok(&mut v) => Ok(v),
1664 Err(e) => Err(e),
1665 }
1666 }
1667
1668 /// Maps a `Result<&mut T, E>` to a `Result<T, E>` by cloning the contents of the
1669 /// `Ok` part.
1670 ///
1671 /// # Examples
1672 ///
1673 /// ```
1674 /// let mut val = 12;
1675 /// let x: Result<&mut i32, i32> = Ok(&mut val);
1676 /// assert_eq!(x, Ok(&mut 12));
1677 /// let cloned = x.cloned();
1678 /// assert_eq!(cloned, Ok(12));
1679 /// ```
1680 #[inline]
1681 #[stable(feature = "result_cloned", since = "1.59.0")]
1682 pub fn cloned(self) -> Result<T, E>
1683 where
1684 T: Clone,
1685 {
1686 self.map(|t| t.clone())
1687 }
1688}
1689
1690impl<T, E> Result<Option<T>, E> {
1691 /// Transposes a `Result` of an `Option` into an `Option` of a `Result`.
1692 ///
1693 /// `Ok(None)` will be mapped to `None`.
1694 /// `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))`.
1695 ///
1696 /// # Examples
1697 ///
1698 /// ```
1699 /// #[derive(Debug, Eq, PartialEq)]
1700 /// struct SomeErr;
1701 ///
1702 /// let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
1703 /// let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
1704 /// assert_eq!(x.transpose(), y);
1705 /// ```
1706 #[inline]
1707 #[stable(feature = "transpose_result", since = "1.33.0")]
1708 #[rustc_const_stable(feature = "const_result", since = "1.83.0")]
1709 #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
1710 pub const fn transpose(self) -> Option<Result<T, E>> {
1711 match self {
1712 Ok(Some(x)) => Some(Ok(x)),
1713 Ok(None) => None,
1714 Err(e) => Some(Err(e)),
1715 }
1716 }
1717}
1718
1719impl<T, E> Result<Result<T, E>, E> {
1720 /// Converts from `Result<Result<T, E>, E>` to `Result<T, E>`
1721 ///
1722 /// # Examples
1723 ///
1724 /// ```
1725 /// let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
1726 /// assert_eq!(Ok("hello"), x.flatten());
1727 ///
1728 /// let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
1729 /// assert_eq!(Err(6), x.flatten());
1730 ///
1731 /// let x: Result<Result<&'static str, u32>, u32> = Err(6);
1732 /// assert_eq!(Err(6), x.flatten());
1733 /// ```
1734 ///
1735 /// Flattening only removes one level of nesting at a time:
1736 ///
1737 /// ```
1738 /// let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
1739 /// assert_eq!(Ok(Ok("hello")), x.flatten());
1740 /// assert_eq!(Ok("hello"), x.flatten().flatten());
1741 /// ```
1742 #[inline]
1743 #[stable(feature = "result_flattening", since = "CURRENT_RUSTC_VERSION")]
1744 #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
1745 #[rustc_const_stable(feature = "result_flattening", since = "CURRENT_RUSTC_VERSION")]
1746 pub const fn flatten(self) -> Result<T, E> {
1747 // FIXME(const-hack): could be written with `and_then`
1748 match self {
1749 Ok(inner) => inner,
1750 Err(e) => Err(e),
1751 }
1752 }
1753}
1754
1755// This is a separate function to reduce the code size of the methods
1756#[cfg(not(feature = "panic_immediate_abort"))]
1757#[inline(never)]
1758#[cold]
1759#[track_caller]
1760fn unwrap_failed(msg: &str, error: &dyn fmt::Debug) -> ! {
1761 panic!("{msg}: {error:?}")
1762}
1763
1764// This is a separate function to avoid constructing a `dyn Debug`
1765// that gets immediately thrown away, since vtables don't get cleaned up
1766// by dead code elimination if a trait object is constructed even if it goes
1767// unused
1768#[cfg(feature = "panic_immediate_abort")]
1769#[inline]
1770#[cold]
1771#[track_caller]
1772fn unwrap_failed<T>(_msg: &str, _error: &T) -> ! {
1773 panic!()
1774}
1775
1776/////////////////////////////////////////////////////////////////////////////
1777// Trait implementations
1778/////////////////////////////////////////////////////////////////////////////
1779
1780#[stable(feature = "rust1", since = "1.0.0")]
1781impl<T, E> Clone for Result<T, E>
1782where
1783 T: Clone,
1784 E: Clone,
1785{
1786 #[inline]
1787 fn clone(&self) -> Self {
1788 match self {
1789 Ok(x: &T) => Ok(x.clone()),
1790 Err(x: &E) => Err(x.clone()),
1791 }
1792 }
1793
1794 #[inline]
1795 fn clone_from(&mut self, source: &Self) {
1796 match (self, source) {
1797 (Ok(to: &mut T), Ok(from: &T)) => to.clone_from(source:from),
1798 (Err(to: &mut E), Err(from: &E)) => to.clone_from(source:from),
1799 (to: &mut Result, from: &Result) => *to = from.clone(),
1800 }
1801 }
1802}
1803
1804#[unstable(feature = "ergonomic_clones", issue = "132290")]
1805impl<T, E> crate::clone::UseCloned for Result<T, E>
1806where
1807 T: crate::clone::UseCloned,
1808 E: crate::clone::UseCloned,
1809{
1810}
1811
1812#[stable(feature = "rust1", since = "1.0.0")]
1813impl<T, E> IntoIterator for Result<T, E> {
1814 type Item = T;
1815 type IntoIter = IntoIter<T>;
1816
1817 /// Returns a consuming iterator over the possibly contained value.
1818 ///
1819 /// The iterator yields one value if the result is [`Result::Ok`], otherwise none.
1820 ///
1821 /// # Examples
1822 ///
1823 /// ```
1824 /// let x: Result<u32, &str> = Ok(5);
1825 /// let v: Vec<u32> = x.into_iter().collect();
1826 /// assert_eq!(v, [5]);
1827 ///
1828 /// let x: Result<u32, &str> = Err("nothing!");
1829 /// let v: Vec<u32> = x.into_iter().collect();
1830 /// assert_eq!(v, []);
1831 /// ```
1832 #[inline]
1833 fn into_iter(self) -> IntoIter<T> {
1834 IntoIter { inner: self.ok() }
1835 }
1836}
1837
1838#[stable(since = "1.4.0", feature = "result_iter")]
1839impl<'a, T, E> IntoIterator for &'a Result<T, E> {
1840 type Item = &'a T;
1841 type IntoIter = Iter<'a, T>;
1842
1843 fn into_iter(self) -> Iter<'a, T> {
1844 self.iter()
1845 }
1846}
1847
1848#[stable(since = "1.4.0", feature = "result_iter")]
1849impl<'a, T, E> IntoIterator for &'a mut Result<T, E> {
1850 type Item = &'a mut T;
1851 type IntoIter = IterMut<'a, T>;
1852
1853 fn into_iter(self) -> IterMut<'a, T> {
1854 self.iter_mut()
1855 }
1856}
1857
1858/////////////////////////////////////////////////////////////////////////////
1859// The Result Iterators
1860/////////////////////////////////////////////////////////////////////////////
1861
1862/// An iterator over a reference to the [`Ok`] variant of a [`Result`].
1863///
1864/// The iterator yields one value if the result is [`Ok`], otherwise none.
1865///
1866/// Created by [`Result::iter`].
1867#[derive(Debug)]
1868#[stable(feature = "rust1", since = "1.0.0")]
1869pub struct Iter<'a, T: 'a> {
1870 inner: Option<&'a T>,
1871}
1872
1873#[stable(feature = "rust1", since = "1.0.0")]
1874impl<'a, T> Iterator for Iter<'a, T> {
1875 type Item = &'a T;
1876
1877 #[inline]
1878 fn next(&mut self) -> Option<&'a T> {
1879 self.inner.take()
1880 }
1881 #[inline]
1882 fn size_hint(&self) -> (usize, Option<usize>) {
1883 let n: usize = if self.inner.is_some() { 1 } else { 0 };
1884 (n, Some(n))
1885 }
1886}
1887
1888#[stable(feature = "rust1", since = "1.0.0")]
1889impl<'a, T> DoubleEndedIterator for Iter<'a, T> {
1890 #[inline]
1891 fn next_back(&mut self) -> Option<&'a T> {
1892 self.inner.take()
1893 }
1894}
1895
1896#[stable(feature = "rust1", since = "1.0.0")]
1897impl<T> ExactSizeIterator for Iter<'_, T> {}
1898
1899#[stable(feature = "fused", since = "1.26.0")]
1900impl<T> FusedIterator for Iter<'_, T> {}
1901
1902#[unstable(feature = "trusted_len", issue = "37572")]
1903unsafe impl<A> TrustedLen for Iter<'_, A> {}
1904
1905#[stable(feature = "rust1", since = "1.0.0")]
1906impl<T> Clone for Iter<'_, T> {
1907 #[inline]
1908 fn clone(&self) -> Self {
1909 Iter { inner: self.inner }
1910 }
1911}
1912
1913/// An iterator over a mutable reference to the [`Ok`] variant of a [`Result`].
1914///
1915/// Created by [`Result::iter_mut`].
1916#[derive(Debug)]
1917#[stable(feature = "rust1", since = "1.0.0")]
1918pub struct IterMut<'a, T: 'a> {
1919 inner: Option<&'a mut T>,
1920}
1921
1922#[stable(feature = "rust1", since = "1.0.0")]
1923impl<'a, T> Iterator for IterMut<'a, T> {
1924 type Item = &'a mut T;
1925
1926 #[inline]
1927 fn next(&mut self) -> Option<&'a mut T> {
1928 self.inner.take()
1929 }
1930 #[inline]
1931 fn size_hint(&self) -> (usize, Option<usize>) {
1932 let n: usize = if self.inner.is_some() { 1 } else { 0 };
1933 (n, Some(n))
1934 }
1935}
1936
1937#[stable(feature = "rust1", since = "1.0.0")]
1938impl<'a, T> DoubleEndedIterator for IterMut<'a, T> {
1939 #[inline]
1940 fn next_back(&mut self) -> Option<&'a mut T> {
1941 self.inner.take()
1942 }
1943}
1944
1945#[stable(feature = "rust1", since = "1.0.0")]
1946impl<T> ExactSizeIterator for IterMut<'_, T> {}
1947
1948#[stable(feature = "fused", since = "1.26.0")]
1949impl<T> FusedIterator for IterMut<'_, T> {}
1950
1951#[unstable(feature = "trusted_len", issue = "37572")]
1952unsafe impl<A> TrustedLen for IterMut<'_, A> {}
1953
1954/// An iterator over the value in a [`Ok`] variant of a [`Result`].
1955///
1956/// The iterator yields one value if the result is [`Ok`], otherwise none.
1957///
1958/// This struct is created by the [`into_iter`] method on
1959/// [`Result`] (provided by the [`IntoIterator`] trait).
1960///
1961/// [`into_iter`]: IntoIterator::into_iter
1962#[derive(Clone, Debug)]
1963#[stable(feature = "rust1", since = "1.0.0")]
1964pub struct IntoIter<T> {
1965 inner: Option<T>,
1966}
1967
1968#[stable(feature = "rust1", since = "1.0.0")]
1969impl<T> Iterator for IntoIter<T> {
1970 type Item = T;
1971
1972 #[inline]
1973 fn next(&mut self) -> Option<T> {
1974 self.inner.take()
1975 }
1976 #[inline]
1977 fn size_hint(&self) -> (usize, Option<usize>) {
1978 let n: usize = if self.inner.is_some() { 1 } else { 0 };
1979 (n, Some(n))
1980 }
1981}
1982
1983#[stable(feature = "rust1", since = "1.0.0")]
1984impl<T> DoubleEndedIterator for IntoIter<T> {
1985 #[inline]
1986 fn next_back(&mut self) -> Option<T> {
1987 self.inner.take()
1988 }
1989}
1990
1991#[stable(feature = "rust1", since = "1.0.0")]
1992impl<T> ExactSizeIterator for IntoIter<T> {}
1993
1994#[stable(feature = "fused", since = "1.26.0")]
1995impl<T> FusedIterator for IntoIter<T> {}
1996
1997#[unstable(feature = "trusted_len", issue = "37572")]
1998unsafe impl<A> TrustedLen for IntoIter<A> {}
1999
2000/////////////////////////////////////////////////////////////////////////////
2001// FromIterator
2002/////////////////////////////////////////////////////////////////////////////
2003
2004#[stable(feature = "rust1", since = "1.0.0")]
2005impl<A, E, V: FromIterator<A>> FromIterator<Result<A, E>> for Result<V, E> {
2006 /// Takes each element in the `Iterator`: if it is an `Err`, no further
2007 /// elements are taken, and the `Err` is returned. Should no `Err` occur, a
2008 /// container with the values of each `Result` is returned.
2009 ///
2010 /// Here is an example which increments every integer in a vector,
2011 /// checking for overflow:
2012 ///
2013 /// ```
2014 /// let v = vec![1, 2];
2015 /// let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
2016 /// x.checked_add(1).ok_or("Overflow!")
2017 /// ).collect();
2018 /// assert_eq!(res, Ok(vec![2, 3]));
2019 /// ```
2020 ///
2021 /// Here is another example that tries to subtract one from another list
2022 /// of integers, this time checking for underflow:
2023 ///
2024 /// ```
2025 /// let v = vec![1, 2, 0];
2026 /// let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|
2027 /// x.checked_sub(1).ok_or("Underflow!")
2028 /// ).collect();
2029 /// assert_eq!(res, Err("Underflow!"));
2030 /// ```
2031 ///
2032 /// Here is a variation on the previous example, showing that no
2033 /// further elements are taken from `iter` after the first `Err`.
2034 ///
2035 /// ```
2036 /// let v = vec![3, 2, 1, 10];
2037 /// let mut shared = 0;
2038 /// let res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {
2039 /// shared += x;
2040 /// x.checked_sub(2).ok_or("Underflow!")
2041 /// }).collect();
2042 /// assert_eq!(res, Err("Underflow!"));
2043 /// assert_eq!(shared, 6);
2044 /// ```
2045 ///
2046 /// Since the third element caused an underflow, no further elements were taken,
2047 /// so the final value of `shared` is 6 (= `3 + 2 + 1`), not 16.
2048 #[inline]
2049 fn from_iter<I: IntoIterator<Item = Result<A, E>>>(iter: I) -> Result<V, E> {
2050 iter::try_process(iter.into_iter(), |i| i.collect())
2051 }
2052}
2053
2054#[unstable(feature = "try_trait_v2", issue = "84277")]
2055impl<T, E> ops::Try for Result<T, E> {
2056 type Output = T;
2057 type Residual = Result<convert::Infallible, E>;
2058
2059 #[inline]
2060 fn from_output(output: Self::Output) -> Self {
2061 Ok(output)
2062 }
2063
2064 #[inline]
2065 fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
2066 match self {
2067 Ok(v: T) => ControlFlow::Continue(v),
2068 Err(e: E) => ControlFlow::Break(Err(e)),
2069 }
2070 }
2071}
2072
2073#[unstable(feature = "try_trait_v2", issue = "84277")]
2074impl<T, E, F: From<E>> ops::FromResidual<Result<convert::Infallible, E>> for Result<T, F> {
2075 #[inline]
2076 #[track_caller]
2077 fn from_residual(residual: Result<convert::Infallible, E>) -> Self {
2078 match residual {
2079 Err(e: E) => Err(From::from(e)),
2080 }
2081 }
2082}
2083#[diagnostic::do_not_recommend]
2084#[unstable(feature = "try_trait_v2_yeet", issue = "96374")]
2085impl<T, E, F: From<E>> ops::FromResidual<ops::Yeet<E>> for Result<T, F> {
2086 #[inline]
2087 fn from_residual(ops::Yeet(e: E): ops::Yeet<E>) -> Self {
2088 Err(From::from(e))
2089 }
2090}
2091
2092#[unstable(feature = "try_trait_v2_residual", issue = "91285")]
2093impl<T, E> ops::Residual<T> for Result<convert::Infallible, E> {
2094 type TryType = Result<T, E>;
2095}
2096