Docs / API / Belt / Option

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:

Examples

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

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

keepU

Deprecated

Use keep instead

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

Uncurried version of keep

keep

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

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

Examples

RESCRIPT
Belt.Option.keep(Some(10), x => x > 5) == Some(10)
Belt.Option.keep(Some(4), x => x > 5) == None
Belt.Option.keep(None, x => x > 5) == None

forEachU

Deprecated

Use forEach instead

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

Uncurried version of forEach

forEach

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

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

Examples

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

getExn

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

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

Examples

RESCRIPT
Some(3)->Belt.Option.getExn == 3

switch Belt.Option.getExn(None) {
// Throws an exception
| exception _ => assert(true)
| _ => assert(false)
}

getOrThrow

RESCRIPT
let getOrThrow: option<'a> => 'a

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

Examples

RESCRIPT
Some(3)->Belt.Option.getOrThrow == 3

switch Belt.Option.getOrThrow(None) {
// Throws an exception
| exception _ => assert(true)
| _ => assert(false)
}

getUnsafe

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

getUnsafe(x) returns x

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

mapWithDefaultU

Deprecated

Use mapWithDefault instead

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

Uncurried version of mapWithDefault

mapWithDefault

RESCRIPT
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.

Examples

RESCRIPT
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

mapU

Deprecated

Use map instead

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

Uncurried version of map

map

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

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

Examples

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

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

flatMapU

Deprecated

Use flatMap instead

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

Uncurried version of flatMap

flatMap

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

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

Examples

RESCRIPT
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

getWithDefault

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

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

Examples

RESCRIPT
Belt.Option.getWithDefault(None, "Banana") == "Banana"

Belt.Option.getWithDefault(Some("Apple"), "Banana") == "Apple"

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

Some("Jane")->greet == "Greetings Jane"

None->greet == "Greetings Anonymous"

orElse

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

orElse(optionalValue, otherOptional) if optionalValue is Some(value), returns Some(value), otherwise otherOptional

Examples

RESCRIPT
Belt.Option.orElse(Some(1812), Some(1066)) == Some(1812)
Belt.Option.orElse(None, Some(1066)) == Some(1066)
Belt.Option.orElse(None, None) == None

isSome

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

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

Examples

RESCRIPT
Belt.Option.isSome(None) == false

Belt.Option.isSome(Some(1)) == true

isNone

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

Returns true if the argument is None, false otherwise.

Examples

RESCRIPT
Belt.Option.isNone(None) == true

Belt.Option.isNone(Some(1)) == false

eqU

Deprecated

Use eq instead

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

Uncurried version of eq

eq

RESCRIPT
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.

Examples

RESCRIPT
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

cmpU

Deprecated

Use cmp instead

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

Uncurried version of cmp

cmp

RESCRIPT
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.

Examples

RESCRIPT
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