12

std::option::Option - Rust

 3 years ago
source link: https://doc.rust-lang.org/std/option/enum.Option.html
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

impl<T> Option<T>[src][−]

pub const fn is_some(&self) -> bool1.0.0 (const: 1.48.0)[src][−]

Returns true if the option is a Some value.

Examples

let x: Option<u32> = Some(2);
assert_eq!(x.is_some(), true);

let x: Option<u32> = None;
assert_eq!(x.is_some(), false);
Run
pub const fn is_none(&self) -> bool1.0.0 (const: 1.48.0)[src][−]

Returns true if the option is a None value.

Examples

let x: Option<u32> = Some(2);
assert_eq!(x.is_none(), false);

let x: Option<u32> = None;
assert_eq!(x.is_none(), true);
Run
pub fn contains<U>(&self, x: &U) -> bool where
    U: PartialEq<T>, [src][−]
🔬 This is a nightly-only experimental API. (option_result_contains #62358)

Returns true if the option is a Some value containing the given value.

Examples

#![feature(option_result_contains)]

let x: Option<u32> = Some(2);
assert_eq!(x.contains(&2), true);

let x: Option<u32> = Some(3);
assert_eq!(x.contains(&2), false);

let x: Option<u32> = None;
assert_eq!(x.contains(&2), false);
Run

pub const fn as_ref(&self) -> Option<&T>1.0.0 (const: 1.48.0)[src][−]

Converts from &Option<T> to Option<&T>.

Examples

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.

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 `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {:?}", text);
Run

pub fn as_mut(&mut self) -> Option<&mut T>[src][−]

Converts from &mut Option<T> to Option<&mut T>.

Examples

let mut x = Some(2);
match x.as_mut() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));
Run

pub fn as_pin_ref(self: Pin<&Option<T>>) -> Option<Pin<&T>>1.33.0[src][−]

Converts from Pin<&Option<T>> to Option<Pin<&T>>.

pub fn as_pin_mut(self: Pin<&mut Option<T>>) -> Option<Pin<&mut T>>1.33.0[src][−]

Converts from Pin<&mut Option<T>> to Option<Pin<&mut T>>.

pub fn expect(self, msg: &str) -> T[src][−]

Returns the contained Some value, consuming the self value.

Panics

Panics if the value is a None with a custom panic message provided by msg.

Examples

let x = Some("value");
assert_eq!(x.expect("fruits are healthy"), "value");
Run
let x: Option<&str> = None;
x.expect("fruits are healthy"); // panics with `fruits are healthy`
Run

pub fn unwrap(self) -> T[src][−]

Returns the contained Some value, consuming the self value.

Because this function may panic, its use is generally discouraged. Instead, prefer to use pattern matching and handle the None case explicitly, or call unwrap_or, unwrap_or_else, or unwrap_or_default.

Panics

Panics if the self value equals None.

Examples

let x = Some("air");
assert_eq!(x.unwrap(), "air");
Run
let x: Option<&str> = None;
assert_eq!(x.unwrap(), "air"); // fails
Run

pub fn unwrap_or(self, default: T) -> T[src][−]

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.

Examples

assert_eq!(Some("car").unwrap_or("bike"), "car");
assert_eq!(None.unwrap_or("bike"), "bike");
Run

pub fn unwrap_or_else<F>(self, f: F) -> T where
    F: FnOnce() -> T, [src][−]

Returns the contained Some value or computes it from a closure.

Examples

let k = 10;
assert_eq!(Some(4).unwrap_or_else(|| 2 * k), 4);
assert_eq!(None.unwrap_or_else(|| 2 * k), 20);
Run

pub unsafe fn unwrap_unchecked(self) -> T[src][−]

🔬 This is a nightly-only experimental API. (option_result_unwrap_unchecked #81383)

Returns the contained Some value, consuming the self value, without checking that the value is not None.

Safety

Calling this method on None is undefined behavior.

Examples

#![feature(option_result_unwrap_unchecked)]
let x = Some("air");
assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
Run
#![feature(option_result_unwrap_unchecked)]
let x: Option<&str> = None;
assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); // Undefined behavior!
Run

pub fn map<U, F>(self, f: F) -> Option<U> where
    F: FnOnce(T) -> U, [src][−]

Maps an Option<T> to Option<U> by applying a function to a contained value.

Examples

Converts an Option<String> into an Option<usize>, consuming the original:

let maybe_some_string = Some(String::from("Hello, World!"));
// `Option::map` takes self *by value*, consuming `maybe_some_string`
let maybe_some_len = maybe_some_string.map(|s| s.len());

assert_eq!(maybe_some_len, Some(13));
Run

pub fn map_or<U, F>(self, default: U, f: F) -> U where
    F: FnOnce(T) -> U, [src][−]

Applies a function to the contained value (if any), or returns the provided default (if not).

Arguments passed to map_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use map_or_else, which is lazily evaluated.

Examples

let x = Some("foo");
assert_eq!(x.map_or(42, |v| v.len()), 3);

let x: Option<&str> = None;
assert_eq!(x.map_or(42, |v| v.len()), 42);
Run

pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U where
    F: FnOnce(T) -> U,
    D: FnOnce() -> U, [src][−]

Applies a function to the contained value (if any), or computes a default (if not).

Examples

let k = 21;

let x = Some("foo");
assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3);

let x: Option<&str> = None;
assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 42);
Run

pub fn ok_or<E>(self, err: E) -> Result<T, E>[src][−]

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.

Examples

let x = Some("foo");
assert_eq!(x.ok_or(0), Ok("foo"));

let x: Option<&str> = None;
assert_eq!(x.ok_or(0), Err(0));
Run

pub fn ok_or_else<E, F>(self, err: F) -> Result<T, E> where
    F: FnOnce() -> E, [src][−]

Transforms the Option<T> into a Result<T, E>, mapping Some(v) to Ok(v) and None to Err(err()).

Examples

let x = Some("foo");
assert_eq!(x.ok_or_else(|| 0), Ok("foo"));

let x: Option<&str> = None;
assert_eq!(x.ok_or_else(|| 0), Err(0));
Run

pub fn insert(&mut self, value: T) -> &mut Tⓘ[src][−]

🔬 This is a nightly-only experimental API. (option_insert #78271)

Inserts value into the option then returns a mutable reference to it.

If the option already contains a value, the old value is dropped.

Example

#![feature(option_insert)]

let mut opt = None;
let val = opt.insert(1);
assert_eq!(*val, 1);
assert_eq!(opt.unwrap(), 1);
let val = opt.insert(2);
assert_eq!(*val, 2);
*val = 3;
assert_eq!(opt.unwrap(), 3);
Run

pub fn iter(&self) -> Iter<'_, T>ⓘ[src][−]

Returns an iterator over the possibly contained value.

Examples

let x = Some(4);
assert_eq!(x.iter().next(), Some(&4));

let x: Option<u32> = None;
assert_eq!(x.iter().next(), None);
Run

pub fn iter_mut(&mut self) -> IterMut<'_, T>ⓘ[src][−]

Returns a mutable iterator over the possibly contained value.

Examples

let mut x = Some(4);
match x.iter_mut().next() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));

let mut x: Option<u32> = None;
assert_eq!(x.iter_mut().next(), None);
Run

pub fn and<U>(self, optb: Option<U>) -> Option<U>[src][−]

Returns None if the option is None, otherwise returns optb.

Examples

let x = Some(2);
let y: Option<&str> = None;
assert_eq!(x.and(y), None);

let x: Option<u32> = None;
let y = Some("foo");
assert_eq!(x.and(y), None);

let x = Some(2);
let y = Some("foo");
assert_eq!(x.and(y), Some("foo"));

let x: Option<u32> = None;
let y: Option<&str> = None;
assert_eq!(x.and(y), None);
Run

pub fn and_then<U, F>(self, f: F) -> Option<U> where
    F: FnOnce(T) -> Option<U>, [src][−]

Returns None if the option is None, otherwise calls f with the wrapped value and returns the result.

Some languages call this operation flatmap.

Examples

fn sq(x: u32) -> Option<u32> { Some(x * x) }
fn nope(_: u32) -> Option<u32> { None }

assert_eq!(Some(2).and_then(sq).and_then(sq), Some(16));
assert_eq!(Some(2).and_then(sq).and_then(nope), None);
assert_eq!(Some(2).and_then(nope).and_then(sq), None);
assert_eq!(None.and_then(sq).and_then(sq), None);
Run

pub fn filter<P>(self, predicate: P) -> Option<T> where
    P: FnOnce(&T) -> bool, 1.27.0[src][−]

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

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));
Run

pub fn or(self, optb: Option<T>) -> Option<T>[src][−]

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.

Examples

let x = Some(2);
let y = None;
assert_eq!(x.or(y), Some(2));

let x = None;
let y = Some(100);
assert_eq!(x.or(y), Some(100));

let x = Some(2);
let y = Some(100);
assert_eq!(x.or(y), Some(2));

let x: Option<u32> = None;
let y = None;
assert_eq!(x.or(y), None);
Run

pub fn or_else<F>(self, f: F) -> Option<T> where
    F: FnOnce() -> Option<T>, [src][−]

Returns the option if it contains a value, otherwise calls f and returns the result.

Examples

fn nobody() -> Option<&'static str> { None }
fn vikings() -> Option<&'static str> { Some("vikings") }

assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians"));
assert_eq!(None.or_else(vikings), Some("vikings"));
assert_eq!(None.or_else(nobody), None);
Run

pub fn xor(self, optb: Option<T>) -> Option<T>1.37.0[src][−]

Returns Some if exactly one of self, optb is Some, otherwise returns None.

Examples

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);
Run

pub fn get_or_insert(&mut self, value: T) -> &mut Tⓘ1.20.0[src][−]

Inserts value into the option if it is None, then returns a mutable reference to the contained value.

Examples

let mut x = None;

{
    let y: &mut u32 = x.get_or_insert(5);
    assert_eq!(y, &5);

    *y = 7;
}

assert_eq!(x, Some(7));
Run

pub fn get_or_insert_with<F>(&mut self, f: F) -> &mut Tⓘ where
    F: FnOnce() -> T, 1.20.0[src][−]

Inserts a value computed from f into the option if it is None, then returns a mutable reference to the contained value.

Examples

let mut x = None;

{
    let y: &mut u32 = x.get_or_insert_with(|| 5);
    assert_eq!(y, &5);

    *y = 7;
}

assert_eq!(x, Some(7));
Run

pub fn take(&mut self) -> Option<T>[src][−]

Takes the value out of the option, leaving a None in its place.

Examples

let mut x = Some(2);
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, Some(2));

let mut x: Option<u32> = None;
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, None);
Run

pub fn replace(&mut self, value: T) -> Option<T>1.31.0[src][−]

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.

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);
Run

pub fn zip<U>(self, other: Option<U>) -> Option<(T, U)>1.46.0[src][−]

Zips self with another Option.

If self is Some(s) and other is Some(o), this method returns Some((s, o)). Otherwise, None is returned.

Examples

let x = Some(1);
let y = Some("hi");
let z = None::<u8>;

assert_eq!(x.zip(y), Some((1, "hi")));
assert_eq!(x.zip(z), None);
Run

pub fn zip_with<U, F, R>(self, other: Option<U>, f: F) -> Option<R> where
    F: FnOnce(T, U) -> R, [src][−]

🔬 This is a nightly-only experimental API. (option_zip #70086)

Zips self and another Option with function f.

If self is Some(s) and other is Some(o), this method returns Some(f(s, o)). Otherwise, None is returned.

Examples

#![feature(option_zip)]

#[derive(Debug, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
    fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }
}

let x = Some(17.5);
let y = Some(42.7);

assert_eq!(x.zip_with(y, Point::new), Some(Point { x: 17.5, y: 42.7 }));
assert_eq!(x.zip_with(None, Point::new), None);
Run

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK