Module CCOption

Basic operations on the option type.

This module replaces `CCOpt`.

Options

type 'a t = 'a option =
  1. | None
  2. | Some of 'a

The type for option values. Either None or a value Some v.

val none : 'a option

none is None.

val some : 'a -> 'a option

some v is Some v.

val value : 'a option -> default:'a -> 'a

value o ~default is v if o is Some v and default otherwise.

val get : 'a option -> 'a

get o is v if o is Some v and raise otherwise.

  • raises Invalid_argument

    if o is None.

val bind : 'a option -> ('a -> 'b option) -> 'b option

bind o f is f v if o is Some v and None if o is None.

val join : 'a option option -> 'a option

join oo is Some v if oo is Some (Some v) and None otherwise.

val map : ('a -> 'b) -> 'a option -> 'b option

map f o is None if o is None and Some (f v) if o is Some v.

val iter : ('a -> unit) -> 'a option -> unit

iter f o is f v if o is Some v and () otherwise.

Predicates and comparisons

val is_none : 'a option -> bool

is_none o is true if and only if o is None.

val is_some : 'a option -> bool

is_some o is true if and only if o is Some o.

val equal : ('a -> 'a -> bool) -> 'a option -> 'a option -> bool

equal eq o0 o1 is true if and only if o0 and o1 are both None or if they are Some v0 and Some v1 and eq v0 v1 is true.

val compare : ('a -> 'a -> int) -> 'a option -> 'a option -> int

compare cmp o0 o1 is a total order on options using cmp to compare values wrapped by Some _. None is smaller than Some _ values.

Converting

val to_list : 'a option -> 'a list

to_list o is [] if o is None and [v] if o is Some v.

val to_seq : 'a option -> 'a Stdlib.Seq.t

to_seq o is o as a sequence. None is the empty sequence and Some v is the singleton sequence containing v.

val map_or : default:'b -> ('a -> 'b) -> 'a t -> 'b

map_or ~default f o is f x if o = Some x, default otherwise.

  • since 0.16
val map_lazy : (unit -> 'b) -> ('a -> 'b) -> 'a t -> 'b

map_lazy default_fn f o is f x if o = Some x, default_fn () otherwise.

  • since 1.2
val return : 'a -> 'a t

return x is a monadic return, that is return x = Some x.

val flat_map : ('a -> 'b t) -> 'a t -> 'b t

flat_map f o is equivalent to map followed by flatten. Flip version of (>>=).

val flat_map_l : ('a -> 'b list) -> 'a t -> 'b list

flat_map_l f o is [] if o is None, or f x if o is Some x.

  • since 3.12
val k_compose : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

Kleisli composition. Monadic equivalent of CCFun.compose

  • since 3.13.1
val map2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t

map2 f o1 o2 maps 'a option and 'b option to a 'c option using f.

val fold : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a

fold f init o is f init x if o is Some x, or init if o is None. Fold on 0 or 1 element.

val filter : ('a -> bool) -> 'a t -> 'a t

filter f o returns Some x if o is Some x and f x is true, or None if f x is false or if o is None. Filter on 0 or 1 element.

  • since 0.5
val if_ : ('a -> bool) -> 'a -> 'a option

if_ f x is Some x if f x, None otherwise.

  • since 0.17
val exists : ('a -> bool) -> 'a t -> bool

exists f o returns true iff there exists an element for which the provided function f evaluates to true.

  • since 0.17
val for_all : ('a -> bool) -> 'a t -> bool

for_all f o returns true iff the provided function f evaluates to true for all elements.

  • since 0.17
val get_or : default:'a -> 'a t -> 'a

get_or ~default o extracts the value from o, or returns default if o is None.

  • since 0.18
val apply_or : ('a -> 'a t) -> 'a -> 'a

apply_or f x returns the original x if f fails, or unwraps f x if it succeeds. Useful for piping preprocessing functions together (such as string processing), turning functions like "remove" into "remove_if_it_exists".

  • since 3.13.1
val get_exn : 'a t -> 'a

get_exn o returns x if o is Some x or fails if o is None.

  • raises Invalid_argument

    if the option is None.

val get_exn_or : string -> 'a t -> 'a

get_exn_or msg o returns x if o is Some x or fails with Invalid_argument msg if o is None.

  • raises Invalid_argument

    if the option is None.

  • since 3.4
val get_lazy : (unit -> 'a) -> 'a t -> 'a

get_lazy default_fn o unwraps o, but if o is None it returns default_fn () instead.

  • since 0.6.1
val sequence_l : 'a t list -> 'a list t

sequence_l [x1; x2; …; xn] returns Some [y1; y2; …; yn] if every xi is Some yi. Otherwise, if the list contains at least one None, the result is None.

val wrap : ?handler:(exn -> bool) -> ('a -> 'b) -> 'a -> 'b option

wrap ?handler f x calls f x and returns Some y if f x = y. If f x raises any exception, the result is None. This can be useful to wrap functions such as Map.S.find.

  • parameter handler

    the exception handler, which returns true if the exception is to be caught.

val wrap2 : ?handler:(exn -> bool) -> ('a -> 'b -> 'c) -> 'a -> 'b -> 'c option

wrap2 ?handler f x y is similar to wrap but for binary functions.

Applicative

val pure : 'a -> 'a t

pure x is an alias to return.

Alternatives

val or_ : else_:'a t -> 'a t -> 'a t

or_ ~else_ o is o if o is Some _, else_ if o is None.

  • since 1.2
val or_lazy : else_:(unit -> 'a t) -> 'a t -> 'a t

or_lazy ~else_ o is o if o is Some _, else_ () if o is None.

  • since 1.2
val choice : 'a t list -> 'a t

choice lo returns the first non-None element of the list lo, or None.

val flatten : 'a t t -> 'a t

flatten oo transforms Some x into x.

  • since 2.2
val return_if : bool -> 'a -> 'a t

return_if b x applies Some or None depending on the boolean b. More precisely, return_if false x is None, and return_if true x is Some x.

  • since 2.2

Infix Operators

module Infix : sig ... end
include module type of Infix
val (>|=) : 'a t -> ('a -> 'b) -> 'b t

o >|= f is map f o.

val (>>=) : 'a t -> ('a -> 'b t) -> 'b t

o >>= f is the monadic bind.

val (<*>) : ('a -> 'b) t -> 'a t -> 'b t

f <*> o returns Some (f x) if o is Some x and None if o is None.

val (<$>) : ('a -> 'b) -> 'a t -> 'b t

f <$> o is like map f o.

val (<+>) : 'a t -> 'a t -> 'a t

o1 <+> o2 is o1 if o1 is Some _, o2 if o1 is None.

val (|?>) : 'a -> ('a -> 'a t) -> 'a

x |?> f is apply_or f x

  • since 3.13.1
val (let+) : 'a t -> ('a -> 'b) -> 'b t
val (and+) : 'a t -> 'b t -> ('a * 'b) t
val (let*) : 'a t -> ('a -> 'b t) -> 'b t
val (and*) : 'a t -> 'b t -> ('a * 'b) t
val (>=>) : ('a -> 'b t) -> ('b -> 'c t) -> 'a -> 'c t

Monadic k_compose.

  • since 3.13.1
val (<=<) : ('b -> 'c t) -> ('a -> 'b t) -> 'a -> 'c t

Reverse monadic k_compose.

  • since 3.13.1

Conversion and IO

val of_list : 'a list -> 'a t

of_list l returns Some x (x being the head of the list l), or None if l is the empty list.

val to_result : 'e -> 'a t -> ('a, 'e) result

to_result e o returns Ok x if o is Some x, or Error e if o is None.

  • since 1.2
val to_result_lazy : (unit -> 'e) -> 'a t -> ('a, 'e) result

to_result_lazy f o returns Ok x if o is Some x or Error f if o is None.

  • since 1.2
val of_result : ('a, _) result -> 'a t

of_result result returns an option from a result.

  • since 1.2
type 'a iter = ('a -> unit) -> unit
type 'a gen = unit -> 'a option
type 'a printer = Stdlib.Format.formatter -> 'a -> unit
type 'a random_gen = Stdlib.Random.State.t -> 'a
val random : 'a random_gen -> 'a t random_gen
val choice_iter : 'a t iter -> 'a t

choice_iter iter is similar to choice, but works on iter. It returns the first Some x occurring in iter, or None otherwise.

  • since 3.0
val choice_seq : 'a t Stdlib.Seq.t -> 'a t

choice_seq seq works on Seq.t. It returns the first Some x occurring in seq, or None otherwise.

  • since 3.0
val to_gen : 'a t -> 'a gen

to_gen o is o as a gen. Some x is the singleton gen containing x and None is the empty gen.

val to_iter : 'a t -> 'a iter

to_iter o returns an internal iterator, like in the library Iter.

  • since 2.8
val pp : 'a printer -> 'a t printer

pp ppf o pretty-prints option o using ppf.