Optional values. The Option type represents an optional value: every Option is either Some and contains a value, or None, and does not. Option types are very common in Cairo 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
Optional function arguments

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

fn divide(numerator: u64, denominator: u64) -> Option {
    if denominator == 0 {
        None
    } else {
        Some(numerator / denominator)
    }
}

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

// 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"),
}

The question mark operator, `?`

Similar to the Result type, when writing code that calls many functions that return the Option type, handling Some/None can be tedious. The question mark operator, ?, hides some of the boilerplate of propagating values up the call stack. It replaces this:

fn add_last_numbers(mut array: Array) -> Option {
    let a = array.pop_front();
    let b = array.pop_front();

    match (a, b) {
        (Some(x), Some(y)) => Some(x + y),
        _ => None,
    }
}

With this:

fn add_last_numbers(mut array: Array) -> Option {
    Some(array.pop_front()? + array.pop_front()?)
 }

It’s much nicer! Ending the expression with ? will result in the Some’s unwrapped value, unless the result is None, in which case None is returned early from the enclosing function. ? can be used in functions that return Option because of the early return of None that it provides.

Method overview

In addition to working with pattern matching, Option provides a wide variety of different methods.

Querying the variant

The is_some and is_none methods return true if the Option is Some or None, respectively.

Extracting the contained value

These methods extract the contained value in an Option when it is the Some variant. If the Option is None:

expect panics with a provided custom message
unwrap panics with a generic message
unwrap_or returns the provided default value
unwrap_or_default returns the default value of the type T (which must implement the Default trait)
unwrap_or_else returns the result of evaluating the provided function

Transforming contained values

These methods transform Option to Result:

ok_or transforms Some(v) to Ok(v), and None to Err(err) using the provided default err value.
ok_or_else transforms Some(v) to Ok(v), and None to a value of Err using the provided function

These methods transform the Some variant:

map transforms Option to Option by applying the provided function to the contained value of Some and leaving None values unchanged

These methods transform Option to a value of a possibly different type U:

map_or applies the provided function to the contained value of Some, or returns the provided default value if the Option is None
map_or_else applies the provided function to the contained value of Some, or returns the result of evaluating the provided fallback function if the Option is None

Boolean operators

These methods treat the Option as a boolean value, where Some acts like true and None acts like false. There are two categories of these methods: ones that take an Option as input, and ones that take a function as input (to be lazily evaluated). The and, or, and xor methods take another Option as input, and produce an Option as output. Only the and method can produce an Option value having a different inner type U than Option.

method	self	input	output
`and`	`None`	(ignored)	`None`
`and`	`Some(x)`	`None`	`None`
`and`	`Some(x)`	`Some(y)`	`Some(y)`
`or`	`None`	`None`	`None`
`or`	`None`	`Some(y)`	`Some(y)`
`or`	`Some(x)`	(ignored)	`Some(x)`
`xor`	`None`	`None`	`None`
`xor`	`None`	`Some(y)`	`Some(y)`
`xor`	`Some(x)`	`None`	`Some(x)`
`xor`	`Some(x)`	`Some(y)`	`None`

The and_then and or_else methods take a function as input, and only evaluate the function when they need to produce a new value. Only the and_then method can produce an Option value having a different inner type U than Option.

method	self	function input	function result	output
`and_then`	`None`	(not provided)	(not evaluated)	`None`
`and_then`	`Some(x)`	`x`	`None`	`None`
`and_then`	`Some(x)`	`x`	`Some(y)`	`Some(y)`
`or_else`	`None`	(not provided)	`None`	`None`
`or_else`	`None`	(not provided)	`Some(y)`	`Some(y)`
`or_else`	`Some(x)`	(not provided)	(not evaluated)	`Some(x)`

Iterating over `Option`

An Option can be iterated over. This can be helpful if you need an iterator that is conditionally empty. The iterator will either produce a single value (when the Option is Some), or produce no values (when the Option is None). For example, into_iter contains Some(v) if the Option is Some(v), and None if the Option is None.

Structs


OptionIter	An iterator over the value in the `Some` variant of an `Option` . The iterator yields one value if the `Option` is a…

Enums


Option	The `Option` enum representing either `Some(value)` or `None` .

Traits


OptionTrait	A trait for handling `Option` related operations.

Impls


DestructOption	—

Modules

Miscellaneous

Overview of core::option

The question mark operator, `?`

Method overview

Querying the variant

Extracting the contained value

Transforming contained values

Boolean operators

Iterating over `Option`

Structs

Enums

Traits

Impls

Modules

Miscellaneous

​The question mark operator, ?

​Method overview

​Querying the variant

​Extracting the contained value

​Transforming contained values

​Boolean operators

​Iterating over Option

​Structs

​Enums

​Traits

​Impls

The question mark operator, `?`

Method overview

Querying the variant

Extracting the contained value

Transforming contained values

Boolean operators

Iterating over `Option`

Structs

Enums

Traits

Impls