102 lines
4.1 KiB
OCaml
102 lines
4.1 KiB
OCaml
(**************************************************************************)
|
|
(* *)
|
|
(* OCaml *)
|
|
(* *)
|
|
(* The OCaml programmers *)
|
|
(* *)
|
|
(* Copyright 2018 Institut National de Recherche en Informatique et *)
|
|
(* en Automatique. *)
|
|
(* *)
|
|
(* All rights reserved. This file is distributed under the terms of *)
|
|
(* the GNU Lesser General Public License version 2.1, with the *)
|
|
(* special exception on linking described in the file LICENSE. *)
|
|
(* *)
|
|
(**************************************************************************)
|
|
|
|
(** Result values.
|
|
|
|
Result values handle computation results and errors in an explicit
|
|
and declarative manner without resorting to exceptions.
|
|
|
|
@since 4.08 *)
|
|
|
|
(** {1:results Results} *)
|
|
|
|
type ('a, 'e) t = ('a, 'e) result = Ok of 'a | Error of 'e (**)
|
|
(** The type for result values. Either a value [Ok v] or an error [Error e]. *)
|
|
|
|
val ok : 'a -> ('a, 'e) result
|
|
(** [ok v] is [Ok v]. *)
|
|
|
|
val error : 'e -> ('a, 'e) result
|
|
(** [error e] is [Error e]. *)
|
|
|
|
val value : ('a, 'e) result -> default:'a -> 'a
|
|
(** [value r ~default] is [v] if [r] is [Ok v] and [default] otherwise. *)
|
|
|
|
val get_ok : ('a, 'e) result -> 'a
|
|
(** [get_ok r] is [v] if [r] is [Ok v] and @raise Invalid_argument
|
|
otherwise. *)
|
|
|
|
val get_error : ('a, 'e) result -> 'e
|
|
(** [get_error r] is [e] if [r] is [Error e] and @raise Invalid_argument
|
|
otherwise. *)
|
|
|
|
val bind : ('a, 'e) result -> ('a -> ('b, 'e) result) -> ('b, 'e) result
|
|
(** [bind r f] is [f v] if [r] is [Ok v] and [r] if [r] is [Error _]. *)
|
|
|
|
val join : (('a, 'e) result, 'e) result -> ('a, 'e) result
|
|
(** [join rr] is [r] if [rr] is [Ok r] and [rr] if [rr] is [Error _]. *)
|
|
|
|
val map : ('a -> 'b) -> ('a, 'e) result -> ('b, 'e) result
|
|
(** [map f r] is [Ok (f v)] if [r] is [Ok v] and [r] if [r] is [Error _]. *)
|
|
|
|
val map_error : ('e -> 'f) -> ('a, 'e) result -> ('a, 'f) result
|
|
(** [map_error f r] is [Error (f e)] if [r] is [Error e] and [r] if
|
|
[r] is [Ok _]. *)
|
|
|
|
val fold : ok:('a -> 'c) -> error:('e -> 'c) -> ('a, 'e) result -> 'c
|
|
(** [fold ~ok ~error r] is [ok v] if [r] is [Ok v] and [error e] if [r]
|
|
is [Error e]. *)
|
|
|
|
val iter : ('a -> unit) -> ('a, 'e) result -> unit
|
|
(** [iter f r] is [f v] if [r] is [Ok v] and [()] otherwise. *)
|
|
|
|
val iter_error : ('e -> unit) -> ('a, 'e) result -> unit
|
|
(** [iter_error f r] is [f e] if [r] is [Error e] and [()] otherwise. *)
|
|
|
|
(** {1:preds Predicates and comparisons} *)
|
|
|
|
val is_ok : ('a, 'e) result -> bool
|
|
(** [is_ok r] is [true] iff [r] is [Ok _]. *)
|
|
|
|
val is_error : ('a, 'e) result -> bool
|
|
(** [is_error r] is [true] iff [r] is [Error _]. *)
|
|
|
|
val equal :
|
|
ok:('a -> 'a -> bool) -> error:('e -> 'e -> bool) -> ('a, 'e) result ->
|
|
('a, 'e) result -> bool
|
|
(** [equal ~ok ~error r0 r1] tests equality of [r0] and [r1] using [ok]
|
|
and [error] to respectively compare values wrapped by [Ok _] and
|
|
[Error _]. *)
|
|
|
|
val compare :
|
|
ok:('a -> 'a -> int) -> error:('e -> 'e -> int) -> ('a, 'e) result ->
|
|
('a, 'e) result -> int
|
|
(** [compare ~ok ~error r0 r1] totally orders [r0] and [r1] using [ok] and
|
|
[error] to respectively compare values wrapped by [Ok _ ] and [Error _].
|
|
[Ok _] values are smaller than [Error _] values. *)
|
|
|
|
(** {1:convert Converting} *)
|
|
|
|
val to_option : ('a, 'e) result -> 'a option
|
|
(** [to_option r] is [r] as an option, mapping [Ok v] to [Some v] and
|
|
[Error _] to [None]. *)
|
|
|
|
val to_list : ('a, 'e) result -> 'a list
|
|
(** [to_list r] is [[v]] if [r] is [Ok v] and [[]] otherwise. *)
|
|
|
|
val to_seq : ('a, 'e) result -> 'a Seq.t
|
|
(** [to_seq r] is [r] as a sequence. [Ok v] is the singleton sequence
|
|
containing [v] and [Error _] is the empty sequence. *)
|