Docs / API / Stdlib / Option

Option

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, we provide utility-functions for it.

The option type is a part of the ReScript standard library which is defined like this:

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

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

t

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

Type representing an option of type 'a.

filter

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

filter(opt, f) applies f to opt, if f returns true, then it returns Some(value), otherwise returns None.

Examples

RESCRIPT
Option.filter(Some(10), x => x > 5) // Some(10)
Option.filter(Some(4), x => x > 5) // None
Option.filter(None, x => x > 5) // None

forEach

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

forEach(opt, f) call f on opt. if opt is Some(value), then if calls f, otherwise returns unit.

Examples

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

getExn

Deprecated

RESCRIPT
let getExn: (option<'a>, ~message: string=?) => 'a

getExn(opt, ~message=?) returns value if opt is Some(value), otherwise throws an exception with the message provided, or a generic message if no message was provided.

RESCRIPT
Option.getExn(Some(3)) == 3

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

switch Option.getExn(None, ~message="was None!") {
| exception _ => assert(true) // Throws a JsError with the message "was None!"
| _ => assert(false)
}

Exceptions

  • Throws an error if opt is None

getOrThrow

RESCRIPT
let getOrThrow: (option<'a>, ~message: string=?) => 'a

getOrThrow(opt, ~message=?) returns value if opt is Some(value), otherwise throws an exception with the message provided, or a generic message if no message was provided.

RESCRIPT
Option.getOrThrow(Some(3)) == 3

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

switch Option.getOrThrow(None, ~message="was None!") {
| exception _ => assert(true) // Throws a JsError with the message "was None!"
| _ => assert(false)
}

Exceptions

  • Throws an error if opt is None

getUnsafe

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

getUnsafe(opt) returns value if opt is Some(value), otherwise undefined.

Examples

RESCRIPT
Option.getUnsafe(Some(3)) == 3
Option.getUnsafe((None: option<int>)) // Returns `undefined`, which is not a valid `int`

Notes

  • This is an unsafe operation. It assumes value is not None, and may cause undefined behaviour if it is.

mapOr

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

mapOr(opt, default, f) returns f(value) if opt is Some(value), otherwise default.

Examples

RESCRIPT
let someValue = Some(3)
someValue->Option.mapOr(0, x => x + 5) // 8

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

mapWithDefault

Deprecated

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

map

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

map(opt, f) returns Some(f(value)) if opt is Some(value), otherwise None.

Examples

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

flatMap

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

flatMap(opt, f) returns f(value) if opt is Some(value), otherwise None.

Examples

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

Option.flatMap(Some(2), addIfAboveOne) // Some(3)
Option.flatMap(Some(-4), addIfAboveOne) // None
Option.flatMap(None, addIfAboveOne) // None

getOr

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

getOr(opt, default) returns value if opt is Some(value), otherwise default.

Examples

RESCRIPT
Option.getOr(None, "Banana") // Banana
Option.getOr(Some("Apple"), "Banana") // Apple

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

Some("Jane")->greet // "Greetings Jane"
None->greet // "Greetings Anonymous"

getWithDefault

Deprecated

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

orElse

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

orElse(opt1, opt2) returns opt2 if opt1 is None, otherwise opt1.

Examples

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

isSome

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

isSome(opt) returns true if opt is Some(value), otherwise returns false.

Examples

RESCRIPT
Option.isSome(None) // false
Option.isSome(Some(1)) // true

isNone

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

isNone(opt) returns true if opt is None, false otherwise.

Examples

RESCRIPT
Option.isNone(None) // true
Option.isNone(Some(1)) // false

equal

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

equal(opt1, opt2, f) evaluates two optional values for equality with respect to a predicate function f. If both opt1 and opt2 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 f(value1, value2), the predicate function f must return a bool.

Examples

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

open Option

equal(Some(3), Some(15), clockEqual) // true
equal(Some(3), None, clockEqual) // false
equal(None, Some(3), clockEqual) // false
equal(None, None, clockEqual) // true

compare

RESCRIPT
let compare: ( option<'a>, option<'b>, ('a, 'b) => Ordering.t, ) => Ordering.t

compare(opt1, opt2, f) compares two optional values with respect to given f.

If both opt1 and opt2 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 f(value1, value2), f 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) => Int.compare(mod(a, 12), mod(b, 12))

Option.compare(Some(3), Some(15), clockCompare) // 0.
Option.compare(Some(3), Some(14), clockCompare) // 1.
Option.compare(Some(2), Some(15), clockCompare) // (-1.)
Option.compare(None, Some(15), clockCompare) // (-1.)
Option.compare(Some(14), None, clockCompare) // 1.
Option.compare(None, None, clockCompare) // 0.

all

RESCRIPT
let all: array<option<'a>> => option<array<'a>>

all(options) returns an option of array if all options are Some, otherwise returns None.

Examples

RESCRIPT
Option.all([Some(1), Some(2), Some(3)]) // Some([1, 2, 3])
Option.all([Some(1), None]) // None

all2

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

all2((o1, o2)). Like all(), but with a fixed size tuple of 2

all3

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

all3((o1, o2, o3)). Like all(), but with a fixed size tuple of 3

all4

RESCRIPT
let all4: ( (option<'a>, option<'b>, option<'c>, option<'d>), ) => option<('a, 'b, 'c, 'd)>

all4((o1, o2, o3, o4)). Like all(), but with a fixed size tuple of 4

all5

RESCRIPT
let all5: ( ( option<'a>, option<'b>, option<'c>, option<'d>, option<'e>, ), ) => option<('a, 'b, 'c, 'd, 'e)>

all5((o1, o2, o3, o4, o5)). Like all(), but with a fixed size tuple of 5

all6

RESCRIPT
let all6: ( ( option<'a>, option<'b>, option<'c>, option<'d>, option<'e>, option<'f>, ), ) => option<('a, 'b, 'c, 'd, 'e, 'f)>

all6((o1, o2, o3, o4, o5, o6)). Like all(), but with a fixed size tuple of 6

ignore

RESCRIPT
let ignore: option<'a> => unit

ignore(option) ignores the provided option and returns unit.

This helper is useful when you want to discard a value (for example, the result of an operation with side effects) without having to store or process it further.