Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err("hey");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err("Nothing here");\nassert_eq!(x.err(), Some("Nothing here"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err("Error");\nassert_eq!(x.as_ref(), Err(&"Error"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = "1\\n2\\n3\\n4\\n";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!("{n}"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err("bar");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err("bar");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!("error code: {x}") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&str, &u32> = Ok("hello");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = "HELLO".to_string();\nlet mut x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err("emergency failure");\nx.expect("Testing expect"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var("IMPORTANT_PATH")\n .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);let x: Result<u32, &str> = Err("emergency failure");\nx.unwrap(); // panics with `emergency failure`Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = "1909";\nlet bad_year_from_input = "190blarg";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a panic message including the\npassed message, and the content of the Ok.
let x: Result<u32, &str> = Ok(10);\nx.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a custom panic message provided\nby the Ok’s value.
let x: Result<u32, &str> = Ok(2);\nx.unwrap_err(); // panics with `2`let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(x.unwrap_err(), "emergency failure");unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok("this is fine".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!("{s}");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err("Oops, it failed".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!("{error}");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("late error"));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<&str, &str> = Ok("foo");\nassert_eq!(x.and(y), Err("early error"));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("not a 2"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok("different result type");\nassert_eq!(x.and(y), Ok("different result type"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));\nassert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows "/" maps to "C:\\"\nlet root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Err("late error"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err("error");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err("emergency failure");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");Maps a Result<&mut T, E> to a Result<T, E> by copying the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet copied = x.copied();\nassert_eq!(copied, Ok(12));Maps a Result<&mut T, E> to a Result<T, E> by cloning the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet cloned = x.cloned();\nassert_eq!(cloned, Ok(12));Transposes a Result of an Option into an Option of a Result.
Ok(None) will be mapped to None.\nOk(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).
#[derive(Debug, Eq, PartialEq)]\nstruct SomeErr;\n\nlet x: Result<Option<i32>, SomeErr> = Ok(Some(5));\nlet y: Option<Result<i32, SomeErr>> = Some(Ok(5));\nassert_eq!(x.transpose(), y);result_flattening)Converts from Result<Result<T, E>, E> to Result<T, E>
#![feature(result_flattening)]\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));\nassert_eq!(Ok("hello"), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));\nassert_eq!(Err(6), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Err(6);\nassert_eq!(Err(6), x.flatten());Flattening only removes one level of nesting at a time:
\n\n#![feature(result_flattening)]\nlet x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));\nassert_eq!(Ok(Ok("hello")), x.flatten());\nassert_eq!(Ok("hello"), x.flatten().flatten());Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or("Overflow!")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or("Underflow!")\n).collect();\nassert_eq!(res, Err("Underflow!"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or("Underflow!")\n}).collect();\nassert_eq!(res, Err("Underflow!"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
Returns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err("nothing!");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);try_trait_v2)Residual type. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err("Negative element found"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moreself and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec!["5", "10", "1", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec!["5", "10", "one", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err("hey");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err("Nothing here");\nassert_eq!(x.err(), Some("Nothing here"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err("Error");\nassert_eq!(x.as_ref(), Err(&"Error"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = "1\\n2\\n3\\n4\\n";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!("{n}"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err("bar");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err("bar");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!("error code: {x}") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&str, &u32> = Ok("hello");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = "HELLO".to_string();\nlet mut x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err("emergency failure");\nx.expect("Testing expect"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var("IMPORTANT_PATH")\n .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);let x: Result<u32, &str> = Err("emergency failure");\nx.unwrap(); // panics with `emergency failure`Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = "1909";\nlet bad_year_from_input = "190blarg";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a panic message including the\npassed message, and the content of the Ok.
let x: Result<u32, &str> = Ok(10);\nx.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a custom panic message provided\nby the Ok’s value.
let x: Result<u32, &str> = Ok(2);\nx.unwrap_err(); // panics with `2`let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(x.unwrap_err(), "emergency failure");unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok("this is fine".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!("{s}");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err("Oops, it failed".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!("{error}");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("late error"));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<&str, &str> = Ok("foo");\nassert_eq!(x.and(y), Err("early error"));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("not a 2"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok("different result type");\nassert_eq!(x.and(y), Ok("different result type"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));\nassert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows "/" maps to "C:\\"\nlet root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Err("late error"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err("error");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err("emergency failure");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or("Overflow!")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or("Underflow!")\n).collect();\nassert_eq!(res, Err("Underflow!"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or("Underflow!")\n}).collect();\nassert_eq!(res, Err("Underflow!"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
Returns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err("nothing!");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);try_trait_v2)Residual type. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err("Negative element found"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moreself and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec!["5", "10", "1", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec!["5", "10", "one", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err("hey");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err("Nothing here");\nassert_eq!(x.err(), Some("Nothing here"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err("Error");\nassert_eq!(x.as_ref(), Err(&"Error"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = "1\\n2\\n3\\n4\\n";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!("{n}"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err("bar");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err("bar");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!("error code: {x}") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&str, &u32> = Ok("hello");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = "HELLO".to_string();\nlet mut x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err("emergency failure");\nx.expect("Testing expect"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var("IMPORTANT_PATH")\n .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = "1909";\nlet bad_year_from_input = "190blarg";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok("this is fine".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!("{s}");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err("Oops, it failed".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!("{error}");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("late error"));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<&str, &str> = Ok("foo");\nassert_eq!(x.and(y), Err("early error"));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("not a 2"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok("different result type");\nassert_eq!(x.and(y), Ok("different result type"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));\nassert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows "/" maps to "C:\\"\nlet root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Err("late error"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err("error");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err("emergency failure");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");Transposes a Result of an Option into an Option of a Result.
Ok(None) will be mapped to None.\nOk(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).
#[derive(Debug, Eq, PartialEq)]\nstruct SomeErr;\n\nlet x: Result<Option<i32>, SomeErr> = Ok(Some(5));\nlet y: Option<Result<i32, SomeErr>> = Some(Ok(5));\nassert_eq!(x.transpose(), y);result_flattening)Converts from Result<Result<T, E>, E> to Result<T, E>
#![feature(result_flattening)]\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));\nassert_eq!(Ok("hello"), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));\nassert_eq!(Err(6), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Err(6);\nassert_eq!(Err(6), x.flatten());Flattening only removes one level of nesting at a time:
\n\n#![feature(result_flattening)]\nlet x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));\nassert_eq!(Ok(Ok("hello")), x.flatten());\nassert_eq!(Ok("hello"), x.flatten().flatten());Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or("Overflow!")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or("Underflow!")\n).collect();\nassert_eq!(res, Err("Underflow!"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or("Underflow!")\n}).collect();\nassert_eq!(res, Err("Underflow!"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
Returns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err("nothing!");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);try_trait_v2)Residual type. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err("Negative element found"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moreself and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec!["5", "10", "1", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec!["5", "10", "one", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err("hey");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err("Nothing here");\nassert_eq!(x.err(), Some("Nothing here"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err("Error");\nassert_eq!(x.as_ref(), Err(&"Error"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = "1\\n2\\n3\\n4\\n";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!("{n}"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err("bar");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err("bar");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!("error code: {x}") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&str, &u32> = Ok("hello");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = "HELLO".to_string();\nlet mut x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err("emergency failure");\nx.expect("Testing expect"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var("IMPORTANT_PATH")\n .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);let x: Result<u32, &str> = Err("emergency failure");\nx.unwrap(); // panics with `emergency failure`Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = "1909";\nlet bad_year_from_input = "190blarg";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a panic message including the\npassed message, and the content of the Ok.
let x: Result<u32, &str> = Ok(10);\nx.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a custom panic message provided\nby the Ok’s value.
let x: Result<u32, &str> = Ok(2);\nx.unwrap_err(); // panics with `2`let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(x.unwrap_err(), "emergency failure");unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok("this is fine".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!("{s}");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err("Oops, it failed".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!("{error}");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("late error"));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<&str, &str> = Ok("foo");\nassert_eq!(x.and(y), Err("early error"));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("not a 2"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok("different result type");\nassert_eq!(x.and(y), Ok("different result type"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));\nassert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows "/" maps to "C:\\"\nlet root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Err("late error"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err("error");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err("emergency failure");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");Maps a Result<&mut T, E> to a Result<T, E> by copying the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet copied = x.copied();\nassert_eq!(copied, Ok(12));Maps a Result<&mut T, E> to a Result<T, E> by cloning the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet cloned = x.cloned();\nassert_eq!(cloned, Ok(12));Transposes a Result of an Option into an Option of a Result.
Ok(None) will be mapped to None.\nOk(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).
#[derive(Debug, Eq, PartialEq)]\nstruct SomeErr;\n\nlet x: Result<Option<i32>, SomeErr> = Ok(Some(5));\nlet y: Option<Result<i32, SomeErr>> = Some(Ok(5));\nassert_eq!(x.transpose(), y);result_flattening)Converts from Result<Result<T, E>, E> to Result<T, E>
#![feature(result_flattening)]\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));\nassert_eq!(Ok("hello"), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));\nassert_eq!(Err(6), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Err(6);\nassert_eq!(Err(6), x.flatten());Flattening only removes one level of nesting at a time:
\n\n#![feature(result_flattening)]\nlet x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));\nassert_eq!(Ok(Ok("hello")), x.flatten());\nassert_eq!(Ok("hello"), x.flatten().flatten());Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or("Overflow!")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or("Underflow!")\n).collect();\nassert_eq!(res, Err("Underflow!"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or("Underflow!")\n}).collect();\nassert_eq!(res, Err("Underflow!"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
Returns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err("nothing!");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);try_trait_v2)Residual type. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err("Negative element found"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moreself and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec!["5", "10", "1", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec!["5", "10", "one", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err("hey");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err("Nothing here");\nassert_eq!(x.err(), Some("Nothing here"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err("Error");\nassert_eq!(x.as_ref(), Err(&"Error"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = "1\\n2\\n3\\n4\\n";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!("{n}"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err("bar");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok("foo");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err("bar");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!("error code: {x}") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err("error code: 13".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&str, &u32> = Ok("hello");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = "HELLO".to_string();\nlet mut x: Result<String, u32> = Ok("hello".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err("nothing!");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err("emergency failure");\nx.expect("Testing expect"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var("IMPORTANT_PATH")\n .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);let x: Result<u32, &str> = Err("emergency failure");\nx.unwrap(); // panics with `emergency failure`Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = "1909";\nlet bad_year_from_input = "190blarg";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a panic message including the\npassed message, and the content of the Ok.
let x: Result<u32, &str> = Ok(10);\nx.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a custom panic message provided\nby the Ok’s value.
let x: Result<u32, &str> = Ok(2);\nx.unwrap_err(); // panics with `2`let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(x.unwrap_err(), "emergency failure");unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok("this is fine".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!("{s}");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err("Oops, it failed".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!("{error}");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("late error"));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<&str, &str> = Ok("foo");\nassert_eq!(x.and(y), Err("early error"));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<&str, &str> = Err("late error");\nassert_eq!(x.and(y), Err("not a 2"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok("different result type");\nassert_eq!(x.and(y), Ok("different result type"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));\nassert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows "/" maps to "C:\\"\nlet root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("early error");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err("not a 2");\nlet y: Result<u32, &str> = Err("late error");\nassert_eq!(x.or(y), Err("late error"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err("error");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err("emergency failure");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err("emergency failure");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");Maps a Result<&mut T, E> to a Result<T, E> by copying the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet copied = x.copied();\nassert_eq!(copied, Ok(12));Maps a Result<&mut T, E> to a Result<T, E> by cloning the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet cloned = x.cloned();\nassert_eq!(cloned, Ok(12));Transposes a Result of an Option into an Option of a Result.
Ok(None) will be mapped to None.\nOk(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).
#[derive(Debug, Eq, PartialEq)]\nstruct SomeErr;\n\nlet x: Result<Option<i32>, SomeErr> = Ok(Some(5));\nlet y: Option<Result<i32, SomeErr>> = Some(Ok(5));\nassert_eq!(x.transpose(), y);result_flattening)Converts from Result<Result<T, E>, E> to Result<T, E>
#![feature(result_flattening)]\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));\nassert_eq!(Ok("hello"), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));\nassert_eq!(Err(6), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Err(6);\nassert_eq!(Err(6), x.flatten());Flattening only removes one level of nesting at a time:
\n\n#![feature(result_flattening)]\nlet x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));\nassert_eq!(Ok(Ok("hello")), x.flatten());\nassert_eq!(Ok("hello"), x.flatten().flatten());Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or("Overflow!")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or("Underflow!")\n).collect();\nassert_eq!(res, Err("Underflow!"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or("Underflow!")\n}).collect();\nassert_eq!(res, Err("Underflow!"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
Returns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err("nothing!");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);try_trait_v2)Residual type. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err("Negative element found"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moreself and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec!["5", "10", "1", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec!["5", "10", "one", "2"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());