True Myth / maybe / first

Function: first()

Call Signature

first<T>(array): Maybe<Just<T>>

Safely get the first item from a list, returning Just the first item if the array has at least one item in it, or Nothing if it is empty.

This produces a Maybe<Maybe<T>> rather than Maybe<T> to distinguish between arrays that include null or undefined and empty arrays.

Examples

import { first } from 'true-myth/maybe';

let empty = [];
first(empty); // => Nothing

let full = [1, 2, 3];
first(full); // => Just(Just(1))

let mixed = [undefined, 1];
first(mixed); // => Just(Nothing)

Type Parameters

T

T extends object

Parameters

array

AnyArray<T>

The array to get the first item from.

Returns

Maybe<Just<T>>

Note

Unfortunately, it is not possible to distinguish between these statically in a single call signature in a reasonable way: we do not want to change the types and runtime result produced by calling this function simply because the input array had its type changed (to include, or not include, null or undefined). Although the types and runtime could be guaranteed to align, correctly doing so would require every item in the array to check whether any items are null or undefined, making the performance linear on the size of the array ($O(n)$) instead of constant time ($O(1)$). This is quite undesirable!

Call Signature

first(array): Maybe<Nothing<{ }>>

Safely get the first item from a list, returning Just the first item if the array has at least one item in it, or Nothing if it is empty.

This produces a Maybe<Maybe<T>> rather than Maybe<T> to distinguish between arrays that include null or undefined and empty arrays.

Examples

import { first } from 'true-myth/maybe';

let empty = [];
first(empty); // => Nothing

let full = [1, 2, 3];
first(full); // => Just(Just(1))

let mixed = [undefined, 1];
first(mixed); // => Just(Nothing)

Parameters

array

AnyArray<undefined | null>

The array to get the first item from.

Returns

Maybe<Nothing<{ }>>

Note

Unfortunately, it is not possible to distinguish between these statically in a single call signature in a reasonable way: we do not want to change the types and runtime result produced by calling this function simply because the input array had its type changed (to include, or not include, null or undefined). Although the types and runtime could be guaranteed to align, correctly doing so would require every item in the array to check whether any items are null or undefined, making the performance linear on the size of the array ($O(n)$) instead of constant time ($O(1)$). This is quite undesirable!

Call Signature

first<T>(array): Maybe<Maybe<T>>

Safely get the first item from a list, returning Just the first item if the array has at least one item in it, or Nothing if it is empty.

This produces a Maybe<Maybe<T>> rather than Maybe<T> to distinguish between arrays that include null or undefined and empty arrays.

Examples

import { first } from 'true-myth/maybe';

let empty = [];
first(empty); // => Nothing

let full = [1, 2, 3];
first(full); // => Just(Just(1))

let mixed = [undefined, 1];
first(mixed); // => Just(Nothing)

Type Parameters

T

T extends object

Parameters

array

AnyArray<undefined | null | T>

The array to get the first item from.

Returns

Maybe<Maybe<T>>

Note

Unfortunately, it is not possible to distinguish between these statically in a single call signature in a reasonable way: we do not want to change the types and runtime result produced by calling this function simply because the input array had its type changed (to include, or not include, null or undefined). Although the types and runtime could be guaranteed to align, correctly doing so would require every item in the array to check whether any items are null or undefined, making the performance linear on the size of the array ($O(n)$) instead of constant time ($O(1)$). This is quite undesirable!