Skip to content

Commit

Permalink
Don't use the word 'unwrap' to describe core unwrapping functions
Browse files Browse the repository at this point in the history 
It's tautological, and Rust-specific Jargon.

This changes various Option/Result methods to consistently describe unwrapping
behavior using the words "return", "contain", "consume".

It also renames the closure argument of `Return::unwrap_or_else` to `default` to
be consistent with `Option`.
  • Loading branch information
@brson
brson committed Feb 7, 2020
1 parent db9b578 commit 8251e12
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 26 deletions.
26 changes: 16 additions & 10 deletions src/libcore/option.rs
View file
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
38 changes: 22 additions & 16 deletions src/libcore/result.rs
View file
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,7 @@ 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
///
Expand Down Expand Up @@ -959,7 +956,16 @@ 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.
///
/// 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 @@ -994,7 +1000,7 @@ impl<T, E: fmt::Debug> Result<T, 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 @@ -1022,7 +1028,7 @@ 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 @@ -1056,7 +1062,7 @@ impl<T: fmt::Debug, E> Result<T, 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

0 comments on commit 8251e12

Please sign in to comment.