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
Noneis returned on error - Optional struct fields
- Optional function arguments
None case.
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:
? 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
Theis_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 anOption when it
is the Some variant. If the Option is None:
expectpanics with a provided custom messageunwrappanics with a generic messageunwrap_orreturns the provided default valueunwrap_or_defaultreturns the default value of the typeT(which must implement theDefaulttrait)unwrap_or_elsereturns the result of evaluating the provided function
Transforming contained values
These methods transformOption to Result:
ok_ortransformsSome(v)toOk(v), andNonetoErr(err)using the provided defaulterrvalue.ok_or_elsetransformsSome(v)toOk(v), andNoneto a value ofErrusing the provided function
Some variant:
maptransformsOptiontoOptionby applying the provided function to the contained value ofSomeand leavingNonevalues unchanged
Option to a value of a possibly
different type U:
map_orapplies the provided function to the contained value ofSome, or returns the provided default value if theOptionisNonemap_or_elseapplies the provided function to the contained value ofSome, or returns the result of evaluating the provided fallback function if theOptionisNone
Boolean operators
These methods treat theOption 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.
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 | — |