package base

  1. Overview
  2. Docs
package base
Legend:
Library
Module
Module type
Parameter
Class
Class type

The option type indicates whether a meaningful value is present. It is frequently used to represent success or failure, using None for failure. To be more descriptive about why a function failed, see the Or_error module.

Usage example from a utop session follows. Hash table lookups use the option type to indicate success or failure when looking up a key.

  # let h = Hashtbl.of_alist (module String) [ ("Bar", "Value") ];;
  val h : (string, string) Hashtbl.t = <abstr>;;
  - : (string, string) Hashtbl.t = <abstr>
  # Hashtbl.find h "Foo";;
  - : string option = None
  # Hashtbl.find h "Bar";;
  - : string option = Some "Value"

Type and Interfaces

type 'a t = 'a option =
  1. | None
  2. | Some of 'a
val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
val hash_fold_t : (Hash.state -> 'a -> Hash.state) -> Hash.state -> 'a t -> Hash.state
val t_sexp_grammar : 'a Sexplib0.Sexp_grammar.t -> 'a t Sexplib0.Sexp_grammar.t
include Equal.S1 with type 'a t := 'a t
val equal : 'a Equal.equal -> 'a t Equal.equal
include Invariant.S1 with type 'a t := 'a t
val invariant : ('a -> unit) -> 'a t -> unit
include Sexpable.S1 with type 'a t := 'a t
val t_of_sexp : (Sexplib0.Sexp.t -> 'a) -> Sexplib0.Sexp.t -> 'a t
val sexp_of_t : ('a -> Sexplib0.Sexp.t) -> 'a t -> Sexplib0.Sexp.t

Applicative interface

Options form an applicative, where:

  • return x = Some x
  • None <*> x = None
  • Some f <*> None = None
  • Some f <*> Some x = Some (f x)
include Applicative.S with type 'a t := 'a t
val both : 'a t -> 'b t -> ('a * 'b) t
val (<*>) : ('a -> 'b) t -> 'a t -> 'b t

same as apply

val (<*) : 'a t -> unit t -> 'a t
val (*>) : unit t -> 'a t -> 'a t
val apply : ('a -> 'b) t -> 'a t -> 'b t
val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t
val map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t
module Applicative_infix : sig ... end

Monadic interface

Options form a monad, where:

  • return x = Some x
  • (None >>= f) = None
  • (Some x >>= f) = f x
include Monad.S with type 'a t := 'a t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t

t >>= f returns a computation that sequences the computations represented by two monad elements. The resulting computation first does t to yield a value v, and then runs the computation returned by f v.

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

t >>| f is t >>= (fun a -> return (f a)).

module Monad_infix : sig ... end
val bind : 'a t -> f:('a -> 'b t) -> 'b t

bind t ~f = t >>= f

val return : 'a -> 'a t

return v returns the (trivial) computation that returns v.

val map : 'a t -> f:('a -> 'b) -> 'b t

map t ~f is t >>| f.

val join : 'a t t -> 'a t

join t is t >>= (fun t' -> t').

val ignore_m : 'a t -> unit t

ignore_m t is map t ~f:(fun _ -> ()). ignore_m used to be called ignore, but we decided that was a bad name, because it shadowed the widely used Caml.ignore. Some monads still do let ignore = ignore_m for historical reasons.

val all : 'a t list -> 'a list t
val all_unit : unit t list -> unit t

Like all, but ensures that every monadic value in the list produces a unit value, all of which are discarded rather than being collected into a list.

module Let_syntax : sig ... end

These are convenient to have in scope when programming with a monad:

Extracting Underlying Values

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

Extracts the underlying value if present, otherwise returns default.

val value_exn : ?here:Base__.Import.Caml.Lexing.position -> ?error:Error.t -> ?message:string -> 'a t -> 'a

Extracts the underlying value, or raises if there is no value present. The error raised can be augmented using the ~here, ~error, and ~message optional arguments.

val value_map : 'a t -> default:'b -> f:('a -> 'b) -> 'b

Extracts the underlying value and applies f to it if present, otherwise returns default.

val value_or_thunk : 'a t -> default:(unit -> 'a) -> 'a

Extracts the underlying value if present, otherwise executes and returns the result of default. default is only executed if the underlying value is absent.

val fold : 'a t -> init:'accum -> f:('accum -> 'a -> 'accum) -> 'accum

On None, returns init. On Some x, returns f init x.

val mem : 'a t -> 'a -> equal:('a -> 'a -> bool) -> bool

Checks whether the provided element is there, using equal.

val length : 'a t -> int
val iter : 'a t -> f:('a -> unit) -> unit
val exists : 'a t -> f:('a -> bool) -> bool

On None, returns false. On Some x, returns f x.

val for_all : 'a t -> f:('a -> bool) -> bool

On None, returns true. On Some x, returns f x.

val find : 'a t -> f:('a -> bool) -> 'a option

find t ~f returns t if t = Some x and f x = true; otherwise, find returns None.

val find_map : 'a t -> f:('a -> 'b option) -> 'b option

On None, returns None. On Some x, returns f x.

val to_list : 'a t -> 'a list
val to_array : 'a t -> 'a array
val call : 'a -> f:('a -> unit) t -> unit

call x f runs an optional function ~f on the argument.

val merge : 'a t -> 'a t -> f:('a -> 'a -> 'a) -> 'a t

merge a b ~f merges together the values from a and b using f. If both a and b are None, returns None. If only one is Some, returns that one, and if both are Some, returns Some of the result of applying f to the contents of a and b.

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

Constructors

val try_with : (unit -> 'a) -> 'a t

try_with f returns Some x if f returns x and None if f raises an exception. See Result.try_with if you'd like to know which exception.

val try_with_join : (unit -> 'a t) -> 'a t

try_with_join f returns the optional value returned by f if it exits normally, and None if f raises an exception.

val some : 'a -> 'a t

Wraps the Some constructor as a function.

val first_some : 'a t -> 'a t -> 'a t

first_some t1 t2 returns t1 if it has an underlying value, or t2 otherwise.

val some_if : bool -> 'a -> 'a t

some_if b x converts a value x to Some x if b, and None otherwise.

Predicates

val is_none : 'a t -> bool

is_none t returns true iff t = None.

val is_some : 'a t -> bool

is_some t returns true iff t = Some x.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct