Documentation Index
Fetch the complete documentation index at: https://docs.starknet.io/llms.txt
Use this file to discover all available pages before exploring further.
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,
}
}
fn add_last_numbers(mut array: Array) -> Option {
Some(array.pop_front()? + array.pop_front()?)
}
? 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.
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 messageunwrap panics with a generic messageunwrap_or returns the provided default valueunwrap_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
These methods transform Option to Result:
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
Nonemap_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 |
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.
| |
|---|
| OptionIter | An iterator over the value in the Some variant of an Option . The iterator yields one value if the Option is a… |
| |
|---|
| Option | The Option enum representing either Some(value) or None . |
| |
|---|
| OptionTrait | A trait for handling Option related operations. |
