.. _stdlib_option:

====================================================
Monadic Option<T> — a value-or-nothing tagged pair
====================================================

.. das:module:: option

Monadic ``Option<T>`` — represents a value that may or may not be present.
Functional API for modelling "absence" in ordinary value code, where nullable
pointers are inapplicable and sentinel values (``-1``, ``""``) are fragile.

The payload may be any type, including non-copyable ones (``array<T>``,
``table<K;V>``, lambdas): constructors and combinators clone or move on the
non-copyable branch via ``static_if (typeinfo can_copy(...))``.

Construct via ``some(v)`` (clones), ``move_some(v)`` (moves out of a mutable
source), or ``none(type<T>)``; read via ``unwrap`` / ``unwrap_or`` / ``??``;
compose via ``map`` / ``and_then`` / ``filter`` / ``or_else`` through the
``|>`` pipe.

See also :ref:`tutorial_option_and_result` and ``daslib/result`` for the
``Result<T, E>`` counterpart.



++++++++++
Structures
++++++++++

.. _struct-option-Option:

.. das:attribute:: Option

struct Option


++++++++++++
Constructors
++++++++++++

  *  :ref:`move_some (var v: auto(TT)) : auto <function-option_move_some_autoTT_0x39>`
  *  :ref:`none (t: auto(TT)) : auto <function-option_none_autoTT_0x42>`
  *  :ref:`some (v: auto(TT)) : auto <function-option_some_autoTT_0x27>`

.. _function-option_move_some_autoTT_0x39:

.. das:function:: move_some(v: auto(TT)) : auto

def move_some (var v: auto(TT)) : auto

:Arguments: * **v** : auto(TT)

.. _function-option_none_autoTT_0x42:

.. das:function:: none(t: auto(TT)) : auto

def none (t: auto(TT)) : auto

:Arguments: * **t** : auto(TT)

.. _function-option_some_autoTT_0x27:

.. das:function:: some(v: auto(TT)) : auto

def some (v: auto(TT)) : auto

:Arguments: * **v** : auto(TT)


+++++++
Queries
+++++++

  *  :ref:`is_none (o: $Option(type\<auto(TT)\>)) : bool <function-option_is_none__builtin_Optiontype_ls_autoTT_gr_>`
  *  :ref:`is_some (o: $Option(type\<auto(TT)\>)) : bool <function-option_is_some__builtin_Optiontype_ls_autoTT_gr_>`

.. _function-option_is_none__builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: is_none(o: $Option(type<auto(TT)>)) : bool

def is_none (o: $Option(type<auto(TT)>)) : bool

:Arguments: * **o** : typemacro

.. _function-option_is_some__builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: is_some(o: $Option(type<auto(TT)>)) : bool

def is_some (o: $Option(type<auto(TT)>)) : bool

:Arguments: * **o** : typemacro


++++++++++++
Transforming
++++++++++++

  *  :ref:`and_then (o: $Option(type\<auto(TT)\>); f: block\<(v:TT):$Option(type\<auto(UU)\>)\>) : auto <function-option_and_then__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c__builtin_Optiontype_ls_autoUU_gr__gr_>`
  *  :ref:`filter (o: $Option(type\<auto(TT)\>); p: block\<(v:TT):bool\>) : auto <function-option_filter__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_bool_gr_>`
  *  :ref:`map (o: $Option(type\<auto(TT)\>); f: block\<(v:TT):auto(UU)\>) : auto <function-option_map__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_autoUU_gr_>`
  *  :ref:`or_else (o: $Option(type\<auto(TT)\>); f: block\<():void\>) : auto <function-option_or_else__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_>`
  *  :ref:`or_value (o: $Option(type\<auto(TT)\>); v: TT) : auto <function-option_or_value__builtin_Optiontype_ls_autoTT_gr__TT>`

.. _function-option_and_then__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c__builtin_Optiontype_ls_autoUU_gr__gr_:

.. das:function:: and_then(o: $Option(type<auto(TT)>); f: block<(v:TT):$Option(type<auto(UU)>)>) : auto

def and_then (o: $Option(type<auto(TT)>); f: block<(v:TT):$Option(type<auto(UU)>)>) : auto

:Arguments: * **o** : typemacro

            * **f** : block<(v:TT):typemacro>

.. _function-option_filter__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_bool_gr_:

.. das:function:: filter(o: $Option(type<auto(TT)>); p: block<(v:TT):bool>) : auto

def filter (o: $Option(type<auto(TT)>); p: block<(v:TT):bool>) : auto

:Arguments: * **o** : typemacro

            * **p** : block<(v:TT):bool>

.. _function-option_map__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_autoUU_gr_:

