API / Belt / Option

You are currently looking at the v9.1 - v10.1 docs (Reason v3.6 syntax edition). You can find the latest API docs here.

Option

In Belt we represent the existence and nonexistence of a value by wrapping it with the option type. In order to make it a bit more convenient to work with option-types, Belt provides utility-functions for it.

The option type is a part of the Reason / OCaml standard library which is defined like this:

RES
type option<'a> = None | Some('a)

RES
let someString: option<string> = Some("hello")

getExn

RES
let getExn: option<'a> => 'a

Raises an Error in case None is provided. Use with care.

RES
Belt.Option.getExn(Some(3)) /* 3 */

Belt.Option.getExn(None) /* Raises an Error */

mapWithDefault

RES
let mapWithDefault: (option<'a>, 'b, 'a => 'b) => 'b

If optionValue is of Some(value), this function returns that value applied with f, in other words f(value).

If optionValue is None, the default is returned.

RES
let someValue = Some(3)
someValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 8 */

let noneValue = None
noneValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 0 */

mapWithDefaultU

RES
let mapWithDefaultU: (option<'a>, 'b, (. 'a) => 'b) => 'b

Uncurried version of mapWithDefault.

map

RES
let map: (option<'a>, 'a => 'b) => option<'b>

If optionValue is Some(value) this returns f(value), otherwise it returns None.

RES
Belt.Option.map(Some(3), x => x * x) /* Some(9) */

Belt.Option.map(None, x => x * x) /* None */

mapU

RES
let mapU: (option<'a>, (. 'a) => 'b) => option<'b>

Uncurried version of map.

flatMap

RES
let flatMap: (option<'a>, 'a => option<'b>) => option<'b>

If optionValue is Some(value), returns f(value), otherwise returns None.
The function f must have a return type of option<'b>.

RES
let addIfAboveOne = value =>
  if (value > 1) {
    Some(value + 1)
  } else {
    None
  }

Belt.Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */

Belt.Option.flatMap(Some(-4), addIfAboveOne) /* None */

Belt.Option.flatMap(None, addIfAboveOne) /* None */

flatMapU

RES
let flatMapU: (option<'a>, (. 'a) => option<'b>) => option<'b>

Uncurried version of flatMap.

getWithDefault

RES
let getWithDefault: (option<'a>, 'a) => 'a

If optionalValue is Some(value), returns value, otherwise default.

RES
Belt.Option.getWithDefault(None, "Banana") /* Banana */

Belt.Option.getWithDefault(Some("Apple"), "Banana") /* Apple */

RES
let greet = (firstName: option<string>) =>
  "Greetings " ++ firstName->Belt.Option.getWithDefault("Anonymous")

Some("Jane")->greet /* "Greetings Jane" */

None->greet /* "Greetings Anonymous" */

RES
Belt.Option.getWithDefault(Some(1812), 1066) /* 1812 */

Belt.Option.getWithDefault(None, 1066) /* 1066 */

isSome

RES
let isSome: option<'a> => bool

Returns true if the argument is Some(value), false otherwise.

RES
Belt.Option.isSome(None) /* false */

Belt.Option.isSome(Some(1)) /* true */

isNone

RES
let isNone: option<'a> => bool

Returns true if the argument is None, false otherwise.

RES
Belt.Option.isNone(None) /* true */

Belt.Option.isNone(Some(1)) /* false */

eq

RES
let eq: (option<'a>, option<'b>, ('a, 'b) => bool) => bool

Evaluates two optional values for equality with respect to a predicate function. If both optValue1 and optValue2 are None, returns true. If one of the arguments is Some(value) and the other is None, returns false.

If arguments are Some(value1) and Some(value2), returns the result of predicate(value1, value2); the predicate function must return a bool.

RES
let clockEqual = (a, b) => mod(a, 12) == mod(b, 12)

open Belt.Option

eq(Some(3), Some(15), clockEqual) /* true */

eq(Some(3), None, clockEqual) /* false */

eq(None, Some(3), clockEqual) /* false */

eq(None, None, clockEqual) /* true */

eqU

RES
let eqU: (option<'a>, option<'b>, (.'a, 'b) => bool) => bool

Uncurried version of eq.

cmp

RES
let cmp: (option<'a>, option<'b>, ('a, 'b) => int) => int

cmp(optValue1, optValue2, comparisonFunction) compares two optional values with respect to given comparisonFunction.

If both optValue1 and optValue2 are None, it returns 0.

If the first argument is Some(value1) and the second is None, returns 1 (something is greater than nothing).

If the first argument is None and the second is Some(value2), returns -1 (nothing is less than something).

If the arguments are Some(value1) and Some(value2), returns the result of comparisonFunction(value1, value2); comparisonFunction takes two arguments and returns -1 if the first argument is less than the second, 0 if the arguments are equal, and 1 if the first argument is greater than the second.

RES
let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12))

open Belt.Option

cmp(Some(3), Some(15), clockCompare) /* 0 */

cmp(Some(3), Some(14), clockCompare) /* 1 */

cmp(Some(2), Some(15), clockCompare) /* (-1) */

cmp(None, Some(15), clockCompare) /* (-1) */

cmp(Some(14), None, clockCompare) /* 1 */

cmp(None, None, clockCompare) /* 0 */

cmpU

RES
let cmpU: (option<'a>, option<'b>, ((.'a, 'b) => int)) => int

Uncurried version of cmp.