Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Don't use the word "unwrap" to describe "unwrap" methods #68918

Merged
merged 3 commits into from
Feb 9, 2020
Merged

Don't use the word "unwrap" to describe "unwrap" methods #68918

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c00d8aa
Reorder declarations of Result::export/unwrap to match Option
brson Feb 5, 2020
db9b578
Reorder declarations of Result::expect_err/unwrap_err to match Option
brson Feb 5, 2020
8251e12
Don't use the word 'unwrap' to describe core unwrapping functions
brson Feb 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions src/libcore/option.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@ impl<T> Option<T> {
// Getting to contained values
/////////////////////////////////////////////////////////////////////////

/// Unwraps an option, yielding the content of a [`Some`].
/// Returns the contained [`Some`] value, consuming the `self` value.
///
/// # Panics
///
Expand Down Expand Up @@ -348,17 +348,22 @@ impl<T> Option<T> {
}
}

/// Moves the value `v` out of the `Option<T>` if it is [`Some(v)`].
/// Returns the contained [`Some`] value, consuming the `self` value.
///
/// In general, because this function may panic, its use is discouraged.
/// Because this function may panic, its use is generally discouraged.
/// Instead, prefer to use pattern matching and handle the [`None`]
/// case explicitly.
/// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or
/// [`unwrap_or_default`].
///
/// [`unwrap_or`]: #method.unwrap_or
/// [`unwrap_or_else`]: #method.unwrap_or_else
/// [`unwrap_or_default`]: #method.unwrap_or_default
///
/// # Panics
///
/// Panics if the self value equals [`None`].
///
/// [`Some(v)`]: #variant.Some
/// [`Some`]: #variant.Some
/// [`None`]: #variant.None
///
/// # Examples
Expand All @@ -382,12 +387,13 @@ impl<T> Option<T> {
}
}

/// Returns the contained value or a default.
/// Returns the contained [`Some`] value or a provided default.
///
/// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing
/// the result of a function call, it is recommended to use [`unwrap_or_else`],
/// which is lazily evaluated.
///
/// [`Some`]: #variant.Some
/// [`unwrap_or_else`]: #method.unwrap_or_else
///
/// # Examples
Expand All @@ -405,7 +411,7 @@ impl<T> Option<T> {
}
}

/// Returns the contained value or computes it from a closure.
/// Returns the contained [`Some`] value or computes it from a closure.
///
/// # Examples
///
Expand Down Expand Up @@ -980,7 +986,7 @@ impl<T: Clone> Option<&mut T> {
}

impl<T: fmt::Debug> Option<T> {
/// Unwraps an option, expecting [`None`] and returning nothing.
/// Consumes `self` while expecting [`None`] and returning nothing.
///
/// # Panics
///
Expand Down Expand Up @@ -1023,7 +1029,7 @@ impl<T: fmt::Debug> Option<T> {
}
}

/// Unwraps an option, expecting [`None`] and returning nothing.
/// Consumes `self` while expecting [`None`] and returning nothing.
///
/// # Panics
///
Expand Down Expand Up @@ -1068,7 +1074,7 @@ impl<T: fmt::Debug> Option<T> {
}

impl<T: Default> Option<T> {
/// Returns the contained value or a default
/// Returns the contained [`Some`] value or a default
///
/// Consumes the `self` argument then, if [`Some`], returns the contained
/// value, otherwise if [`None`], returns the [default value] for that
Expand Down
112 changes: 59 additions & 53 deletions src/libcore/result.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -792,8 +792,7 @@ impl<T, E> Result<T, E> {
}
}

