Module CCResultSource

Error Monad

Uses the new "result" type from OCaml 4.03.

Sourcetype 'a sequence = ('a -> unit) -> unit
  • deprecated

    use 'a iter instead

Sourcetype 'a iter = ('a -> unit) -> unit

Fast internal iterator.

  • since 2.8
Sourcetype 'a equal = 'a -> 'a -> bool
Sourcetype 'a ord = 'a -> 'a -> int
Sourcetype 'a printer = Format.formatter -> 'a -> unit

Basics

Sourcetype nonrec (+'good, +'bad) result = ('good, 'bad) result =
  1. | Ok of 'good
  2. | Error of 'bad
Sourcetype (+'good, +'bad) t = ('good, 'bad) result =
  1. | Ok of 'good
  2. | Error of 'bad
Sourceval return : 'a -> ('a, 'err) t

Successfully return a value.

Sourceval fail : 'err -> ('a, 'err) t

Fail with an error.

Sourceval of_exn : exn -> ('a, string) t

of_exn e uses Printexc to print the exception as a string.

Sourceval of_exn_trace : exn -> ('a, string) t

of_exn_trace e is similar to of_exn e, but it adds the stacktrace to the error message.

Remember to call Printexc.record_backtrace true and compile with the debug flag for this to work.

Sourceval fail_printf : ('a, Buffer.t, unit, ('b, string) t) format4 -> 'a

fail_printf format uses format to obtain an error message and then returns Error msg.

Sourceval fail_fprintf : ('a, Format.formatter, unit, ('b, string) t) format4 -> 'a

fail_fprintf format uses format to obtain an error message and then returns Error msg.

Sourceval add_ctx : string -> ('a, string) t -> ('a, string) t

add_ctx msg leaves Ok x untouched, but transforms Error s into Error s' where s' contains the additional context given by msg.

  • since 1.2
