Skip to main content

/

Docs

Nightly
v24.5
Log in

Mojo struct

Optional

A type modeling a value which may or may not be present.

Optional values can be thought of as a type-safe nullable pattern. Your value can take on a value or None, and you need to check and explicitly extract the value to get it out.

Currently T is required to be a CollectionElement so we can implement copy/move for Optional and allow it to be used in collections itself.

from collections import Optional
var a = Optional(1)
var b = Optional[Int](None)
if a:
    print(a.value())  # prints 1
if b:  # bool(b) is False, so no print
    print(b.value())
var c = a.or_else(2)
var d = b.or_else(2)
print(c)  # prints 1
print(d)  # prints 2
from collections import Optional
var a = Optional(1)
var b = Optional[Int](None)
if a:
    print(a.value())  # prints 1
if b:  # bool(b) is False, so no print
    print(b.value())
var c = a.or_else(2)
var d = b.or_else(2)
print(c)  # prints 1
print(d)  # prints 2

Parameters​

  • ​T (CollectionElement): The type of value stored in the Optional.

Implemented traits​

AnyType, Boolable, CollectionElement, CollectionElementNew, Copyable, ExplicitlyCopyable, Movable

Methods​

__init__​

__init__(out self)

Construct an empty Optional.

__init__(out self, owned value: T)

Construct an Optional containing a value.

Args:

  • ​value (T): The value to store in the optional.

__init__(out self, value: NoneType)

Construct an empty Optional.

Args:

  • ​value (NoneType): Must be exactly None.

__init__(out self, *, other: Self)

Copy construct an Optional.

Args:

  • ​other (Self): The Optional to copy.

__bool__​

__bool__(self) -> Bool

Return true if the Optional has a value.

Returns:

True if the optional has a value and False otherwise.

__invert__​

__invert__(self) -> Bool

Return False if the optional has a value.

Returns:

False if the optional has a value and True otherwise.

__eq__​

__eq__(self, rhs: NoneType) -> Bool

Return True if a value is not present.

Args:

  • ​rhs (NoneType): The None value to compare to.

Returns:

True if a value is not present, False otherwise.

__eq__[T: EqualityComparableCollectionElement](self: Optional[T], rhs: Optional[T]) -> Bool

Return True if this is the same as another optional value, meaning both are absent, or both are present and have the same underlying value.

Parameters:

  • ​T (EqualityComparableCollectionElement): The type of the elements in the list. Must implement the traits CollectionElement and EqualityComparable.

Args:

  • ​rhs (Optional[T]): The value to compare to.

Returns:

True if the values are the same.

__ne__​

__ne__(self, rhs: NoneType) -> Bool

Return True if a value is present.

Args:

  • ​rhs (NoneType): The None value to compare to.

Returns:

False if a value is not present, True otherwise.

__ne__[T: EqualityComparableCollectionElement](self: Optional[T], rhs: Optional[T]) -> Bool

Return False if this is the same as another optional value, meaning both are absent, or both are present and have the same underlying value.

Parameters:

  • ​T (EqualityComparableCollectionElement): The type of the elements in the list. Must implement the traits CollectionElement and EqualityComparable.

Args:

  • ​rhs (Optional[T]): The value to compare to.

Returns:

False if the values are the same.

__is__​

__is__(self, other: NoneType) -> Bool

Return True if the Optional has no value.

It allows you to use the following syntax: if my_optional is None:

Args:

  • ​other (NoneType): The value to compare to (None).

Returns:

True if the Optional has no value and False otherwise.

__isnot__​

__isnot__(self, other: NoneType) -> Bool

Return True if the Optional has a value.

It allows you to use the following syntax: if my_optional is not None:.

Args:

  • ​other (NoneType): The value to compare to (None).

Returns:

True if the Optional has a value and False otherwise.

__str__​

__str__[U: RepresentableCollectionElement, //](self: Optional[U]) -> String

Return the string representation of the value of the Optional.

Parameters:

  • ​U (RepresentableCollectionElement): The type of the elements in the list. Must implement the traits Representable and CollectionElement.

Returns:

A string representation of the Optional.

__repr__​

__repr__[U: RepresentableCollectionElement, //](self: Optional[U]) -> String

Returns the verbose string representation of the Optional.

Parameters:

  • ​U (RepresentableCollectionElement): The type of the elements in the list. Must implement the traits Representable and CollectionElement.

Returns:

A verbose string representation of the Optional.

write_to​

write_to[W: Writer, U: RepresentableCollectionElement, //](self: Optional[U], inout writer: W)

Write Optional string representation to a Writer.

Parameters:

  • ​W (Writer): A type conforming to the Writable trait.
  • ​U (RepresentableCollectionElement): The type of the elements in the list. Must implement the traits Representable and CollectionElement.

Args:

  • ​writer (W): The object to write to.

value​

value(ref self) -> ref [$1._value] T

Retrieve a reference to the value of the Optional.

This check to see if the optional contains a value. If you call this without first verifying the optional with bool() eg. by if my_option: or without otherwise knowing that it contains a value (for instance with or_else), the program will abort

Returns:

A reference to the contained data of the option as a Pointer[T].

unsafe_value​

unsafe_value(ref self) -> ref [$1._value] T

Unsafely retrieve a reference to the value of the Optional.

This doesn't check to see if the optional contains a value. If you call this without first verifying the optional with bool() eg. by if my_option: or without otherwise knowing that it contains a value (for instance with or_else), you'll get garbage unsafe data out.

Returns:

A reference to the contained data of the option as a Pointer[T].

take​

take(inout self) -> T

Move the value out of the Optional.

The caller takes ownership over the new value, which is moved out of the Optional, and the Optional is left in an empty state.

This check to see if the optional contains a value. If you call this without first verifying the optional with bool() eg. by if my_option: or without otherwise knowing that it contains a value (for instance with or_else), you'll get garbage unsafe data out.

Returns:

The contained data of the option as an owned T value.

unsafe_take​

unsafe_take(inout self) -> T

Unsafely move the value out of the Optional.

The caller takes ownership over the new value, which is moved out of the Optional, and the Optional is left in an empty state.

This check to see if the optional contains a value. If you call this without first verifying the optional with bool() eg. by if my_option: or without otherwise knowing that it contains a value (for instance with or_else), the program will abort!

Returns:

The contained data of the option as an owned T value.

or_else​

or_else(self, default: T) -> T

Return the underlying value contained in the Optional or a default value if the Optional's underlying value is not present.

Args:

  • ​default (T): The new value to use if no value was present.

Returns:

The underlying value contained in the Optional or a default value.