/// Unwraps a result, yielding the content of an [`Ok`].
/// Else, it returns `optb`.
/// Returns the contained [`Ok`] value or a provided default.
///
/// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing
/// the result of a function call, it is recommended to use [`unwrap_or_else`],
Expand All @@ -808,27 +807,25 @@ impl<T, E> Result<T, E> {
/// Basic usage:
///
/// ```
/// let optb = 2;
/// let default = 2;
/// let x: Result<u32, &str> = Ok(9);
/// assert_eq!(x.unwrap_or(optb), 9);
/// assert_eq!(x.unwrap_or(default), 9);
///
/// let x: Result<u32, &str> = Err("error");
/// assert_eq!(x.unwrap_or(optb), optb);
/// assert_eq!(x.unwrap_or(default), default);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn unwrap_or(self, optb: T) -> T {
pub fn unwrap_or(self, default: T) -> T {
match self {
Ok(t) => t,
Err(_) => optb,
Err(_) => default,
}
}

/// Unwraps a result, yielding the content of an [`Ok`].
/// If the value is an [`Err`] then it calls `op` with its value.
/// Returns the contained [`Ok`] value or computes it from a closure.
///
/// [`Ok`]: enum.Result.html#variant.Ok
/// [`Err`]: enum.Result.html#variant.Err
///
/// # Examples
///
Expand Down Expand Up @@ -931,7 +928,44 @@ impl<T: Clone, E> Result<&mut T, E> {
}

impl<T, E: fmt::Debug> Result<T, E> {
/// Unwraps a result, yielding the content of an [`Ok`].
/// Returns the contained [`Ok`] value, consuming the `self` value.
///
/// # Panics
///
/// Panics if the value is an [`Err`], with a panic message including the
/// passed message, and the content of the [`Err`].
///
/// [`Ok`]: enum.Result.html#variant.Ok
/// [`Err`]: enum.Result.html#variant.Err
///
/// # Examples
///
/// Basic usage:
///
/// ```{.should_panic}
/// let x: Result<u32, &str> = Err("emergency failure");
/// x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
/// ```
#[inline]
#[track_caller]
#[stable(feature = "result_expect", since = "1.4.0")]
pub fn expect(self, msg: &str) -> T {
match self {
Ok(t) => t,
Err(e) => unwrap_failed(msg, &e),
}
}

/// Returns the contained [`Ok`] value, consuming the `self` value.
///
/// Because this function may panic, its use is generally discouraged.
/// Instead, prefer to use pattern matching and handle the [`Err`]
/// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or
/// [`unwrap_or_default`].
///
/// [`unwrap_or`]: #method.unwrap_or
/// [`unwrap_or_else`]: #method.unwrap_or_else
/// [`unwrap_or_default`]: #method.unwrap_or_default
///
/// # Panics
///
Expand Down Expand Up @@ -963,13 +997,15 @@ impl<T, E: fmt::Debug> Result<T, E> {
Err(e) => unwrap_failed("called `Result::unwrap()` on an `Err` value", &e),
}
}
}

/// Unwraps a result, yielding the content of an [`Ok`].
impl<T: fmt::Debug, E> Result<T, E> {
/// Returns the contained [`Err`] value, consuming the `self` value.
///
/// # Panics
///
/// Panics if the value is an [`Err`], with a panic message including the
/// passed message, and the content of the [`Err`].
/// Panics if the value is an [`Ok`], with a panic message including the
/// passed message, and the content of the [`Ok`].
///
/// [`Ok`]: enum.Result.html#variant.Ok
/// [`Err`]: enum.Result.html#variant.Err
Expand All @@ -979,22 +1015,20 @@ impl<T, E: fmt::Debug> Result<T, E> {
/// Basic usage:
///
/// ```{.should_panic}
/// let x: Result<u32, &str> = Err("emergency failure");
/// x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
/// let x: Result<u32, &str> = Ok(10);
/// x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
/// ```
#[inline]
#[track_caller]
#[stable(feature = "result_expect", since = "1.4.0")]
pub fn expect(self, msg: &str) -> T {
#[stable(feature = "result_expect_err", since = "1.17.0")]
pub fn expect_err(self, msg: &str) -> E {
match self {
Ok(t) => t,
Err(e) => unwrap_failed(msg, &e),
Ok(t) => unwrap_failed(msg, &t),
Err(e) => e,
}
}
}

impl<T: fmt::Debug, E> Result<T, E> {
/// Unwraps a result, yielding the content of an [`Err`].
/// Returns the contained [`Err`] value, consuming the `self` value.
///
/// # Panics
///
Expand Down Expand Up @@ -1025,38 +1059,10 @@ impl<T: fmt::Debug, E> Result<T, E> {
Err(e) => e,
}
}

/// Unwraps a result, yielding the content of an [`Err`].
///
/// # Panics
///
/// Panics if the value is an [`Ok`], with a panic message including the
/// passed message, and the content of the [`Ok`].
///
/// [`Ok`]: enum.Result.html#variant.Ok
/// [`Err`]: enum.Result.html#variant.Err
///
/// # Examples
///
/// Basic usage:
///
/// ```{.should_panic}
/// let x: Result<u32, &str> = Ok(10);
/// x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10`
/// ```
#[inline]
#[track_caller]
#[stable(feature = "result_expect_err", since = "1.17.0")]
pub fn expect_err(self, msg: &str) -> E {
match self {
Ok(t) => unwrap_failed(msg, &t),
Err(e) => e,
}
}
}

impl<T: Default, E> Result<T, E> {
/// Returns the contained value or a default
/// Returns the contained [`Ok`] value or a default
///
/// Consumes the `self` argument then, if [`Ok`], returns the contained
/// value, otherwise if [`Err`], returns the default value for that
Expand Down Expand Up @@ -1095,7 +1101,7 @@ impl<T: Default, E> Result<T, E> {

#[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")]
impl<T, E: Into<!>> Result<T, E> {
/// Unwraps a result that can never be an [`Err`], yielding the content of the [`Ok`].
/// 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
Expand Down