Module core::option [−] [src]

Optional values

Type Option represents an optional value: every Option is either Some and contains a value, or None, and does not. Option types are very common in Rust code, as they have a number of uses:

Initial values
Return values for functions that are not defined over their entire input range (partial functions)
Return value for otherwise reporting simple errors, where None is returned on error
Optional struct fields
Struct fields that can be loaned or "taken"
Optional function arguments
Nullable pointers
Swapping things out of difficult situations

Options are commonly paired with pattern matching to query the presence of a value and take action, always accounting for the None case.

fn main() { fn divide(numerator: f64, denominator: f64) -> Option<f64> { if denominator == 0.0 { None } else { Some(numerator / denominator) } } // The return value of the function is an option let result = divide(2.0, 3.0); // Pattern match to retrieve the value match result { // The division was valid Some(x) => println!("Result: {}", x), // The division was invalid None => println!("Cannot divide by 0"), } }

fn divide(numerator: f64, denominator: f64) -> Option<f64> {
    if denominator == 0.0 {
        None
    } else {
        Some(numerator / denominator)
    }
}

// The return value of the function is an option
let result = divide(2.0, 3.0);

// Pattern match to retrieve the value
match result {
    // The division was valid
    Some(x) => println!("Result: {}", x),
    // The division was invalid
    None    => println!("Cannot divide by 0"),
}

Options and pointers ("nullable" pointers)

Rust's pointer types must always point to a valid location; there are no "null" pointers. Instead, Rust has optional pointers, like the optional owned box, Option<Box<T>>.

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(...)) or not (None).

fn main() { let optional: Option<Box<i32>> = None; check_optional(&optional); let optional: Option<Box<i32>> = Some(Box::new(9000)); check_optional(&optional); fn check_optional(optional: &Option<Box<i32>>) { match *optional { Some(ref p) => println!("have value {}", p), None => println!("have no value"), } } }

let optional: Option<Box<i32>> = None;
check_optional(&optional);

let optional: Option<Box<i32>> = Some(Box::new(9000));
check_optional(&optional);

fn check_optional(optional: &Option<Box<i32>>) {
    match *optional {
        Some(ref p) => println!("have value {}", p),
        None => println!("have no value"),
    }
}

This usage of Option to create safe nullable pointers is so common that Rust does special optimizations to make the representation of Option<Box<T>> a single pointer. Optional pointers in Rust are stored as efficiently as any other pointer type.

Examples

Basic pattern matching on Option:

fn main() { let msg = Some("howdy"); // Take a reference to the contained string match msg { Some(ref m) => println!("{}", *m), None => (), } // Remove the contained string, destroying the Option let unwrapped_msg = match msg { Some(m) => m, None => "default message", }; }

let msg = Some("howdy");

// Take a reference to the contained string
match msg {
    Some(ref m) => println!("{}", *m),
    None => (),
}

// Remove the contained string, destroying the Option
let unwrapped_msg = match msg {
    Some(m) => m,
    None => "default message",
};

Initialize a result to None before a loop:

fn main() { enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) } // A list of data to search through. let all_the_big_things = [ Kingdom::Plant(250, "redwood"), Kingdom::Plant(230, "noble fir"), Kingdom::Plant(229, "sugar pine"), Kingdom::Animal(25, "blue whale"), Kingdom::Animal(19, "fin whale"), Kingdom::Animal(15, "north pacific right whale"), ]; // We're going to search for the name of the biggest animal, // but to start with we've just got `None`. let mut name_of_biggest_animal = None; let mut size_of_biggest_animal = 0; for big_thing in &all_the_big_things { match *big_thing { Kingdom::Animal(size, name) if size > size_of_biggest_animal => { // Now we've found the name of some big animal size_of_biggest_animal = size; name_of_biggest_animal = Some(name); } Kingdom::Animal(..) | Kingdom::Plant(..) => () } } match name_of_biggest_animal { Some(name) => println!("the biggest animal is {}", name), None => println!("there are no animals :("), } }

enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) }

// A list of data to search through.
let all_the_big_things = [
    Kingdom::Plant(250, "redwood"),
    Kingdom::Plant(230, "noble fir"),
    Kingdom::Plant(229, "sugar pine"),
    Kingdom::Animal(25, "blue whale"),
    Kingdom::Animal(19, "fin whale"),
    Kingdom::Animal(15, "north pacific right whale"),
];

// We're going to search for the name of the biggest animal,
// but to start with we've just got `None`.
let mut name_of_biggest_animal = None;
let mut size_of_biggest_animal = 0;
for big_thing in &all_the_big_things {
    match *big_thing {
        Kingdom::Animal(size, name) if size > size_of_biggest_animal => {
            // Now we've found the name of some big animal
            size_of_biggest_animal = size;
            name_of_biggest_animal = Some(name);
        }
        Kingdom::Animal(..) | Kingdom::Plant(..) => ()
    }
}

match name_of_biggest_animal {
    Some(name) => println!("the biggest animal is {}", name),
    None => println!("there are no animals :("),
}

Reexports

use self::Option::*;

use clone::Clone;

use cmp::{Eq, Ord};

use default::Default;

use iter::ExactSizeIterator;

use iter::{Iterator, DoubleEndedIterator, FromIterator, IntoIterator};

use mem;

use ops::FnOnce;

use result::Result::{Ok, Err};

use result::Result;

Structs

IntoIter	An iterator over the item contained inside an Option.
Item
Iter	An iterator over a reference of the contained item in an Option.
IterMut	An iterator over a mutable reference of the contained item in an Option.

Enums

Option

The Option type. See the module level documentation for more.

Functions

expect_failed