Skip to main content

Module 0x1::option

This module defines the Option type and its methods to represent and handle an optional value.

use 0x1::vector;

Struct Option​

Abstraction of a value that may or may not be present. Implemented with a vector of size zero or one because Move bytecode does not have ADTs.

struct Option<Element> has copy, drop, store
Fields
vec: vector<Element>

Constants​

The Option is in an invalid state for the operation attempted. The Option is Some while it should be None.

const EOPTION_IS_SET: u64 = 262144;

The Option is in an invalid state for the operation attempted. The Option is None while it should be Some.

const EOPTION_NOT_SET: u64 = 262145;

Function none​

Return an empty Option

public fun none<Element>(): option::Option<Element>
Implementation
public fun none<Element>(): Option<Element> {
    Option { vec: vector::empty() }
}

Function some​

Return an Option containing e

public fun some<Element>(e: Element): option::Option<Element>
Implementation
public fun some<Element>(e: Element): Option<Element> {
    Option { vec: vector::singleton(e) }
}

Function is_none​

Return true if t does not hold a value

public fun is_none<Element>(t: &option::Option<Element>): bool
Implementation
public fun is_none<Element>(t: &Option<Element>): bool {
    t.vec.is_empty()
}

Function is_some​

Return true if t holds a value

public fun is_some<Element>(t: &option::Option<Element>): bool
Implementation
public fun is_some<Element>(t: &Option<Element>): bool {
    !t.vec.is_empty()
}

Function contains​

Return true if the value in t is equal to e_ref Always returns false if t does not hold a value

public fun contains<Element>(t: &option::Option<Element>, e_ref: &Element): bool
Implementation
public fun contains<Element>(t: &Option<Element>, e_ref: &Element): bool {
    t.vec.contains(e_ref)
}

Function borrow​

Return an immutable reference to the value inside t Aborts if t does not hold a value

public fun borrow<Element>(t: &option::Option<Element>): &Element
Implementation
public fun borrow<Element>(t: &Option<Element>): &Element {
    assert!(t.is_some(), EOPTION_NOT_SET);
    &t.vec[0]
}

Function borrow_with_default​

Return a reference to the value inside t if it holds one Return default_ref if t does not hold a value

public fun borrow_with_default<Element>(t: &option::Option<Element>, default_ref: &Element): &Element
Implementation
public fun borrow_with_default<Element>(t: &Option<Element>, default_ref: &Element): &Element {
    let vec_ref = &t.vec;
    if (vec_ref.is_empty()) default_ref
    else &vec_ref[0]
}

Function get_with_default​

Return the value inside t if it holds one Return default if t does not hold a value

public fun get_with_default<Element: copy, drop>(t: &option::Option<Element>, default: Element): Element
Implementation
public fun get_with_default<Element: copy + drop>(
    t: &Option<Element>,
    default: Element,
): Element {
    let vec_ref = &t.vec;
    if (vec_ref.is_empty()) default
    else vec_ref[0]
}

Function fill​

Convert the none option t to a some option by adding e. Aborts if t already holds a value

public fun fill<Element>(t: &mut option::Option<Element>, e: Element)
Implementation
public fun fill<Element>(t: &mut Option<Element>, e: Element) {
    let vec_ref = &mut t.vec;
    if (vec_ref.is_empty()) vec_ref.push_back(e)
    else abort EOPTION_IS_SET
}

Function extract​

Convert a some option to a none by removing and returning the value stored inside t Aborts if t does not hold a value

public fun extract<Element>(t: &mut option::Option<Element>): Element
Implementation
public fun extract<Element>(t: &mut Option<Element>): Element {
    assert!(t.is_some(), EOPTION_NOT_SET);
    t.vec.pop_back()
}

Function borrow_mut​

Return a mutable reference to the value inside t Aborts if t does not hold a value

public fun borrow_mut<Element>(t: &mut option::Option<Element>): &mut Element
Implementation
public fun borrow_mut<Element>(t: &mut Option<Element>): &mut Element {
    assert!(t.is_some(), EOPTION_NOT_SET);
    &mut t.vec[0]
}

Function swap​

Swap the old value inside t with e and return the old value Aborts if t does not hold a value

public fun swap<Element>(t: &mut option::Option<Element>, e: Element): Element
Implementation
public fun swap<Element>(t: &mut Option<Element>, e: Element): Element {
    assert!(t.is_some(), EOPTION_NOT_SET);
    let vec_ref = &mut t.vec;
    let old_value = vec_ref.pop_back();
    vec_ref.push_back(e);
    old_value
}

Function swap_or_fill​

Swap the old value inside t with e and return the old value; or if there is no old value, fill it with e. Different from swap(), swap_or_fill() allows for t not holding a value.

public fun swap_or_fill<Element>(t: &mut option::Option<Element>, e: Element): option::Option<Element>
Implementation
public fun swap_or_fill<Element>(t: &mut Option<Element>, e: Element): Option<Element> {
    let vec_ref = &mut t.vec;
    let old_value = if (vec_ref.is_empty()) none()
        else some(vec_ref.pop_back());
    vec_ref.push_back(e);
    old_value
}

Function destroy_with_default​

Destroys t. If t holds a value, return it. Returns default otherwise

public fun destroy_with_default<Element: drop>(t: option::Option<Element>, default: Element): Element
Implementation
public fun destroy_with_default<Element: drop>(t: Option<Element>, default: Element): Element {
    let Option { mut vec } = t;
    if (vec.is_empty()) default
    else vec.pop_back()
}

Function destroy_some​

Unpack t and return its contents Aborts if t does not hold a value

public fun destroy_some<Element>(t: option::Option<Element>): Element
Implementation
public fun destroy_some<Element>(t: Option<Element>): Element {
    assert!(t.is_some(), EOPTION_NOT_SET);
    let Option { mut vec } = t;
    let elem = vec.pop_back();
    vec.destroy_empty();
    elem
}

Function destroy_none​

Unpack t Aborts if t holds a value

public fun destroy_none<Element>(t: option::Option<Element>)
Implementation
public fun destroy_none<Element>(t: Option<Element>) {
    assert!(t.is_none(), EOPTION_IS_SET);
    let Option { vec } = t;
    vec.destroy_empty()
}

Function to_vec​

Convert t into a vector of length 1 if it is Some, and an empty vector otherwise

public fun to_vec<Element>(t: option::Option<Element>): vector<Element>
Implementation
public fun to_vec<Element>(t: Option<Element>): vector<Element> {
    let Option { vec } = t;
    vec
}