Null

Functions for handling values that could be null.

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

t

RESCRIPT

@unboxed
type t<'a> = null<'a> =
  | Value('a)
  | @as(null) Null

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

asNullable

RESCRIPT

let asNullable: t<'a> => 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

equal(a, b, eq) checks if a and b are equal. If both are Null.Value, it will use function eq to check if the values are equal.

Examples

RESCRIPT
let a = Null.Value(1)
let b = Null.null
let c = Null.Value(2)

Null.equal(a, b, Int.equal) == false
Null.equal(a, c, Int.equal) == false
Null.equal(Null.null, Null.null, Int.equal) == true

compare

RESCRIPT

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

compare(a, b, cmp) compares a and b. If both are Null.Value, it will use function cmp to compare the values.

Examples

RESCRIPT
let a = Null.Value(1)
let b = Null.null
let c = Null.Value(2)

// A value is greater than null
Null.compare(a, b, Int.compare) == Ordering.greater
// A value is less than null
Null.compare(b, a, Int.compare) == Ordering.less
// A null is equal to null
Null.compare(Null.null, Null.null, Int.compare) == Ordering.equal
// The compare function is used if both are `Null.Value`
Null.compare(a, c, Int.compare) == Ordering.less

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

RESCRIPT

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

getExn

Deprecated

RESCRIPT

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

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

RESCRIPT
Null.getExn(Null.make(3)) == 3

switch Null.getExn(%raw("'ReScript'")) {
| exception Invalid_argument(_) => assert(false)
| value => value == "ReScript"
}

switch Null.getExn(%raw("null")) {
| exception Invalid_argument(_) => assert(true)
| _ => assert(false)
}

Exceptions

Throws Invalid_argument if value is null

getOrThrow

RESCRIPT

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

getOrThrow(value) throws an exception if null, otherwise returns the value.

RESCRIPT
Null.getOrThrow(Null.make(3)) == 3

switch Null.getOrThrow(%raw("'ReScript'")) {
| exception Invalid_argument(_) => assert(false)
| value => value == "ReScript"
}

switch Null.getOrThrow(%raw("null")) {
| exception Invalid_argument(_) => assert(true)
| _ => assert(false)
}

Exceptions

Throws 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) // Throws 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

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

ignore

RESCRIPT

let ignore: t<'a> => unit

ignore(null) ignores the provided null 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.