# Module `Rresult.R`

Result value combinators.

## Results

`type ('a, 'b) t = ('a, 'b) result`

The type for results.

`val ok : 'a -> ('a, 'b) result`

`ok v` is `Ok v`.

`val error : 'b -> ('a, 'b) result`

`error e` is `Error e`.

`val reword_error : ('b -> 'c) -> ('a, 'b) result -> ('a, 'c) result`

`reword_error reword r` is:

• `r` if `r = Ok v`
• `Error (reword e)` if `r = Error e`
`val get_ok : ('a, 'b) result -> 'a`

`get_ok r` is `v` if `r = Ok v` and raises `Invalid_argument` otherwise.

`val get_error : ('a, 'b) result -> 'b`

`get_error r` is `e` if `r = Error e` and raises `Invalid_argument` otherwise.

## Composing results

`val bind : ('a, 'b) result -> ('a -> ('c, 'b) result) -> ('c, 'b) result`

`bind r f` is `f v` if `r = Ok v` and `r` if `r = Error _`.

`val map : ('a -> 'c) -> ('a, 'b) result -> ('c, 'b) result`

`map f r` is `bind (fun v -> ret (f v))` r.

`val join : (('a, 'b) result, 'b) result -> ('a, 'b) result`

`join r` is `v` if `r = Ok v` and `r` otherwise.

`val (>>=) : ('a, 'b) result -> ('a -> ('c, 'b) result) -> ('c, 'b) result`

`r >>= f` is `bind`` r f`.

`val (>>|) : ('a, 'b) result -> ('a -> 'c) -> ('c, 'b) result`

`r >>| f` is `map`` r f`.

`module Infix : sig ... end`

Infix operators.

## Error messages

`type msg = [ `
 `| ```Msg of string`
` ]`

The type for (error) messages.

`val msg : string -> [> msg ]`

`msg s` is ``Msg s`.

`val msgf : ('a, Stdlib.Format.formatter, unit, [> msg ]) Stdlib.format4 -> 'a`

`msgf fmt ...` formats a message according to `fmt`.

`val pp_msg : Stdlib.Format.formatter -> msg -> unit`

`pp_msg ppf m` prints `m` on `ppf`.

`val error_msg : string -> ('a, [> msg ]) result`

`error_msg s` is `error (`Msg s)`.

`val error_msgf : ('a, Stdlib.Format.formatter, unit, ('b, [> msg ]) result) Stdlib.format4 -> 'a`

`error_msgf fmt ...` is an error message formatted according to `fmt`.

`val reword_error_msg : ?replace:bool -> (string -> msg) -> ('a, msg) result -> ('a, [> msg ]) result`

`reword_error_msg ~replace reword r` is like `reword_error` except if `replace` is `false` (default), the result of `reword old_msg` is concatened, on a new line to the old message.

```val error_to_msg : pp_error:(Stdlib.Format.formatter -> 'b -> unit) -> ('a, 'b) result -> ('a, [> msg ]) result```

`error_to_msg ~pp_error r` converts errors in `r` with `pp_error` to an error message.

`val error_msg_to_invalid_arg : ('a, msg) result -> 'a`

`err_msg_to_invalid_arg r` is `v` if `r = Ok v` and

• raises Invalid_argument

with the error message otherwise.

`val open_error_msg : ('a, msg) result -> ('a, [> msg ]) result`

`open_error_msg r` allows to combine a closed error message variant with other variants.

`val failwith_error_msg : ('a, msg) result -> 'a`

`failwith_error_msg r` raises `Failure m` if `r` is `Error (`Msg m)`.

## Trapping unexpected exceptions

Getting rid of `null` was not enough.

`type exn_trap = [ `
 `| ```Exn_trap of exn * Stdlib.Printexc.raw_backtrace`
` ]`

The type for exception traps.

`val pp_exn_trap : Stdlib.Format.formatter -> exn_trap -> unit`

`pp_exn_trap ppf bt` prints `bt` on `ppf`.

`val trap_exn : ('a -> 'b) -> 'a -> ('b, [> exn_trap ]) result`

`trap_exn f v` is `f v` and traps any exception that may occur as an exception trap error.

`val error_exn_trap_to_msg : ('a, exn_trap) result -> ('a, [> msg ]) result`

`error_exn_trap_to_msg r` converts exception trap errors in `r` to an error message.

`val open_error_exn_trap : ('a, exn_trap) result -> ('a, [> exn_trap ]) result`

`open_error_exn_trap r` allows to combine a closed exception trap error variant with other variants.

## Pretty printing

```val pp : ok:(Stdlib.Format.formatter -> 'a -> unit) -> error:(Stdlib.Format.formatter -> 'b -> unit) -> Stdlib.Format.formatter -> ('a, 'b) result -> unit```

`pp ~ok ~error ppf r` prints `r` on `ppf` using `ok` and `error` according to `r`.

```val dump : ok:(Stdlib.Format.formatter -> 'a -> unit) -> error:(Stdlib.Format.formatter -> 'b -> unit) -> Stdlib.Format.formatter -> ('a, 'b) result -> unit```

`dump ~ok ~error` formats an OCaml result value using `ok` or `error` according to case, no parentheses are added.

## Predicates and comparison

`val is_ok : ('a, 'b) result -> bool`

`is_ok r` is `true` iff `r = Ok _`.

`val is_error : ('a, 'b) result -> bool`

`is_error r` is `true` iff `r = Error _`.

```val equal : ok:('a -> 'a -> bool) -> error:('b -> 'b -> bool) -> ('a, 'b) result -> ('a, 'b) result -> bool```

`equal ~ok ~error r r'` tests `r` and `r'` for equality using `ok` and `error`.

```val compare : ok:('a -> 'a -> int) -> error:('b -> 'b -> int) -> ('a, 'b) result -> ('a, 'b) result -> int```

`compare ~ok ~error r r'` totally orders `r` and `r'` using `ok` and `error`.

## Converting

`val to_option : ('a, 'b) result -> 'a option`

`to_option r` is `Some v` if `r = Ok v` and `None` otherwise.

`val of_option : none:(unit -> ('a, 'b) result) -> 'a option -> ('a, 'b) result`

`of_option ~none r` is `Ok v` if `r = Some v` and `none ()` otherwise.

`val to_presult : ('a, 'b) result -> [> `Ok of 'a | `Error of 'b ]`

`to_presult r` is `r` as a polymorphic variant result value.

`val of_presult : [< `Ok of 'a | `Error of 'b ] -> ('a, 'b) result`

`of_presult pr` is `pr` as a result value.

## Ignoring errors

Warning. Using these functions is, most of the time, a bad idea.

`val ignore_error : use:('b -> 'a) -> ('a, 'b) result -> 'a`

`ignore_error ~use r` is `v` if `r = Ok v` and `use e` if `r = Error e`.

`val kignore_error : use:('b -> ('a, 'c) result) -> ('a, 'b) result -> ('a, 'c) result`

`kignore_error ~use r` is `r` if `r = Ok v` and `use e` if `r = Error e`.