List

data. List

new List()

The List data type. List is implemented as a linked list, where each part has a head and a tail. The end of the list is marked with Nil

Version:
  • 3.0.0
Source:
Example
const {List} = require('futils').data;
const {Cons, Nil} = List;

List.Cons(1, List.Nil());               // -> Cons(1, Nil)
Cons(1, Nil());                         // -> Cons(1, Nil)

List.Cons(1, List.Cons(2, List.Nil())); // -> Cons(1, Cons(2, Nil))
Cons(1, Cons(2, Nil()));                // -> Cons(1, Cons(2, Nil))

Extends

Methods

(static) empty() → {List}

Monoid implementation for List. Returns a List without values

Source:
Returns:
Type:
List

A List

Example
const {List} = require('futils').data;

List.empty(); // -> Nil

(static) from(a) → {List}

Lifts a value into a List. Somewhat similiar to List.of, but only accepts a single value and puts it in a array if it is not an array itself. Useful to transform array-like objects on the fly

Source:
Parameters:
Name Type Description
a any

The value to lift
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

List.from(1);    // -> Cons(1, Nil)
List.from([1]);  // -> Cons(1, Nil)
List.from(null); // -> Nil

(static) fromArray(a) → {List}

A natural transformation from an array into a List

Source:
Parameters:
Name Type Description
a Array

The array to transform
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

List.fromArray([1, 2, 3]); // -> Cons(1, Cons(2, Cons(3, Nil)))

(static) fromEither(a) → {List}

A natural transformation from an Either.Left or Either.Right into a List

Source:
Parameters:
Name Type Description
a Left | Right

The Either to transform
Returns:
Type:
List

List with value(s) for Either.Right, empty List for Either.Left

Example
const {List, Either} = require('futils').data;

const l = Either.Left('a left');
const r = Either.Right('a right');

List.fromEither(l); // -> Nil
List.fromEither(r); // -> Cons('a right', Nil)

(static) fromId(a) → {List}

A natural transformation from an Id to a List

Source:
Parameters:
Name Type Description
a Id

The Id to transform
Returns:
Type:
List

A new List

Example
const {List, Id} = require('futils').data;

const id = Id('a value');

List.fromId(id); // -> Cons('a value', Nil)

(static) fromMaybe(a) → {List}

A natural transformation from a Maybe.Some or Maybe.None into a List

Source:
Parameters:
Name Type Description
a Some | None

The Maybe to transform
Returns:
Type:
List

A List with the value of a Maybe.Some and an empty List for Maybe.None

Example
const {List, Maybe} = require('futils').data;

const some = Maybe.Some('a value');
const none = Maybe.None();

List.fromMaybe(some); // -> Cons('a value', Nil)
List.fromMaybe(none); // -> Nil

(static) of(…a) → {List}

Lifts one or more values into a List

Source:
Parameters:
Name Type Attributes Description
a any <repeatable>

The value or values to lift
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

List.of(1); // -> Cons(1, Nil)

ap(a) → {List}

Applies a function in a List to the values in another List

Source:
Parameters:
Name Type Description
a List

The List that holds the values
Returns:
Type:
List

List which contains the results of applying the function

Example
const {List} = require('futils').data;

const ls = List.of(1);

const mIncDouble = List.of((n) => n + 1).cons((n) => n * 2);

mIncDouble.ap(ls); // -> Cons(4, Nil)

concat(a) → {List}

Concatenates a List with another List

Source:
Parameters:
Name Type Description
a List

The List instance to concatenate with
Returns:
Type:
List

A List containing all values from both Lists

Example
const {List} = require('futils').data;

const ls = List.of(1);

ls.concat(List.of(2)); // -> Cons(1, Cons(2, Nil))

cons(a) → {Cons}

Sets the given value to the head position of a List, making the current List the new tail

Source:
Parameters:
Name Type Description
a any

The value to set
Returns:
Type:
Cons

A new List

Example
const {List} = require('futils').data;

List.of(2).cons(1); // -> Cons(1, Cons(2, Nil));

drop(n) → {Cons|Nil}

If given a number N, drops the first N items from the List

Source:
Parameters:
Name Type Description
n Number

Amount of elements to drop from the beginning of the List
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

List.of(2).cons(1).cons(0).drop(2); // -> Cons(2, Nil)

extend(f) → {List}

If given a function that takes a List and returns a value, returns a List

Source:
Parameters:
Name Type Description
f function

A function taking a List
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

const ls = List.of(3).cons(2).cons(1);

ls.extend(({head, tail}) => head + tail.head || 0); // -> Cons(6, Cons(5, Cons(3, Nil)))

extract() → {any|null}

Extracts the head value from a List. For Nil instances, it returns null

Source:
Returns:
Type:
any | null

The head element

Example
const {List} = require('futils').data;

List.of(1).extract();   // -> 1
List.empty().extract(); // -> null

filter(f) → {Cons|Nil}

Takes a function which returns a Boolean and filters the List with it. Works much like the Array.filter function

Source:
Parameters:
Name Type Description
f function

The function to filter with
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

const even = (n) => n % 2 === 0;

