package reason-standard

  1. Overview
  2. Docs

Functions for working with optional values.

type 'a t = 'a option
val some : 'a -> 'a option

A function version of the Some constructor.

In most situations you just want to use the Some constructor directly.

However OCaml doesn't support piping to variant constructors.

Note that when using the Reason syntax you can use fast pipe (->) with variant constructors, so you don't need this function.

See the Reason docs for more.

Examples

String.reverse("desserts") |> Option.some = Some "desserts" 
val and_ : 'a t -> 'a t -> 'a t

Returns None if the first argument is None, otherwise return the second argument.

Unlike the built in && operator, the and_ function does not short-circuit.

When you call and_, both arguments are evaluated before being passed to the function.

Examples

Option.and_ (Some 11) (Some 22) = Some 22
Option.and_ None (Some 22) = None
Option.and_ (Some 11) None = None
Option.and_ None None = None
val or_ : 'a t -> 'a t -> 'a t

Return the first argument if it isSome, otherwise return the second.

Unlike the built in || operator, the or_ function does not short-circuit. When you call or_, both arguments are evaluated before being passed to the function.

Examples

Option.or_ (Some 11) (Some 22) = Some 11
Option.or_ None (Some 22) = Some 22
Option.or_ (Some 11) None = Some 11
Option.or_ None None = None
val both : 'a t -> 'b t -> ('a * 'b) t

Transform two options into an option of a Tuple.

Returns None if either of the aguments is None.

Examples

Option.both (Some 3004) (Some "Ant") = Some (3004, "Ant")
Option.both (Some 3004) None = None
Option.both None (Some "Ant") = None
Option.both None None = None
val flatten : 'a t t -> 'a t

Flatten two optional layers into a single optional layer.

Examples

Option.flatten (Some (Some 4)) = Some 4
Option.flatten (Some None) = None
Option.flatten (None) = None
val map : 'a t -> f:('a -> 'b) -> 'b t

Transform the value inside an option.

Leaves None untouched.

See Infix.(>>|) for an operator version of this function.

Examples

Option.map ~f:(fun x -> x * x) (Some 9) = Some 81
Option.map ~f:Int.toString (Some 9) = Some "9"
Option.map ~f:(fun x -> x * x) None = None
val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t

Combine two Options

If both options are Some returns, as Some the result of running f on both values.

If either value is None, returns None

Examples

Option.map2 (Some 3) (Some 4) ~f:Int.add = Some 7
Option.map2 (Some 3) (Some 4) ~f:Tuple.make = Some (3, 4)
Option.map2 (Some 3) None ~f:Int.add = None
Option.map2 None (Some 4) ~f:Int.add = None
val flatMap : 'a t -> f:('a -> 'b t) -> 'b t

Chain together many computations that may not return a value.

It is helpful to see its definition:

let flatMap t ~f =
  match t with
  | Some x -> f x
  | None -> None

This means we only continue with the callback if we have a value.

For example, say you need to parse some user input as a month:

let toValidMonth (month: int) : (int option) =
  if (1 <= month && month <= 12) then
    Some month
  else
    None
in

let userInput = "5" in

Int.ofString userInput
|> Option.flatMap ~f:toValidMonth

If String.toInt produces None (because the userInput was not an integer) this entire chain of operations will short-circuit and result in None. If toValidMonth results in None, again the chain of computations will result in None.

See Infix.(>>=) for an operator version of this function.

Examples

Option.flatMap (Some [1, 2, 3]) ~f:List.head = Some 1
Option.flatMap (Some []) ~f:List.head = None
val get : 'a t -> default:'a -> 'a

Unwrap an option('a) returning default if called with None.

This comes in handy when paired with functions like Map.get or List.head which return an Option.

Examples

Option.get ~default:99 (Some 42) = 42
Option.get ~default:99 None = 99
Option.get ~default:"unknown" (Map.get Map.String.empty "Tom") = "unknown"
val (|?) : 'a t -> 'a -> 'a

The operator version of get

Examples

Option.(Some 3004 |? 8) = 3004
Option.(None |? 8) = 8
val getUnsafe : 'a t -> 'a

Unwrap an option('a) returning the enclosed 'a.

Note in most situations it is better to use pattern matching, get, map or flatMap. Can you structure your code slightly differently to avoid potentially raising an exception?

Exceptions

Raises an Invalid_argument exception if called with None

Examples

List.head [1;2;3] |> Option.getUnsafe = 1
List.head [] |> Option.getUnsafe (* raises 'Invalid_argument' *)
val isSome : 'a t -> bool

Check if an Option is a Some.

In most situtations you should just use pattern matching instead.

Examples

Option.isSome (Some 3004) = true
Option.isSome None = false
val isNone : 'a t -> bool

Check if an Option is a None.

In most situtations you should just use pattern matching instead.

Examples

Option.isNone (Some 3004) = false
Option.isNone None = true
val forEach : 'a t -> f:('a -> unit) -> unit

Run a function against a value, if it is present.

val toArray : 'a t -> 'a array

Convert an option to a Array.

None is represented as an empty array and Some is represented as an array of one element.

Examples

Option.toArray (Some 3004) = [|3004|]
Option.toArray (None) = [||]
val toList : 'a t -> 'a list

Convert an option to a List.

None is represented as an empty list and Some is represented as a list of one element.

Examples

Option.toList (Some 3004) = [3004]
Option.toList (None) = []

Compare

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

Test two optional values for equality using the provided function

Examples

Option.equal Int.equal (Some 1) (Some 1) = true
Option.equal Int.equal (Some 1) (Some 3) = false
Option.equal Int.equal (Some 1) None = false
Option.equal Int.equal None None = true
val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int

Compare two optional values using the provided function.

A None is "less" than a Some

Examples

Option.compare Int.compare (Some 1) (Some 3) = -1
Option.compare Int.compare (Some 1) None = 1
Option.compare Int.compare None None = 0
module Infix : sig ... end

Operators for code that works extensively with Options.

val let+ : 'a t -> ('a -> 'b) -> 'b t

The binding operator for Core.Option.map

Note Currently this is only supported by the OCaml syntax.

Note This requires at least OCaml 4.08 which means currently this is only supported by the native compiler.

val and+ : 'a t -> 'b t -> ('a * 'b) t

The binding operator for Core.Option.both

Note Currently this is only supported by the OCaml syntax.

Note This requires at least OCaml 4.08 which means currently this is only supported by the native compiler.

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

The binding operator for Core.Option.flatMap

Note Currently this is only supported by the OCaml syntax.

Note This requires at least OCaml 4.08 which means currently this is only supported by the native compiler.

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

The binding operator for Core.Option.both

Note Currently this is only supported by the OCaml syntax.

Note This requires at least OCaml 4.08 which means currently this is only supported by the native compiler.

OCaml

Innovation. Community. Security.