Sourceval add_ctxf : ('a, Format.formatter, unit, ('b, string) t -> ('b, string) t) format4 -> 'a

add_ctxf format_message is similar to add_ctx but with Format for printing the message (eagerly). Example:

  add_ctxf "message(number %d, foo: %B)" 42 true (Error "error)"
  • since 1.2
Sourceval map : ('a -> 'b) -> ('a, 'err) t -> ('b, 'err) t

Map on success.

Sourceval map_err : ('err1 -> 'err2) -> ('a, 'err1) t -> ('a, 'err2) t

Map on the error variant.

Sourceval map2 : ('a -> 'b) -> ('err1 -> 'err2) -> ('a, 'err1) t -> ('b, 'err2) t

Like map, but also with a function that can transform the error message in case of failure.

Sourceval iter : ('a -> unit) -> ('a, _) t -> unit

Apply the function only in case of Ok.

Sourceval iter_err : ('err -> unit) -> (_, 'err) t -> unit

Apply the function in case of Error.

  • since 2.4
Sourceexception Get_error
Sourceval get_exn : ('a, _) t -> 'a

Extract the value x from Ok x, fails otherwise. You should be careful with this function, and favor other combinators whenever possible.

Sourceval get_or : ('a, _) t -> default:'a -> 'a

get_or e ~default returns x if e = Ok x, default otherwise.

Sourceval get_or_failwith : ('a, string) t -> 'a

get_or_failwith e returns x if e = Ok x, fails otherwise.

  • raises Failure

    with msg if e = Error msg.

  • since 2.4
Sourceval map_or : ('a -> 'b) -> ('a, 'c) t -> default:'b -> 'b

map_or f e ~default returns f x if e = Ok x, default otherwise.

Sourceval catch : ('a, 'err) t -> ok:('a -> 'b) -> err:('err -> 'b) -> 'b

catch e ~ok ~err calls either ok or err depending on the value of e.

Sourceval flat_map : ('a -> ('b, 'err) t) -> ('a, 'err) t -> ('b, 'err) t
Sourceval (>|=) : ('a, 'err) t -> ('a -> 'b) -> ('b, 'err) t
Sourceval (>>=) : ('a, 'err) t -> ('a -> ('b, 'err) t) -> ('b, 'err) t

Monadic composition. e >>= f proceeds as f x if e is Ok x or returns e if e is an Error.

Sourceval equal : err:'err equal -> 'a equal -> ('a, 'err) t equal
Sourceval compare : err:'err ord -> 'a ord -> ('a, 'err) t ord
Sourceval fold : ok:('a -> 'b) -> error:('err -> 'b) -> ('a, 'err) t -> 'b

fold ~ok ~error e opens e and, if e = Ok x, returns ok x, otherwise e = Error s and it returns error s.

Sourceval fold_ok : ('a -> 'b -> 'a) -> 'a -> ('b, _) t -> 'a

fold_ok f acc r will compute f acc x if r=Ok x, and return acc otherwise, as if the result were a mere option.

  • since 1.2
Sourceval is_ok : ('a, 'err) t -> bool

Return true if Ok.

  • since 1.0
Sourceval is_error : ('a, 'err) t -> bool

Return true if Error.

  • since 1.0

Wrappers

Sourceval guard : (unit -> 'a) -> ('a, exn) t

guard f runs f () and returns its result wrapped in Ok. If f () raises some exception e, then it fails with Error e.

Sourceval guard_str : (unit -> 'a) -> ('a, string) t

Like guard but uses of_exn to print the exception.

Sourceval guard_str_trace : (unit -> 'a) -> ('a, string) t

Like guard_str but uses of_exn_trace instead of of_exn so that the stack trace is printed.

Sourceval wrap1 : ('a -> 'b) -> 'a -> ('b, exn) t

Like guard but gives the function one argument.

Sourceval wrap2 : ('a -> 'b -> 'c) -> 'a -> 'b -> ('c, exn) t

Like guard but gives the function two arguments.

Sourceval wrap3 : ('a -> 'b -> 'c -> 'd) -> 'a -> 'b -> 'c -> ('d, exn) t

Like guard but gives the function three arguments.

Applicative

Sourceval pure : 'a -> ('a, 'err) t

Synonym of return.

Sourceval (<*>) : ('a -> 'b, 'err) t -> ('a, 'err) t -> ('b, 'err) t

a <*> b evaluates a and b, and, in case of success, returns Ok (a b). Otherwise, it fails, and the error of a is chosen over the error of b if both fail.

Sourceval join : (('a, 'err) t, 'err) t -> ('a, 'err) t

join t, in case of success, returns Ok o from Ok (Ok o). Otherwise, it fails with Error e where e is the unwrapped error of t.

Sourceval both : ('a, 'err) t -> ('b, 'err) t -> ('a * 'b, 'err) t

both a b, in case of success, returns Ok (o, o') with the ok values of a and b. Otherwise, it fails, and the error of a is chosen over the error of b if both fail.

Infix

Sourcemodule Infix : sig ... end

Let operators on OCaml >= 4.08.0, nothing otherwise

  • since 2.8
include CCShimsMkLet_.S2 with type ('a, 'e) t_let2 := ('a, 'e) result
Sourceval (let+) : ('a, 'e) result -> ('a -> 'b) -> ('b, 'e) result
Sourceval (and+) : ('a, 'e) result -> ('b, 'e) result -> ('a * 'b, 'e) result
Sourceval (let*) : ('a, 'e) result -> ('a -> ('b, 'e) result) -> ('b, 'e) result
Sourceval (and*) : ('a, 'e) result -> ('b, 'e) result -> ('a * 'b, 'e) result

Collections

Sourceval flatten_l : ('a, 'err) t list -> ('a list, 'err) t

Same as map_l id: returns Ok [x1;…;xn] if l=[Ok x1; …; Ok xn], or the first error otherwise.

  • since 2.7
Sourceval map_l : ('a -> ('b, 'err) t) -> 'a list -> ('b list, 'err) t

map_l f [a1; ...; an] applies the function f to a1, ..., an , and, in case of success for every element, returns the list of Ok-value. Otherwise, it fails and returns the first error encountered. Tail-recursive.

Sourceval fold_l : ('b -> 'a -> ('b, 'err) t) -> 'b -> 'a list -> ('b, 'err) t
Sourceval fold_seq : ('b -> 'a -> ('b, 'err) t) -> 'b -> 'a sequence -> ('b, 'err) t

Misc

Sourceval choose : ('a, 'err) t list -> ('a, 'err list) t

choose l selects a member of l that is a Ok _ value, or returns Error l otherwise, where l is the list of errors.

Sourceval retry : int -> (unit -> ('a, 'err) t) -> ('a, 'err list) t

retry n f calls f at most n times, returning the first result of f () that doesn't fail. If f fails n times, retry n f fails with the list of successive errors.

Sourcemodule type MONAD = sig ... end
Sourcemodule Traverse (M : MONAD) : sig ... end

Conversions

Sourceval to_opt : ('a, _) t -> 'a option

Convert a result to an option.

Sourceval of_opt : 'a option -> ('a, string) t

Convert an option to a result.

Sourceval to_iter : ('a, _) t -> 'a iter
  • since 2.8
Sourceval to_std_seq : ('a, _) t -> 'a Seq.t
  • since 2.8
Sourceval to_seq : ('a, _) t -> 'a sequence
  • deprecated use to_iter or to_std_seq
Sourcetype ('a, 'b) error = [
  1. | `Ok of 'a
  2. | `Error of 'b
]
Sourceval of_err : ('a, 'b) error -> ('a, 'b) t
  • since 0.17
Sourceval to_err : ('a, 'b) t -> ('a, 'b) error
  • since 0.17

IO

Sourceval pp : 'a printer -> ('a, string) t printer
Sourceval pp' : 'a printer -> 'e printer -> ('a, 'e) t printer

Printer that is generic on the error type.