List.of(3).cons(2).cons(1).filter(even); // -> Cons(2, Nil)

find(f) → {any|null}

Given a predicate function, returns the first element for which the predicate returns true. If no element passes the predicate, null is returned

Source:
Parameters:
Name Type Description
f function

The predicate function
Returns:
Type:
any | null

The first match or null

Example
const {List} = require('futils').data;

const even = (n) => n % 2 === 0;

List.of(3).cons(2).cons(1).find(even); // -> 2

flat() → {List}

Flattens a nested List one level

Source:
Returns:
Type:
List

A List flattened

Example
const {List} = require('futils').data;

const ls = List.of(List.of(1));

ls.flat(); // -> Cons(1, Nil)

flatMap(f) → {List}

Maps a List returning function over each value in the List and flattens the result

Source:
Parameters:
Name Type Description
f function

A List returning function to map
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

const ls = List.of(1);

const inc = (n) => List.of(n + 1);

ls.flatMap(inc); // -> Cons(2, Nil)

fold(A) → {Monoid}

Takes a Monoid and folds the List into it

Source:
Parameters:
Name Type Description
A Monoid

The Monoid type constructor
Returns:
Type:
Monoid

A Monoid of the type the function returns

Example
const {List} = require('futils').data;
const {Sum} = require('futils').monoid;

List.of(1).cons(2).fold(Sum); // -> Sum(3)

foldMap(f) → {Monoid}

Takes a function which returns a Monoid and folds the List with it into a Monoid

Source:
Parameters:
Name Type Description
f function

The Monoid returning function
Returns:
Type:
Monoid

A Monoid of the type the function returns

Example
const {List} = require('futils').data;
const {Sum} = require('futils').monoid;

const fn = (n) => Sum.of(n);

List.of(1).cons(2).foldMap(fn); // -> Sum(3)

intersperse(a) → {Cons|Nil}

Takes a value and puts it between each entry in the List

Source:
Parameters:
Name Type Description
a any

The value to put in between
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

List.of(2).cons(1).intersperse(0.5); // -> Cons(1, Cons(0.5, Cons(2, Nil)))

map(f) → {List}

Maps a function over each value in the List

Source:
Parameters:
Name Type Description
f function

The function to map
Returns:
Type:
List

A new List

Example
const {List} = require('futils').data;

const ls = List.of(1);

const inc = (n) => n + 1;

ls.map(inc); // -> Cons(2, Nil)

nub() → {Cons|Nil}

Removes all duplicates from the List. Uses deep equality for comparison

Source:
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

List.of(3).cons(2).cons(2).cons(1).nub(); // -> Cons(1, Cons(2, Cons(3, Nil)))

nubBy(f) → {Cons|Nil}

Given a predicate function, removes all duplicates from the List for which the predicate function returns true

Source:
Parameters:
Name Type Description
f function

The predicate function
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

const eq = (a, b) => a === b;

List.of(3).cons(2).cons(2).cons(1).nubBy(eq); // -> Cons(1, Cons(2, Cons(3, Nil)))

reduce(f, x) → {any}

Works like the Array.reduce method. If given a function and an initial value, reduces the values in the List to a final value

Source:
Parameters:
Name Type Description
f function

The function to reduce with
x any

The seed value to reduce into
Returns:
Type:
any

All values reduced into the seed

Example
const {List} = require('futils').data;

const ls = List.of(1);

const reducer = (a, b) => a + b;

ls.reduce(reducer, 1); // -> 2

reduceRight(f, x) → {any}

Works like the Array.reduceRight method. If given a function and an initial value, reduces the values in the List to a final value

Source:
Parameters:
Name Type Description
f function

The function to reduce with
x any

The seed value to reduce into
Returns:
Type:
any

All values reduced into the seed

Example
const {List} = require('futils').data;

const ls = List.of(1);

const reducer = (a, b) => a + b;

ls.reduceRight(reducer, 1); // -> 2

sequence(A) → {Applicative}

Sequences a List into another applicative Type

Source:
Parameters:
Name Type Description
A Applicative

A constructor with of and ap methods
Returns:
Type:
Applicative

A List wrapped in the applicative

Example
const {List, Maybe} = require('futils').data;

const ls = List.of(Maybe.of(1));

ls.sequence(Maybe); // -> Some(Cons(1, Nil))

snoc(a) → {Cons}

Sets a given value to the tail position of a List

Source:
Parameters:
Name Type Description
a any

The value to set
Returns:
Type:
Cons

A new List

Example
const {List} = require('futils').data;

List.of(1).snoc(2); // -> Cons(1, Cons(2, Nil))

take(n) → {Cons|Nil}

If given a number N, returns the first N items from the List

Source:
Parameters:
Name Type Description
n Number

Amount of elements to take from the beginning of the List
Returns:
Type:
Cons | Nil

A new List

Example
const {List} = require('futils').data;

List.of(2).cons(1).cons(0).take(2); // -> Cons(0, Cons(1, Nil))

toArray() → {Array}

A natural transformation from a List into an array

Source:
Returns:
Type:
Array

Array of values

Example
const {List} = require('futils').data;

List.of(2).cons(1).toArray(); // -> [1, 2]