API / Core / Null

Null

Functions for handling values that could be null.

If you also need to cover undefined, check out Nullable instead.

t

RESCRIPT

type t<'a> = Js.Null.t<'a> = Value('a) | Null

A type representing a value that can be either 'a or null.

asNullable

RESCRIPT

let asNullable: t<'a> => Core__Nullable.t<'a>

Converts a Null.t into a Nullable.t.

Examples

RESCRIPT
let nullValue = Null.make("Hello")
let asNullable = nullValue->Null.asNullable // Nullable.t<string>

null

RESCRIPT

let null: t<'a>

The value null.

See null on MDN.

Examples

RESCRIPT
Console.log(null) // Logs `null` to the console.

make

RESCRIPT

let make: 'a => t<'a>

Creates a new Null.t from the provided value. This means the compiler will enforce null checks for the new value.

Examples

RESCRIPT
let myStr = "Hello"
let asNullValue = myStr->Null.make // The compiler now thinks this can be `string` or `null`.

equal

RESCRIPT

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

compare

RESCRIPT

let compare: (
  t<'a>,
  t<'b>,
  ('a, 'b) => Core__Ordering.t,
) => Core__Ordering.t

toOption

RESCRIPT

let toOption: t<'a> => option<'a>

Converts a nullable value into an option, so it can be pattern matched on. Will convert null to None, and a present value to Some(value).

Examples

RESCRIPT
let nullStr = Null.make("Hello")

switch nullStr->Null.toOption {
| Some(str) => Console.log2("Got string:", str)
| None => Console.log("Didn't have a value.")
}

fromOption

RESCRIPT

let fromOption: option<'a> => t<'a>

Turns an option into a Null.t. None will be converted to null.

Examples

RESCRIPT
let optString: option<string> = None
let asNull = optString->Null.fromOption // Null.t<string>
Console.log(asNull == Null.null) // Logs `true` to the console.

getOr

RESCRIPT

let getOr: (t<'a>, 'a) => 'a

getOr(value, default) returns value if not null, otherwise return default.

Examples

RESCRIPT
Null.getOr(Null.null, "Banana") // Banana
Null.getOr(Null.make("Apple"), "Banana") // Apple

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

Null.make("Jane")->Null.toOption->greet // "Greetings Jane"
Null.null->Null.toOption->greet // "Greetings Anonymous"

getWithDefault

Deprecated

Use getOr instead

RESCRIPT

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

getExn

RESCRIPT

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

getExn(value) raises an exception if null, otherwise returns the value.

RESCRIPT
Null.getExn(Null.make(3)) // 3
Null.getExn(Null.null) /* Raises an Error */

Exceptions

Raises Invalid_argument if value is null,

getUnsafe

RESCRIPT

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

getUnsafe(value) returns value.

Examples

RESCRIPT
Null.getUnsafe(Null.make(3)) == 3
Null.getUnsafe(Null.null) // Raises an error

Important

This is an unsafe operation, it assumes value is not null.

forEach

RESCRIPT

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

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

Examples

RESCRIPT
Null.forEach(Null.make("thing"), x => Console.log(x)) // logs "thing"
Null.forEach(Null.null, x => Console.log(x)) // logs nothing

map

RESCRIPT

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

map(value, f) returns f(value) if value is not null, otherwise returns value unchanged.

Examples

RESCRIPT
Null.map(Null.make(3), x => x * x) // Null.make(9)
Null.map(Null.null, x => x * x) // null

mapOr

RESCRIPT

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

mapOr(value, default, f) returns f(value) if value is not null, otherwise returns default.

Examples

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

let noneValue = Null.null
noneValue->Null.mapOr(0, x => x + 5) // 0

mapWithDefault

Deprecated

Use mapOr instead

RESCRIPT

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

flatMap

RESCRIPT

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

flatMap(value, f) returns f(value) if value is not null, otherwise returns value unchanged.

Examples

RESCRIPT
let addIfAboveOne = value =>
  if (value > 1) {
    Null.make(value + 1)
  } else {
    Null.null
  }

Null.flatMap(Null.make(2), addIfAboveOne) // Null.make(3)
Null.flatMap(Null.make(-4), addIfAboveOne) // null
Null.flatMap(Null.null, addIfAboveOne) // null