Nullable
Functions for handling nullable values.
Primarily useful when interoping with JavaScript when you don't know whether you'll get a value, null
or undefined
.
t
type t<'a> = Js.Nullable.t<'a> =
| Value('a)
| Null
| Undefined
Type representing a nullable value.
A nullable value can be the value 'a
, null
or undefined
.
null
let null: t<'a>
The value null
.
See null
on MDN.
Examples
RESCRIPTConsole.log(Nullable.null) // Logs `null` to the console.
undefined
let undefined: t<'a>
The value undefined
.
See undefined
on MDN.
Examples
RESCRIPTConsole.log(undefined) // Logs `undefined` to the console.
make
let make: 'a => t<'a>
Creates a new nullable value from the provided value. This means the compiler will enforce null checks for the new value.
Examples
RESCRIPTlet myStr = "Hello"
let asNullable = myStr->Nullable.make
// Can't do the below because we're now forced to check for nullability
// myStr == asNullable
// Need to do this
switch asNullable->Nullable.toOption {
| Some(value) if value == myStr => Console.log("Yay, values matched!")
| _ => Console.log("Values did not match.")
}
equal
let equal: (t<'a>, t<'b>, ('a, 'b) => bool) => bool
compare
let compare: (
t<'a>,
t<'b>,
('a, 'b) => Core__Ordering.t,
) => Core__Ordering.t
toOption
let toOption: t<'a> => option<'a>
Converts a nullable value into an option, so it can be pattern matched on.
Will convert both null
and undefined
to None
, and a present value to Some(value)
.
Examples
RESCRIPTlet nullableString = Nullable.make("Hello")
switch nullableString->Nullable.toOption {
| Some(str) => Console.log2("Got string:", str)
| None => Console.log("Didn't have a value.")
}
fromOption
let fromOption: option<'a> => t<'a>
Turns an option
into a Nullable.t
.
Examples
RESCRIPTlet optString = Some("Hello")
let asNullable = optString->Nullable.fromOption // Nullable.t<string>
getOr
let getOr: (t<'a>, 'a) => 'a
getOr(value, default)
returns value
if not null
or undefined
,
otherwise return default
.
Examples
RESCRIPTNullable.getOr(Nullable.null, "Banana") // Banana
Nullable.getOr(Nullable.make("Apple"), "Banana") // Apple
let greet = (firstName: option<string>) =>
"Greetings " ++ firstName->Option.getOr("Anonymous")
Nullable.make("Jane")->Nullable.toOption->greet // "Greetings Jane"
Nullable.null->Nullable.toOption->greet // "Greetings Anonymous"
getWithDefault
Deprecated
Use getOr instead
let getWithDefault: (t<'a>, 'a) => 'a
getExn
let getExn: t<'a> => 'a
getExn(value)
raises an exception if null
or undefined
, otherwise returns the value.
RESCRIPTNullable.getExn(Nullable.make(3)) // 3
Nullable.getExn(Nullable.null) /* Raises an Error */
Exceptions
Raises
Invalid_argument
ifvalue
isnull
orundefined
getUnsafe
let getUnsafe: t<'a> => 'a
getUnsafe(value)
returns value
.
Examples
RESCRIPTNullable.getUnsafe(Nullable.make(3)) == 3
Nullable.getUnsafe(Nullable.null) // Raises an error
Important
This is an unsafe operation, it assumes
value
is notnull
orundefined
.
forEach
let forEach: (t<'a>, 'a => unit) => unit
forEach(value, f)
call f
on value
. if value
is not null
or undefined
,
then if calls f
, otherwise returns unit
.
Examples
RESCRIPTNullable.forEach(Nullable.make("thing"), x => Console.log(x)) // logs "thing"
Nullable.forEach(Nullable.null, x => Console.log(x)) // returns ()
Nullable.forEach(undefined, x => Console.log(x)) // returns ()
map
let map: (t<'a>, 'a => 'b) => t<'b>
map(value, f)
returns f(value)
if value
is not null
or undefined
,
otherwise returns value
unchanged.
Examples
RESCRIPTNullable.map(Nullable.make(3), x => x * x) // Nullable.make(9)
Nullable.map(undefined, x => x * x) // undefined
mapOr
let mapOr: (t<'a>, 'b, 'a => 'b) => 'b
mapOr(value, default, f)
returns f(value)
if value
is not null
or undefined
, otherwise returns default
.
Examples
RESCRIPTlet someValue = Nullable.make(3)
someValue->Nullable.mapOr(0, x => x + 5) // 8
let noneValue = Nullable.null
noneValue->Nullable.mapOr(0, x => x + 5) // 0
mapWithDefault
Deprecated
Use mapOr instead
let mapWithDefault: (t<'a>, 'b, 'a => 'b) => 'b
flatMap
let flatMap: (t<'a>, 'a => t<'b>) => t<'b>
flatMap(value, f)
returns f(value)
if value
is not null
or undefined
,
otherwise returns value
unchanged.
Examples
RESCRIPTlet addIfAboveOne = value =>
if (value > 1) {
Nullable.make(value + 1)
} else {
Nullable.null
}
Nullable.flatMap(Nullable.make(2), addIfAboveOne) // Nullable.make(3)
Nullable.flatMap(Nullable.make(-4), addIfAboveOne) // undefined
Nullable.flatMap(Nullable.null, addIfAboveOne) // undefined