Don't use the word 'unwrap' to describe core unwrapping functions
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`.
This commit is contained in:
parent
db9b578b71
commit
8251e12950
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
|
|
|
@ -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`],
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
///
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue