-// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
-// file at the top-level directory of this distribution and at
-// http://rust-lang.org/COPYRIGHT.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
-
//! Optional values.
//!
//! Type [`Option`] represents an optional value: every [`Option`]
//! The following example uses [`Option`] to create an optional box of
//! [`i32`]. Notice that in order to use the inner [`i32`] value first, the
//! `check_optional` function needs to use pattern matching to
-//! determine whether the box has a value (i.e. it is [`Some(...)`][`Some`]) or
+//! determine whether the box has a value (i.e., it is [`Some(...)`][`Some`]) or
//! not ([`None`]).
//!
//! ```
-//! let optional: Option<Box<i32>> = None;
-//! check_optional(&optional);
+//! let optional = None;
+//! check_optional(optional);
//!
-//! let optional: Option<Box<i32>> = Some(Box::new(9000));
-//! check_optional(&optional);
+//! let optional = Some(Box::new(9000));
+//! check_optional(optional);
//!
-//! fn check_optional(optional: &Option<Box<i32>>) {
-//! match *optional {
+//! fn check_optional(optional: Option<Box<i32>>) {
+//! match optional {
//! Some(ref p) => println!("has value {}", p),
//! None => println!("has no value"),
//! }
#![stable(feature = "rust1", since = "1.0.0")]
use iter::{FromIterator, FusedIterator, TrustedLen};
-use mem;
+use {hint, mem, ops::{self, Deref}};
+use pin::Pin;
// Note that this is not a lang item per se, but it has a hidden dependency on
// `Iterator`, which is one. The compiler assumes that the `next` method of
// Querying the contained values
/////////////////////////////////////////////////////////////////////////
- /// Returns `true` if the option is a `Some` value.
+ /// Returns `true` if the option is a [`Some`] value.
///
/// # Examples
///
/// let x: Option<u32> = None;
/// assert_eq!(x.is_some(), false);
/// ```
+ ///
+ /// [`Some`]: #variant.Some
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_some(&self) -> bool {
}
}
- /// Returns `true` if the option is a `None` value.
+ /// Returns `true` if the option is a [`None`] value.
///
/// # Examples
///
/// let x: Option<u32> = None;
/// assert_eq!(x.is_none(), true);
/// ```
+ ///
+ /// [`None`]: #variant.None
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_none(&self) -> bool {
///
/// # Examples
///
- /// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
+ /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, preserving the original.
/// The [`map`] method takes the `self` argument by value, consuming the original,
/// so this technique uses `as_ref` to first take an `Option` to a reference
/// to the value inside the original.
///
/// [`map`]: enum.Option.html#method.map
+ /// [`String`]: ../../std/string/struct.String.html
+ /// [`usize`]: ../../std/primitive.usize.html
///
/// ```
- /// let num_as_str: Option<String> = Some("10".to_string());
+ /// let text: Option<String> = Some("Hello, world!".to_string());
/// // First, cast `Option<String>` to `Option<&String>` with `as_ref`,
- /// // then consume *that* with `map`, leaving `num_as_str` on the stack.
- /// let num_as_int: Option<usize> = num_as_str.as_ref().map(|n| n.len());
- /// println!("still can print num_as_str: {:?}", num_as_str);
+ /// // then consume *that* with `map`, leaving `text` on the stack.
+ /// let text_length: Option<usize> = text.as_ref().map(|s| s.len());
+ /// println!("still can print text: {:?}", text);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
}
}
+
+ /// Converts from `Pin<&Option<T>>` to `Option<Pin<&T>>`
+ #[inline]
+ #[stable(feature = "pin", since = "1.33.0")]
+ pub fn as_pin_ref<'a>(self: Pin<&'a Option<T>>) -> Option<Pin<&'a T>> {
+ unsafe {
+ Pin::get_ref(self).as_ref().map(|x| Pin::new_unchecked(x))
+ }
+ }
+
+ /// Converts from `Pin<&mut Option<T>>` to `Option<Pin<&mut T>>`
+ #[inline]
+ #[stable(feature = "pin", since = "1.33.0")]
+ pub fn as_pin_mut<'a>(self: Pin<&'a mut Option<T>>) -> Option<Pin<&'a mut T>> {
+ unsafe {
+ Pin::get_unchecked_mut(self).as_mut().map(|x| Pin::new_unchecked(x))
+ }
+ }
+
/////////////////////////////////////////////////////////////////////////
// Getting to contained values
/////////////////////////////////////////////////////////////////////////
- /// Unwraps an option, yielding the content of a `Some`.
+ /// Unwraps an option, yielding the content of a [`Some`].
///
/// # Panics
///
- /// Panics if the value is a `None` with a custom panic message provided by
+ /// Panics if the value is a [`None`] with a custom panic message provided by
/// `msg`.
///
+ /// [`Some`]: #variant.Some
+ /// [`None`]: #variant.None
+ ///
/// # Examples
///
/// ```
}
}
- /// Moves the value `v` out of the `Option<T>` if it is `Some(v)`.
+ /// Moves the value `v` out of the `Option<T>` if it is [`Some(v)`].
///
/// In general, because this function may panic, its use is discouraged.
- /// Instead, prefer to use pattern matching and handle the `None`
+ /// Instead, prefer to use pattern matching and handle the [`None`]
/// case explicitly.
///
/// # Panics
///
- /// Panics if the self value equals `None`.
+ /// Panics if the self value equals [`None`].
+ ///
+ /// [`Some(v)`]: #variant.Some
+ /// [`None`]: #variant.None
///
/// # Examples
///
/// Returns the contained value or a 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.
+ ///
+ /// [`unwrap_or_else`]: #method.unwrap_or_else
+ ///
/// # Examples
///
/// ```
///
/// # Examples
///
- /// Convert an `Option<String>` into an `Option<usize>`, consuming the original:
+ /// Converts an `Option<`[`String`]`>` into an `Option<`[`usize`]`>`, consuming the original:
+ ///
+ /// [`String`]: ../../std/string/struct.String.html
+ /// [`usize`]: ../../std/primitive.usize.html
///
/// ```
/// let maybe_some_string = Some(String::from("Hello, World!"));
}
/// Applies a function to the contained value (if any),
- /// or returns a `default` (if not).
+ /// or returns the provided default (if not).
///
/// # Examples
///
}
/// Applies a function to the contained value (if any),
- /// or computes a `default` (if not).
+ /// or computes a default (if not).
///
/// # Examples
///
}
}
- /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
- /// [`Ok(v)`] and `None` to [`Err(err)`][Err].
+ /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping [`Some(v)`] to
+ /// [`Ok(v)`] and [`None`] to [`Err(err)`].
+ ///
+ /// Arguments passed to `ok_or` are eagerly evaluated; if you are passing the
+ /// result of a function call, it is recommended to use [`ok_or_else`], which is
+ /// lazily evaluated.
///
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
/// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
- /// [Err]: ../../std/result/enum.Result.html#variant.Err
+ /// [`Err(err)`]: ../../std/result/enum.Result.html#variant.Err
+ /// [`None`]: #variant.None
+ /// [`Some(v)`]: #variant.Some
+ /// [`ok_or_else`]: #method.ok_or_else
///
/// # Examples
///
}
}
- /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
- /// [`Ok(v)`] and `None` to [`Err(err())`][Err].
+ /// Transforms the `Option<T>` into a [`Result<T, E>`], mapping [`Some(v)`] to
+ /// [`Ok(v)`] and [`None`] to [`Err(err())`].
///
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
/// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
- /// [Err]: ../../std/result/enum.Result.html#variant.Err
+ /// [`Err(err())`]: ../../std/result/enum.Result.html#variant.Err
+ /// [`None`]: #variant.None
+ /// [`Some(v)`]: #variant.Some
///
/// # Examples
///
// Boolean operations on the values, eager and lazy
/////////////////////////////////////////////////////////////////////////
- /// Returns `None` if the option is `None`, otherwise returns `optb`.
+ /// Returns [`None`] if the option is [`None`], otherwise returns `optb`.
+ ///
+ /// [`None`]: #variant.None
///
/// # Examples
///
}
}
- /// Returns `None` if the option is `None`, otherwise calls `f` with the
+ /// Returns [`None`] if the option is [`None`], otherwise calls `f` with the
/// wrapped value and returns the result.
///
/// Some languages call this operation flatmap.
///
+ /// [`None`]: #variant.None
+ ///
/// # Examples
///
/// ```
}
}
+ /// Returns `None` if the option is `None`, otherwise calls `predicate`
+ /// with the wrapped value and returns:
+ ///
+ /// - `Some(t)` if `predicate` returns `true` (where `t` is the wrapped
+ /// value), and
+ /// - `None` if `predicate` returns `false`.
+ ///
+ /// This function works similar to `Iterator::filter()`. You can imagine
+ /// the `Option<T>` being an iterator over one or zero elements. `filter()`
+ /// lets you decide which elements to keep.
+ ///
+ /// # Examples
+ ///
+ /// ```rust
+ /// fn is_even(n: &i32) -> bool {
+ /// n % 2 == 0
+ /// }
+ ///
+ /// assert_eq!(None.filter(is_even), None);
+ /// assert_eq!(Some(3).filter(is_even), None);
+ /// assert_eq!(Some(4).filter(is_even), Some(4));
+ /// ```
+ #[inline]
+ #[stable(feature = "option_filter", since = "1.27.0")]
+ pub fn filter<P: FnOnce(&T) -> bool>(self, predicate: P) -> Self {
+ if let Some(x) = self {
+ if predicate(&x) {
+ return Some(x)
+ }
+ }
+ None
+ }
+
/// Returns the option if it contains a value, otherwise returns `optb`.
///
+ /// 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`]: #method.or_else
+ ///
/// # Examples
///
/// ```
}
}
+ /// Returns [`Some`] if exactly one of `self`, `optb` is [`Some`], otherwise returns `None`.
+ ///
+ /// [`Some`]: #variant.Some
+ /// [`None`]: #variant.None
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #![feature(option_xor)]
+ ///
+ /// let x = Some(2);
+ /// let y: Option<u32> = None;
+ /// assert_eq!(x.xor(y), Some(2));
+ ///
+ /// let x: Option<u32> = None;
+ /// let y = Some(2);
+ /// assert_eq!(x.xor(y), Some(2));
+ ///
+ /// let x = Some(2);
+ /// let y = Some(2);
+ /// assert_eq!(x.xor(y), None);
+ ///
+ /// let x: Option<u32> = None;
+ /// let y: Option<u32> = None;
+ /// assert_eq!(x.xor(y), None);
+ /// ```
+ #[inline]
+ #[unstable(feature = "option_xor", issue = "50512")]
+ pub fn xor(self, optb: Option<T>) -> Option<T> {
+ match (self, optb) {
+ (Some(a), None) => Some(a),
+ (None, Some(b)) => Some(b),
+ _ => None,
+ }
+ }
+
/////////////////////////////////////////////////////////////////////////
// Entry-like operations to insert if None and return a reference
/////////////////////////////////////////////////////////////////////////
- /// Inserts `v` into the option if it is `None`, then
+ /// Inserts `v` into the option if it is [`None`], then
/// returns a mutable reference to the contained value.
///
+ /// [`None`]: #variant.None
+ ///
/// # Examples
///
/// ```
- /// #![feature(option_entry)]
- ///
/// let mut x = None;
///
/// {
/// assert_eq!(x, Some(7));
/// ```
#[inline]
- #[unstable(feature = "option_entry", issue = "39288")]
+ #[stable(feature = "option_entry", since = "1.20.0")]
pub fn get_or_insert(&mut self, v: T) -> &mut T {
match *self {
None => *self = Some(v),
match *self {
Some(ref mut v) => v,
- _ => unreachable!(),
+ None => unsafe { hint::unreachable_unchecked() },
}
}
- /// Inserts a value computed from `f` into the option if it is `None`, then
+ /// Inserts a value computed from `f` into the option if it is [`None`], then
/// returns a mutable reference to the contained value.
///
+ /// [`None`]: #variant.None
+ ///
/// # Examples
///
/// ```
- /// #![feature(option_entry)]
- ///
/// let mut x = None;
///
/// {
/// assert_eq!(x, Some(7));
/// ```
#[inline]
- #[unstable(feature = "option_entry", issue = "39288")]
+ #[stable(feature = "option_entry", since = "1.20.0")]
pub fn get_or_insert_with<F: FnOnce() -> T>(&mut self, f: F) -> &mut T {
match *self {
None => *self = Some(f()),
match *self {
Some(ref mut v) => v,
- _ => unreachable!(),
+ None => unsafe { hint::unreachable_unchecked() },
}
}
// Misc
/////////////////////////////////////////////////////////////////////////
- /// Takes the value out of the option, leaving a `None` in its place.
+ /// Takes the value out of the option, leaving a [`None`] in its place.
+ ///
+ /// [`None`]: #variant.None
///
/// # Examples
///
/// ```
/// let mut x = Some(2);
- /// x.take();
+ /// let y = x.take();
/// assert_eq!(x, None);
+ /// assert_eq!(y, Some(2));
///
/// let mut x: Option<u32> = None;
- /// x.take();
+ /// let y = x.take();
/// assert_eq!(x, None);
+ /// assert_eq!(y, None);
/// ```
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn take(&mut self) -> Option<T> {
mem::replace(self, None)
}
+
+ /// Replaces the actual value in the option by the value given in parameter,
+ /// returning the old value if present,
+ /// leaving a [`Some`] in its place without deinitializing either one.
+ ///
+ /// [`Some`]: #variant.Some
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let mut x = Some(2);
+ /// let old = x.replace(5);
+ /// assert_eq!(x, Some(5));
+ /// assert_eq!(old, Some(2));
+ ///
+ /// let mut x = None;
+ /// let old = x.replace(3);
+ /// assert_eq!(x, Some(3));
+ /// assert_eq!(old, None);
+ /// ```
+ #[inline]
+ #[stable(feature = "option_replace", since = "1.31.0")]
+ pub fn replace(&mut self, value: T) -> Option<T> {
+ mem::replace(self, Some(value))
+ }
+}
+
+impl<T: Copy> Option<&T> {
+ /// Maps an `Option<&T>` to an `Option<T>` by copying the contents of the
+ /// option.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #![feature(copied)]
+ ///
+ /// let x = 12;
+ /// let opt_x = Some(&x);
+ /// assert_eq!(opt_x, Some(&12));
+ /// let copied = opt_x.copied();
+ /// assert_eq!(copied, Some(12));
+ /// ```
+ #[unstable(feature = "copied", issue = "57126")]
+ pub fn copied(self) -> Option<T> {
+ self.map(|&t| t)
+ }
}
-impl<'a, T: Clone> Option<&'a T> {
+impl<T: Copy> Option<&mut T> {
+ /// Maps an `Option<&mut T>` to an `Option<T>` by copying the contents of the
+ /// option.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #![feature(copied)]
+ ///
+ /// let mut x = 12;
+ /// let opt_x = Some(&mut x);
+ /// assert_eq!(opt_x, Some(&mut 12));
+ /// let copied = opt_x.copied();
+ /// assert_eq!(copied, Some(12));
+ /// ```
+ #[unstable(feature = "copied", issue = "57126")]
+ pub fn copied(self) -> Option<T> {
+ self.map(|&mut t| t)
+ }
+}
+
+impl<T: Clone> Option<&T> {
/// Maps an `Option<&T>` to an `Option<T>` by cloning the contents of the
/// option.
///
}
}
+impl<T: Clone> Option<&mut T> {
+ /// Maps an `Option<&mut T>` to an `Option<T>` by cloning the contents of the
+ /// option.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// let mut x = 12;
+ /// let opt_x = Some(&mut x);
+ /// assert_eq!(opt_x, Some(&mut 12));
+ /// let cloned = opt_x.cloned();
+ /// assert_eq!(cloned, Some(12));
+ /// ```
+ #[stable(since = "1.26.0", feature = "option_ref_mut_cloned")]
+ pub fn cloned(self) -> Option<T> {
+ self.map(|t| t.clone())
+ }
+}
+
impl<T: Default> Option<T> {
/// Returns the contained value or a default
///
- /// Consumes the `self` argument then, if `Some`, returns the contained
- /// value, otherwise if `None`, returns the default value for that
+ /// Consumes the `self` argument then, if [`Some`], returns the contained
+ /// value, otherwise if [`None`], returns the [default value] for that
/// type.
///
/// # Examples
///
- /// Convert a string to an integer, turning poorly-formed strings
- /// into 0 (the default value for integers). `parse` converts
- /// a string to any other type that implements `FromStr`, returning
- /// `None` on error.
+ /// Converts a string to an integer, turning poorly-formed strings
+ /// into 0 (the default value for integers). [`parse`] converts
+ /// a string to any other type that implements [`FromStr`], returning
+ /// [`None`] on error.
///
/// ```
/// let good_year_from_input = "1909";
/// assert_eq!(1909, good_year);
/// assert_eq!(0, bad_year);
/// ```
+ ///
+ /// [`Some`]: #variant.Some
+ /// [`None`]: #variant.None
+ /// [default value]: ../default/trait.Default.html#tymethod.default
+ /// [`parse`]: ../../std/primitive.str.html#method.parse
+ /// [`FromStr`]: ../../std/str/trait.FromStr.html
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn unwrap_or_default(self) -> T {
}
}
+#[unstable(feature = "inner_deref", reason = "newly added", issue = "50264")]
+impl<T: Deref> Option<T> {
+ /// Converts from `&Option<T>` to `Option<&T::Target>`.
+ ///
+ /// Leaves the original Option in-place, creating a new one with a reference
+ /// to the original one, additionally coercing the contents via `Deref`.
+ pub fn deref(&self) -> Option<&T::Target> {
+ self.as_ref().map(|t| t.deref())
+ }
+}
+
+impl<T, E> Option<Result<T, E>> {
+ /// Transposes an `Option` of a `Result` into a `Result` of an `Option`.
+ ///
+ /// `None` will be mapped to `Ok(None)`.
+ /// `Some(Ok(_))` and `Some(Err(_))` will be mapped to `Ok(Some(_))` and `Err(_)`.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// #[derive(Debug, Eq, PartialEq)]
+ /// struct SomeErr;
+ ///
+ /// let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
+ /// let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
+ /// assert_eq!(x, y.transpose());
+ /// ```
+ #[inline]
+ #[stable(feature = "transpose_result", since = "1.33.0")]
+ pub fn transpose(self) -> Result<Option<T>, E> {
+ match self {
+ Some(Ok(x)) => Ok(Some(x)),
+ Some(Err(e)) => Err(e),
+ None => Ok(None),
+ }
+ }
+}
+
// This is a separate function to reduce the code size of .expect() itself.
#[inline(never)]
#[cold]
panic!("{}", msg)
}
-
/////////////////////////////////////////////////////////////////////////////
// Trait implementations
/////////////////////////////////////////////////////////////////////////////
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> Default for Option<T> {
- /// Returns None.
+ /// Returns [`None`][Option::None].
#[inline]
fn default() -> Option<T> { None }
}
type Item = &'a mut T;
type IntoIter = IterMut<'a, T>;
- fn into_iter(mut self) -> IterMut<'a, T> {
+ fn into_iter(self) -> IterMut<'a, T> {
self.iter_mut()
}
}
}
}
+#[stable(feature = "option_ref_from_ref_option", since = "1.30.0")]
+impl<'a, T> From<&'a Option<T>> for Option<&'a T> {
+ fn from(o: &'a Option<T>) -> Option<&'a T> {
+ o.as_ref()
+ }
+}
+
+#[stable(feature = "option_ref_from_ref_option", since = "1.30.0")]
+impl<'a, T> From<&'a mut Option<T>> for Option<&'a mut T> {
+ fn from(o: &'a mut Option<T>) -> Option<&'a mut T> {
+ o.as_mut()
+ }
+}
+
/////////////////////////////////////////////////////////////////////////////
// The Option Iterators
/////////////////////////////////////////////////////////////////////////////
impl<A> FusedIterator for Item<A> {}
unsafe impl<A> TrustedLen for Item<A> {}
-/// An iterator over a reference of the contained item in an [`Option`].
+/// An iterator over a reference to the [`Some`] variant of an [`Option`].
+///
+/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none.
+///
+/// This `struct` is created by the [`Option::iter`] function.
///
/// [`Option`]: enum.Option.html
+/// [`Some`]: enum.Option.html#variant.Some
+/// [`Option::iter`]: enum.Option.html#method.iter
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Iter<'a, A: 'a> { inner: Item<&'a A> }
}
#[stable(feature = "rust1", since = "1.0.0")]
-impl<'a, A> ExactSizeIterator for Iter<'a, A> {}
+impl<A> ExactSizeIterator for Iter<'_, A> {}
-#[unstable(feature = "fused", issue = "35602")]
-impl<'a, A> FusedIterator for Iter<'a, A> {}
+#[stable(feature = "fused", since = "1.26.0")]
+impl<A> FusedIterator for Iter<'_, A> {}
#[unstable(feature = "trusted_len", issue = "37572")]
-unsafe impl<'a, A> TrustedLen for Iter<'a, A> {}
+unsafe impl<A> TrustedLen for Iter<'_, A> {}
#[stable(feature = "rust1", since = "1.0.0")]
-impl<'a, A> Clone for Iter<'a, A> {
- fn clone(&self) -> Iter<'a, A> {
+impl<A> Clone for Iter<'_, A> {
+ #[inline]
+ fn clone(&self) -> Self {
Iter { inner: self.inner.clone() }
}
}
-/// An iterator over a mutable reference of the contained item in an [`Option`].
+/// An iterator over a mutable reference to the [`Some`] variant of an [`Option`].
+///
+/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none.
+///
+/// This `struct` is created by the [`Option::iter_mut`] function.
///
/// [`Option`]: enum.Option.html
+/// [`Some`]: enum.Option.html#variant.Some
+/// [`Option::iter_mut`]: enum.Option.html#method.iter_mut
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct IterMut<'a, A: 'a> { inner: Item<&'a mut A> }
}
#[stable(feature = "rust1", since = "1.0.0")]
-impl<'a, A> ExactSizeIterator for IterMut<'a, A> {}
+impl<A> ExactSizeIterator for IterMut<'_, A> {}
-#[unstable(feature = "fused", issue = "35602")]
-impl<'a, A> FusedIterator for IterMut<'a, A> {}
+#[stable(feature = "fused", since = "1.26.0")]
+impl<A> FusedIterator for IterMut<'_, A> {}
#[unstable(feature = "trusted_len", issue = "37572")]
-unsafe impl<'a, A> TrustedLen for IterMut<'a, A> {}
+unsafe impl<A> TrustedLen for IterMut<'_, A> {}
-/// An iterator over the item contained inside an [`Option`].
+/// An iterator over the value in [`Some`] variant of an [`Option`].
+///
+/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none.
+///
+/// This `struct` is created by the [`Option::into_iter`] function.
///
/// [`Option`]: enum.Option.html
+/// [`Some`]: enum.Option.html#variant.Some
+/// [`Option::into_iter`]: enum.Option.html#method.into_iter
#[derive(Clone, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct IntoIter<A> { inner: Item<A> }
#[stable(feature = "rust1", since = "1.0.0")]
impl<A> ExactSizeIterator for IntoIter<A> {}
-#[unstable(feature = "fused", issue = "35602")]
+#[stable(feature = "fused", since = "1.26.0")]
impl<A> FusedIterator for IntoIter<A> {}
#[unstable(feature = "trusted_len", issue = "37572")]
#[stable(feature = "rust1", since = "1.0.0")]
impl<A, V: FromIterator<A>> FromIterator<Option<A>> for Option<V> {
- /// Takes each element in the `Iterator`: if it is `None`, no further
- /// elements are taken, and the `None` is returned. Should no `None` occur, a
- /// container with the values of each `Option` is returned.
+ /// Takes each element in the [`Iterator`]: if it is [`None`][Option::None],
+ /// no further elements are taken, and the [`None`][Option::None] is
+ /// returned. Should no [`None`][Option::None] occur, a container with the
+ /// values of each [`Option`] is returned.
+ ///
+ /// # Examples
+ ///
+ /// Here is an example which increments every integer in a vector.
+ /// `We use the checked variant of `add` that returns `None` when the
+ /// calculation would result in an overflow.
+ ///
+ /// ```
+ /// let items = vec![0_u16, 1, 2];
+ ///
+ /// let res: Option<Vec<u16>> = items
+ /// .iter()
+ /// .map(|x| x.checked_add(1))
+ /// .collect();
+ ///
+ /// assert_eq!(res, Some(vec![1, 2, 3]));
+ /// ```
///
- /// Here is an example which increments every integer in a vector,
- /// checking for overflow:
+ /// As you can see, this will return the expected, valid items.
+ ///
+ /// Here is another example that tries to subtract one from another list
+ /// of integers, this time checking for underflow:
///
/// ```
- /// use std::u16;
+ /// let items = vec![2_u16, 1, 0];
+ ///
+ /// let res: Option<Vec<u16>> = items
+ /// .iter()
+ /// .map(|x| x.checked_sub(1))
+ /// .collect();
///
- /// let v = vec![1, 2];
- /// let res: Option<Vec<u16>> = v.iter().map(|&x: &u16|
- /// if x == u16::MAX { None }
- /// else { Some(x + 1) }
- /// ).collect();
- /// assert!(res == Some(vec![2, 3]));
+ /// assert_eq!(res, None);
/// ```
+ ///
+ /// Since the last element is zero, it would underflow. Thus, the resulting
+ /// value is `None`.
+ ///
+ /// [`Iterator`]: ../iter/trait.Iterator.html
#[inline]
fn from_iter<I: IntoIterator<Item=Option<A>>>(iter: I) -> Option<V> {
// FIXME(#11084): This could be replaced with Iterator::scan when this
None => None,
}
}
+
+ #[inline]
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ if self.found_none {
+ (0, Some(0))
+ } else {
+ let (_, upper) = self.iter.size_hint();
+ (0, upper)
+ }
+ }
}
let mut adapter = Adapter { iter: iter.into_iter(), found_none: false };
}
}
}
+
+/// The error type that results from applying the try operator (`?`) to a `None` value. If you wish
+/// to allow `x?` (where `x` is an `Option<T>`) to be converted into your error type, you can
+/// implement `impl From<NoneError>` for `YourErrorType`. In that case, `x?` within a function that
+/// returns `Result<_, YourErrorType>` will translate a `None` value into an `Err` result.
+#[unstable(feature = "try_trait", issue = "42327")]
+#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
+pub struct NoneError;
+
+#[unstable(feature = "try_trait", issue = "42327")]
+impl<T> ops::Try for Option<T> {
+ type Ok = T;
+ type Error = NoneError;
+
+ #[inline]
+ fn into_result(self) -> Result<T, NoneError> {
+ self.ok_or(NoneError)
+ }
+
+ #[inline]
+ fn from_ok(v: T) -> Self {
+ Some(v)
+ }
+
+ #[inline]
+ fn from_error(_: NoneError) -> Self {
+ None
+ }
+}
projects / rustc.git / blobdiff