API / Belt / Belt_Option

Belt_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 ReScript standard library which is defined like this:

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

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

keepU

Uncurried version of keep

let keepU: (option<'a>, (. 'a) => bool) => option<'a>

keep

If optionValue is Some(value) and p(value) = true, it returns Some(value); otherwise returns None

RES
Belt.Option.keep(Some(10), x => x > 5) /* returns `Some(10)` */
Belt.Option.keep(Some(4), x => x > 5) /* returns `None` */
Belt.Option.keep(None, x => x > 5) /* returns `None` */

let keep: (option<'a>, 'a => bool) => option<'a>

forEachU

Uncurried version of forEach

let forEachU: (option<'a>, (. 'a) => unit) => unit

forEach

If optionValue is Some(value), it calls f(value); otherwise returns ()

RES
Belt.Option.forEach(Some("thing"), x => Js.log(x)) /* logs "thing" */
Belt.Option.forEach(None, x => Js.log(x)) /* returns () */

let forEach: (option<'a>, 'a => unit) => unit

getExn

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 */

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

getUnsafe

getUnsafe(x) returns x

This is an unsafe operation, it assumes x is neither None nor Some(None(...)))

let getUnsafe: option<'a> => 'a

mapWithDefaultU

Uncurried version of mapWithDefault

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

mapWithDefault

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 */

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

mapU

Uncurried version of map

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

map

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 */

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

flatMapU

Uncurried version of flatMap

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

flatMap

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 */

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

getWithDefault

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" */

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

orElse

orElse optionalValue otherOptional

If optionalValue is Some value, returns Some value, otherwise otherOptional


orElse (Some 1812) (Some 1066) = Some 1812;;
orElse None (Some 1066) = Some 1066;;
orElse None None = None;;

let orElse: (option<'a>, option<'a>) => option<'a>

isSome

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

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

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

let isSome: option<'a> => bool

isNone

Returns true if the argument is None, false otherwise.

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

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

let isNone: option<'a> => bool

eqU

Uncurried version of eq

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

eq

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 */

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

cmpU

Uncurried version of cmp

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

cmp

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 */

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