.. das:function:: map(o: $Option(type<auto(TT)>); f: block<(v:TT):auto(UU)>) : auto

def map (o: $Option(type<auto(TT)>); f: block<(v:TT):auto(UU)>) : auto

:Arguments: * **o** : typemacro

            * **f** : block<(v:TT):auto(UU)>

.. _function-option_or_else__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_:

.. das:function:: or_else(o: $Option(type<auto(TT)>); f: block<():void>) : auto

def or_else (o: $Option(type<auto(TT)>); f: block<():void>) : auto

:Arguments: * **o** : typemacro

            * **f** : block<void>

.. _function-option_or_value__builtin_Optiontype_ls_autoTT_gr__TT:

.. das:function:: or_value(o: $Option(type<auto(TT)>); v: TT) : auto

def or_value (o: $Option(type<auto(TT)>); v: TT) : auto

:Arguments: * **o** : typemacro

            * **v** : TT


++++++++++
Extraction
++++++++++

  *  :ref:`expect_value (o: $Option(type\<auto(TT)\>); msg: string) : TT <function-option_expect_value__builtin_Optiontype_ls_autoTT_gr__string>`
  *  :ref:`move_unwrap (var o: $Option(type\<auto(TT)\>)) : TT <function-option_move_unwrap__builtin_Optiontype_ls_autoTT_gr_>`
  *  :ref:`unwrap (o: $Option(type\<auto(TT)\>)) : TT <function-option_unwrap__builtin_Optiontype_ls_autoTT_gr_>`
  *  :ref:`unwrap_or (o: $Option(type\<auto(TT)\>); d: TT) : TT <function-option_unwrap_or__builtin_Optiontype_ls_autoTT_gr__TT>`
  *  :ref:`unwrap_or_default (o: $Option(type\<auto(TT)\>)) : TT <function-option_unwrap_or_default__builtin_Optiontype_ls_autoTT_gr_>`
  *  :ref:`unwrap_or_else (o: $Option(type\<auto(TT)\>); f: block\<():void\>) : TT <function-option_unwrap_or_else__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_>`

.. _function-option_expect_value__builtin_Optiontype_ls_autoTT_gr__string:

.. das:function:: expect_value(o: $Option(type<auto(TT)>); msg: string) : TT

def expect_value (o: $Option(type<auto(TT)>); msg: string) : TT

:Arguments: * **o** : typemacro

            * **msg** : string

.. _function-option_move_unwrap__builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: move_unwrap(o: $Option(type<auto(TT)>)) : TT

def move_unwrap (var o: $Option(type<auto(TT)>)) : TT

:Arguments: * **o** : typemacro

.. _function-option_unwrap__builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: unwrap(o: $Option(type<auto(TT)>)) : TT

def unwrap (o: $Option(type<auto(TT)>)) : TT

:Arguments: * **o** : typemacro

.. _function-option_unwrap_or__builtin_Optiontype_ls_autoTT_gr__TT:

.. das:function:: unwrap_or(o: $Option(type<auto(TT)>); d: TT) : TT

def unwrap_or (o: $Option(type<auto(TT)>); d: TT) : TT

:Arguments: * **o** : typemacro

            * **d** : TT

.. _function-option_unwrap_or_default__builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: unwrap_or_default(o: $Option(type<auto(TT)>)) : TT

def unwrap_or_default (o: $Option(type<auto(TT)>)) : TT

:Arguments: * **o** : typemacro

.. _function-option_unwrap_or_else__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_:

.. das:function:: unwrap_or_else(o: $Option(type<auto(TT)>); f: block<():void>) : TT

def unwrap_or_else (o: $Option(type<auto(TT)>); f: block<():void>) : TT

:Arguments: * **o** : typemacro

            * **f** : block<void>


++++++++++++
Side effects
++++++++++++

  *  :ref:`if_none (o: $Option(type\<auto(TT)\>); f: block\<():void\>) <function-option_if_none__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_>`
  *  :ref:`if_some (o: $Option(type\<auto(TT)\>); f: block\<(v:TT):void\>) <function-option_if_some__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_void_gr_>`

.. _function-option_if_none__builtin_Optiontype_ls_autoTT_gr__block_ls__c_void_gr_:

.. das:function:: if_none(o: $Option(type<auto(TT)>); f: block<():void>)

def if_none (o: $Option(type<auto(TT)>); f: block<():void>)

:Arguments: * **o** : typemacro

            * **f** : block<void>

.. _function-option_if_some__builtin_Optiontype_ls_autoTT_gr__block_ls_v_c_TT_c_void_gr_:

.. das:function:: if_some(o: $Option(type<auto(TT)>); f: block<(v:TT):void>)

