+ /// Returns the contained [`Err`] value, consuming the `self` value.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the value is an [`Ok`], with a custom panic message provided
+ /// by the [`Ok`]'s value.
+ ///
+ /// # Examples
+ ///
+ /// ```should_panic
+ /// let x: Result<u32, &str> = Ok(2);
+ /// x.unwrap_err(); // panics with `2`
+ /// ```
+ ///
+ /// ```
+ /// let x: Result<u32, &str> = Err("emergency failure");
+ /// assert_eq!(x.unwrap_err(), "emergency failure");
+ /// ```
+ #[inline]
+ #[track_caller]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ pub fn unwrap_err(self) -> E
+ where
+ T: fmt::Debug,
+ {
+ match self {
+ Ok(t) => unwrap_failed("called `Result::unwrap_err()` on an `Ok` value", &t),
+ Err(e) => e,
+ }
+ }
+
+ /// Returns the contained [`Ok`] value, but never panics.
+ ///
+ /// Unlike [`unwrap`], this method is known to never panic on the
+ /// result types it is implemented for. Therefore, it can be used
+ /// instead of `unwrap` as a maintainability safeguard that will fail
+ /// to compile if the error type of the `Result` is later changed
+ /// to an error that can actually occur.
+ ///
+ /// [`unwrap`]: Result::unwrap
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// # #![feature(never_type)]
+ /// # #![feature(unwrap_infallible)]
+ ///
+ /// fn only_good_news() -> Result<String, !> {
+ /// Ok("this is fine".into())
+ /// }
+ ///
+ /// let s: String = only_good_news().into_ok();
+ /// println!("{}", s);
+ /// ```
+ #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")]
+ #[inline]
+ pub fn into_ok(self) -> T
+ where
+ E: Into<!>,
+ {
+ match self {
+ Ok(x) => x,
+ Err(e) => e.into(),
+ }
+ }
+
+ /// Returns the contained [`Err`] value, but never panics.
+ ///
+ /// Unlike [`unwrap_err`], this method is known to never panic on the
+ /// result types it is implemented for. Therefore, it can be used
+ /// instead of `unwrap_err` as a maintainability safeguard that will fail
+ /// to compile if the ok type of the `Result` is later changed
+ /// to a type that can actually occur.
+ ///
+ /// [`unwrap_err`]: Result::unwrap_err
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// # #![feature(never_type)]
+ /// # #![feature(unwrap_infallible)]
+ ///
+ /// fn only_bad_news() -> Result<!, String> {
+ /// Err("Oops, it failed".into())
+ /// }
+ ///
+ /// let error: String = only_bad_news().into_err();
+ /// println!("{}", error);
+ /// ```
+ #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")]
+ #[inline]
+ pub fn into_err(self) -> E
+ where
+ T: Into<!>,
+ {
+ match self {
+ Ok(x) => x.into(),
+ Err(e) => e,
+ }
+ }
+
+ ////////////////////////////////////////////////////////////////////////
+ // Boolean operations on the values, eager and lazy
+ /////////////////////////////////////////////////////////////////////////
+
+ /// Returns `res` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`.
+ ///
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// let x: Result<u32, &str> = Ok(2);
+ /// let y: Result<&str, &str> = Err("late error");
+ /// assert_eq!(x.and(y), Err("late error"));
+ ///
+ /// let x: Result<u32, &str> = Err("early error");
+ /// let y: Result<&str, &str> = Ok("foo");
+ /// assert_eq!(x.and(y), Err("early error"));
+ ///
+ /// let x: Result<u32, &str> = Err("not a 2");
+ /// let y: Result<&str, &str> = Err("late error");
+ /// assert_eq!(x.and(y), Err("not a 2"));
+ ///
+ /// let x: Result<u32, &str> = Ok(2);
+ /// let y: Result<&str, &str> = Ok("different result type");
+ /// assert_eq!(x.and(y), Ok("different result type"));
+ /// ```
+ #[inline]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ pub fn and<U>(self, res: Result<U, E>) -> Result<U, E> {
+ match self {
+ Ok(_) => res,
+ Err(e) => Err(e),
+ }
+ }
+
+ /// 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.
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
+ /// fn err(x: u32) -> Result<u32, u32> { Err(x) }
+ ///
+ /// assert_eq!(Ok(2).and_then(sq).and_then(sq), Ok(16));
+ /// assert_eq!(Ok(2).and_then(sq).and_then(err), Err(4));
+ /// assert_eq!(Ok(2).and_then(err).and_then(sq), Err(2));
+ /// assert_eq!(Err(3).and_then(sq).and_then(sq), Err(3));
+ /// ```
+ #[inline]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ pub fn and_then<U, F: FnOnce(T) -> Result<U, E>>(self, op: F) -> Result<U, E> {
+ match self {
+ Ok(t) => op(t),
+ Err(e) => Err(e),
+ }
+ }
+
+ /// 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
+ /// result of a function call, it is recommended to use [`or_else`], which is
+ /// lazily evaluated.
+ ///
+ /// [`or_else`]: Result::or_else
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// let x: Result<u32, &str> = Ok(2);
+ /// let y: Result<u32, &str> = Err("late error");
+ /// assert_eq!(x.or(y), Ok(2));
+ ///
+ /// let x: Result<u32, &str> = Err("early error");
+ /// let y: Result<u32, &str> = Ok(2);
+ /// assert_eq!(x.or(y), Ok(2));
+ ///
+ /// let x: Result<u32, &str> = Err("not a 2");
+ /// let y: Result<u32, &str> = Err("late error");
+ /// assert_eq!(x.or(y), Err("late error"));
+ ///
+ /// let x: Result<u32, &str> = Ok(2);
+ /// let y: Result<u32, &str> = Ok(100);
+ /// assert_eq!(x.or(y), Ok(2));
+ /// ```
+ #[inline]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ pub fn or<F>(self, res: Result<T, F>) -> Result<T, F> {
+ match self {
+ Ok(v) => Ok(v),
+ Err(_) => res,
+ }
+ }
+
+ /// 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.
+ ///
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
+ /// fn err(x: u32) -> Result<u32, u32> { Err(x) }
+ ///
+ /// assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));
+ /// assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));
+ /// assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));
+ /// assert_eq!(Err(3).or_else(err).or_else(err), Err(3));
+ /// ```
+ #[inline]
+ #[stable(feature = "rust1", since = "1.0.0")]
+ pub fn or_else<F, O: FnOnce(E) -> Result<T, F>>(self, op: O) -> Result<T, F> {
+ match self {
+ Ok(t) => Ok(t),
+ Err(e) => op(e),
+ }
+ }
+
+ /// Returns the contained [`Ok`] value or a provided default.