.. _stdlib_result:

=====================================================
Monadic Result<T, E> — a value-or-error tagged pair
=====================================================

.. das:module:: result

Monadic ``Result<T, E>`` — a value (``ok``) or an error (``err``).
Functional API for modelling fallible computations where an error carries
meaning (unlike a bare ``Option<T>`` that only says "missing").

Both the value side ``T`` and the error side ``E`` may be non-copyable
(``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 ``ok(v, type<E>)`` / ``err(e, type<T>)`` (clone), or
``move_ok(v, type<E>)`` / ``move_err(e, type<T>)`` to move out of a mutable
source; compose via ``map`` / ``map_err`` / ``and_then`` / ``or_else``;
extract via ``unwrap`` / ``unwrap_or`` / ``??``. Bridge to ``Option<T>`` via
``to_option`` / ``err_to_option``.

See also :ref:`tutorial_option_and_result` and ``daslib/option`` for the
``Option<T>`` counterpart.



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

.. _struct-result-Result:

.. das:attribute:: Result

struct Result


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

  *  :ref:`err (e: auto(EE); ttype: auto(TT)) : auto <function-result_err_autoEE_autoTT_0x4e>`
  *  :ref:`move_err (var e: auto(EE); ttype: auto(TT)) : auto <function-result_move_err_autoEE_autoTT_0x5f>`
  *  :ref:`move_ok (var v: auto(TT); etype: auto(EE)) : auto <function-result_move_ok_autoTT_autoEE_0x42>`
  *  :ref:`ok (v: auto(TT); etype: auto(EE)) : auto <function-result_ok_autoTT_autoEE_0x31>`

.. _function-result_err_autoEE_autoTT_0x4e:

.. das:function:: err(e: auto(EE); ttype: auto(TT)) : auto

def err (e: auto(EE); ttype: auto(TT)) : auto

:Arguments: * **e** : auto(EE)

            * **ttype** : auto(TT)

.. _function-result_move_err_autoEE_autoTT_0x5f:

.. das:function:: move_err(e: auto(EE); ttype: auto(TT)) : auto

def move_err (var e: auto(EE); ttype: auto(TT)) : auto

:Arguments: * **e** : auto(EE)

            * **ttype** : auto(TT)

.. _function-result_move_ok_autoTT_autoEE_0x42:

.. das:function:: move_ok(v: auto(TT); etype: auto(EE)) : auto

def move_ok (var v: auto(TT); etype: auto(EE)) : auto

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

            * **etype** : auto(EE)

.. _function-result_ok_autoTT_autoEE_0x31:

.. das:function:: ok(v: auto(TT); etype: auto(EE)) : auto

def ok (v: auto(TT); etype: auto(EE)) : auto

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

            * **etype** : auto(EE)


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

  *  :ref:`is_err (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : bool <function-result_is_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`is_ok (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : bool <function-result_is_ok__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`

.. _function-result_is_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: is_err(r: $Result(type<auto(TT)>,type<auto(EE)>)) : bool

def is_err (r: $Result(type<auto(TT)>,type<auto(EE)>)) : bool

:Arguments: * **r** : typemacro

.. _function-result_is_ok__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: is_ok(r: $Result(type<auto(TT)>,type<auto(EE)>)) : bool

def is_ok (r: $Result(type<auto(TT)>,type<auto(EE)>)) : bool

:Arguments: * **r** : typemacro


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

  *  :ref:`and_then (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(v:TT):$Result(type\<auto(UU)\>,type\<EE\>)\>) : auto <function-result_and_then__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c__builtin_Resulttype_ls_autoUU_gr_,type_ls_EE_gr__gr_>`
  *  :ref:`map (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(v:TT):auto(UU)\>) : auto <function-result_map__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c_autoUU_gr_>`
  *  :ref:`map_err (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(e:EE):auto(FF)\>) : auto <function-result_map_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_autoFF_gr_>`
  *  :ref:`or_else (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(e:EE):$Result(type\<TT\>,type\<auto(FF)\>)\>) : auto <function-result_or_else__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c__builtin_Resulttype_ls_TT_gr_,type_ls_autoFF_gr__gr_>`

.. _function-result_and_then__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c__builtin_Resulttype_ls_autoUU_gr_,type_ls_EE_gr__gr_:

.. das:function:: and_then(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):$Result(type<auto(UU)>,type<EE>)>) : auto

def and_then (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):$Result(type<auto(UU)>,type<EE>)>) : auto

:Arguments: * **r** : typemacro

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

.. _function-result_map__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c_autoUU_gr_:

.. das:function:: map(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):auto(UU)>) : auto

def map (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):auto(UU)>) : auto

:Arguments: * **r** : typemacro

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

.. _function-result_map_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_autoFF_gr_:

.. das:function:: map_err(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):auto(FF)>) : auto

def map_err (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):auto(FF)>) : auto

:Arguments: * **r** : typemacro

            * **f** : block<(e:EE):auto(FF)>

.. _function-result_or_else__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c__builtin_Resulttype_ls_TT_gr_,type_ls_autoFF_gr__gr_:

.. das:function:: or_else(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):$Result(type<TT>,type<auto(FF)>)>) : auto

def or_else (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):$Result(type<TT>,type<auto(FF)>)>) : auto

:Arguments: * **r** : typemacro

            * **f** : block<(e:EE):typemacro>


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

  *  :ref:`expect_err (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); msg: string) : EE <function-result_expect_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__string>`
  *  :ref:`expect_value (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); msg: string) : TT <function-result_expect_value__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__string>`
  *  :ref:`move_unwrap (var r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : TT <function-result_move_unwrap__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`move_unwrap_err (var r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : EE <function-result_move_unwrap_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`unwrap (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : TT <function-result_unwrap__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`unwrap_err (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : EE <function-result_unwrap_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`unwrap_or (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); d: TT) : TT <function-result_unwrap_or__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT>`
  *  :ref:`unwrap_or_default (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : TT <function-result_unwrap_or_default__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`unwrap_or_else (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(e:EE):TT\>) : TT <function-result_unwrap_or_else__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_TT_gr_>`

.. _function-result_expect_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__string:

.. das:function:: expect_err(r: $Result(type<auto(TT)>,type<auto(EE)>); msg: string) : EE

def expect_err (r: $Result(type<auto(TT)>,type<auto(EE)>); msg: string) : EE

:Arguments: * **r** : typemacro

            * **msg** : string

.. _function-result_expect_value__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__string:

.. das:function:: expect_value(r: $Result(type<auto(TT)>,type<auto(EE)>); msg: string) : TT

def expect_value (r: $Result(type<auto(TT)>,type<auto(EE)>); msg: string) : TT

:Arguments: * **r** : typemacro

            * **msg** : string

.. _function-result_move_unwrap__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: move_unwrap(r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

def move_unwrap (var r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

:Arguments: * **r** : typemacro

.. _function-result_move_unwrap_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: move_unwrap_err(r: $Result(type<auto(TT)>,type<auto(EE)>)) : EE

def move_unwrap_err (var r: $Result(type<auto(TT)>,type<auto(EE)>)) : EE

:Arguments: * **r** : typemacro

.. _function-result_unwrap__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: unwrap(r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

def unwrap (r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

:Arguments: * **r** : typemacro

.. _function-result_unwrap_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: unwrap_err(r: $Result(type<auto(TT)>,type<auto(EE)>)) : EE

def unwrap_err (r: $Result(type<auto(TT)>,type<auto(EE)>)) : EE

:Arguments: * **r** : typemacro

.. _function-result_unwrap_or__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT:

.. das:function:: unwrap_or(r: $Result(type<auto(TT)>,type<auto(EE)>); d: TT) : TT

def unwrap_or (r: $Result(type<auto(TT)>,type<auto(EE)>); d: TT) : TT

:Arguments: * **r** : typemacro

            * **d** : TT

.. _function-result_unwrap_or_default__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: unwrap_or_default(r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

def unwrap_or_default (r: $Result(type<auto(TT)>,type<auto(EE)>)) : TT

:Arguments: * **r** : typemacro

.. _function-result_unwrap_or_else__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_TT_gr_:

.. das:function:: unwrap_or_else(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):TT>) : TT

def unwrap_or_else (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):TT>) : TT

:Arguments: * **r** : typemacro

            * **f** : block<(e:EE):TT>


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

  *  :ref:`if_err (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(e:EE):void\>) <function-result_if_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_void_gr_>`
  *  :ref:`if_ok (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); f: block\<(v:TT):void\>) <function-result_if_ok__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c_void_gr_>`

.. _function-result_if_err__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_e_c_EE_c_void_gr_:

.. das:function:: if_err(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):void>)

def if_err (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(e:EE):void>)

:Arguments: * **r** : typemacro

            * **f** : block<(e:EE):void>

.. _function-result_if_ok__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__block_ls_v_c_TT_c_void_gr_:

.. das:function:: if_ok(r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):void>)

def if_ok (r: $Result(type<auto(TT)>,type<auto(EE)>); f: block<(v:TT):void>)

:Arguments: * **r** : typemacro

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


+++++++++++++++++
Bridges to Option
+++++++++++++++++

  *  :ref:`err_to_option (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : auto <function-result_err_to_option__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`to_option (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : auto <function-result_to_option__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`

.. _function-result_err_to_option__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: err_to_option(r: $Result(type<auto(TT)>,type<auto(EE)>)) : auto

def err_to_option (r: $Result(type<auto(TT)>,type<auto(EE)>)) : auto

:Arguments: * **r** : typemacro

.. _function-result_to_option__builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

.. das:function:: to_option(r: $Result(type<auto(TT)>,type<auto(EE)>)) : auto

def to_option (r: $Result(type<auto(TT)>,type<auto(EE)>)) : auto

:Arguments: * **r** : typemacro


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

  *  :ref:`$Result(type\<auto(TT)\>,type\<auto(EE)\>)\!= (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); v: TT) : bool <function-result__ex__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT>`
  *  :ref:`$Result(type\<auto(TT)\>,type\<auto(EE)\>)== (a: $Result(type\<auto(TT)\>,type\<auto(EE)\>); b: $Result(type\<auto(TT)\>,type\<auto(EE)\>)) : bool <function-result__eq__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_>`
  *  :ref:`$Result(type\<auto(TT)\>,type\<auto(EE)\>)== (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); v: TT) : bool <function-result__eq__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT>`
  *  :ref:`$Result(type\<auto(TT)\>,type\<auto(EE)\>)?? (r: $Result(type\<auto(TT)\>,type\<auto(EE)\>); d: TT) : TT <function-result__q__q___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT>`
  *  :ref:`auto(TT)\!= (v: auto(TT); r: $Result(type\<TT\>,type\<auto(EE)\>)) : bool <function-result__ex__eq__autoTT__builtin_Resulttype_ls_TT_gr_,type_ls_autoEE_gr__0x15f>`
  *  :ref:`auto(TT)== (v: auto(TT); r: $Result(type\<TT\>,type\<auto(EE)\>)) : bool <function-result__eq__eq__autoTT__builtin_Resulttype_ls_TT_gr_,type_ls_autoEE_gr__0x157>`

.. _function-result__ex__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT:

.. das:function:: $Result(type<auto(TT)>,type<auto(EE)>)!=(r: $Result(type<auto(TT)>,type<auto(EE)>); v: TT) : bool

def $Result(type<auto(TT)>,type<auto(EE)>)!= (r: $Result(type<auto(TT)>,type<auto(EE)>); v: TT) : bool

:Arguments: * **r** : typemacro

            * **v** : TT


$Result(type<auto(TT)>,type<auto(EE)>)==
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _function-result__eq__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr_:

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

def $Result(type<auto(TT)>,type<auto(EE)>)== (a: $Result(type<auto(TT)>,type<auto(EE)>); b: $Result(type<auto(TT)>,type<auto(EE)>)) : bool

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

            * **b** : typemacro implicit

.. _function-result__eq__eq___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT:

.. das:function:: $Result(type<auto(TT)>,type<auto(EE)>)==(r: $Result(type<auto(TT)>,type<auto(EE)>); v: TT) : bool

----

.. _function-result__q__q___builtin_Resulttype_ls_autoTT_gr_,type_ls_autoEE_gr__TT:

.. das:function:: $Result(type<auto(TT)>,type<auto(EE)>)??(r: $Result(type<auto(TT)>,type<auto(EE)>); d: TT) : TT

def $Result(type<auto(TT)>,type<auto(EE)>)?? (r: $Result(type<auto(TT)>,type<auto(EE)>); d: TT) : TT

:Arguments: * **r** : typemacro

            * **d** : TT

.. _function-result__ex__eq__autoTT__builtin_Resulttype_ls_TT_gr_,type_ls_autoEE_gr__0x15f:

.. das:function:: auto(TT)!=(v: auto(TT); r: $Result(type<TT>,type<auto(EE)>)) : bool

def auto(TT)!= (v: auto(TT); r: $Result(type<TT>,type<auto(EE)>)) : bool

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

            * **r** : typemacro

.. _function-result__eq__eq__autoTT__builtin_Resulttype_ls_TT_gr_,type_ls_autoEE_gr__0x157:

.. das:function:: auto(TT)==(v: auto(TT); r: $Result(type<TT>,type<auto(EE)>)) : bool

def auto(TT)== (v: auto(TT); r: $Result(type<TT>,type<auto(EE)>)) : bool

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

            * **r** : typemacro