API / Core / Null

You are viewing docs for an older version of Rescript.
Go to latest version.

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