API / Core / 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")

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

RESCRIPT

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

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

RESCRIPT
Option.getExn(Some(3)) // 3
Option.getExn(None) /* Raises an Error */
Option.getExn(None, ~message="was None!") /* Raises an Error with the message "was None!" */

Exceptions

Raises 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

Use mapOr instead

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

Use getOr instead

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) => Core__Ordering.t,
) => Core__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.