def if_some (o: $Option(type<auto(TT)>); f: block<(v:TT):void>)

:Arguments: * **o** : typemacro

            * **f** : block<(v:TT):void>


+++++++
Pairing
+++++++

  *  :ref:`zip (a: $Option(type\<auto(TT)\>); b: $Option(type\<auto(UU)\>)) : auto <function-option_zip__builtin_Optiontype_ls_autoTT_gr___builtin_Optiontype_ls_autoUU_gr_>`

.. _function-option_zip__builtin_Optiontype_ls_autoTT_gr___builtin_Optiontype_ls_autoUU_gr_:

.. das:function:: zip(a: $Option(type<auto(TT)>); b: $Option(type<auto(UU)>)) : auto

def zip (a: $Option(type<auto(TT)>); b: $Option(type<auto(UU)>)) : auto

:Arguments: * **a** : typemacro

            * **b** : typemacro


+++++++++
Operators
+++++++++

  *  :ref:`$Option(type\<auto(TT)\>)\!= (o: $Option(type\<auto(TT)\>); v: TT) : bool <function-option__ex__eq___builtin_Optiontype_ls_autoTT_gr__TT>`
  *  :ref:`$Option(type\<auto(TT)\>)== (a: $Option(type\<auto(TT)\>); b: $Option(type\<auto(TT)\>)) : bool <function-option__eq__eq___builtin_Optiontype_ls_autoTT_gr___builtin_Optiontype_ls_autoTT_gr_>`
  *  :ref:`$Option(type\<auto(TT)\>)== (o: $Option(type\<auto(TT)\>); v: TT) : bool <function-option__eq__eq___builtin_Optiontype_ls_autoTT_gr__TT>`
  *  :ref:`$Option(type\<auto(TT)\>)?? (o: $Option(type\<auto(TT)\>); d: TT) : TT <function-option__q__q___builtin_Optiontype_ls_autoTT_gr__TT>`
  *  :ref:`auto(TT)\!= (v: auto(TT); o: $Option(type\<TT\>)) : bool <function-option__ex__eq__autoTT__builtin_Optiontype_ls_TT_gr__0x10a>`
  *  :ref:`auto(TT)== (v: auto(TT); o: $Option(type\<TT\>)) : bool <function-option__eq__eq__autoTT__builtin_Optiontype_ls_TT_gr__0x102>`

.. _function-option__ex__eq___builtin_Optiontype_ls_autoTT_gr__TT:

.. das:function:: $Option(type<auto(TT)>)!=(o: $Option(type<auto(TT)>); v: TT) : bool

def $Option(type<auto(TT)>)!= (o: $Option(type<auto(TT)>); v: TT) : bool

:Arguments: * **o** : typemacro

            * **v** : TT


$Option(type<auto(TT)>)==
^^^^^^^^^^^^^^^^^^^^^^^^^

.. _function-option__eq__eq___builtin_Optiontype_ls_autoTT_gr___builtin_Optiontype_ls_autoTT_gr_:

.. das:function:: $Option(type<auto(TT)>)==(a: $Option(type<auto(TT)>); b: $Option(type<auto(TT)>)) : bool

def $Option(type<auto(TT)>)== (a: $Option(type<auto(TT)>); b: $Option(type<auto(TT)>)) : bool

:Arguments: * **a** : typemacro implicit

            * **b** : typemacro implicit

.. _function-option__eq__eq___builtin_Optiontype_ls_autoTT_gr__TT:

.. das:function:: $Option(type<auto(TT)>)==(o: $Option(type<auto(TT)>); v: TT) : bool

----

.. _function-option__q__q___builtin_Optiontype_ls_autoTT_gr__TT:

.. das:function:: $Option(type<auto(TT)>)??(o: $Option(type<auto(TT)>); d: TT) : TT

def $Option(type<auto(TT)>)?? (o: $Option(type<auto(TT)>); d: TT) : TT

:Arguments: * **o** : typemacro

            * **d** : TT

.. _function-option__ex__eq__autoTT__builtin_Optiontype_ls_TT_gr__0x10a:

.. das:function:: auto(TT)!=(v: auto(TT); o: $Option(type<TT>)) : bool

def auto(TT)!= (v: auto(TT); o: $Option(type<TT>)) : bool

:Arguments: * **v** : auto(TT)

            * **o** : typemacro

.. _function-option__eq__eq__autoTT__builtin_Optiontype_ls_TT_gr__0x102:

.. das:function:: auto(TT)==(v: auto(TT); o: $Option(type<TT>)) : bool

def auto(TT)== (v: auto(TT); o: $Option(type<TT>)) : bool

:Arguments: * **v** : auto(TT)

            * **o** : typemacro