api.md

TOC

List

1. Creating Lists
   • empty
   • of
   • from
   • times
   • range
   • Builder
   • toBuilder
2. Reading Lists
   • get
   • nth
   • indexOf
   • includes
   • find
   • iterator
   • reverseIterator
   • [Symbol.iterator]
3. Transforming Lists
   • append
   • push
   • appendAll
   • concat
   • prepend
   • unshift
   • drop
   • take
   • update
   • set
   • slice
   • removeAt
   • remove
   • insertAt
   • reduce
   • reduceRight
   • foldl
   • foldr
   • filter
   • map
   • every
   • some
   • sort
   • sortwith
   • intersperse
   • join
   • flatten
   • flatMap
   • chain
   • ap
   • traverse
   • sequence

Builder

1. adding sources
   • append
   • push
   • appendAll
   • concat
   • prepend
   • unshift
2. transforms
   • map
   • filter
   • drop
   • dropWhile
   • take
   • takeWhile
   • groupWith
   • flatMap
   • flatten
   • scan
   • intersperse
   • unique
3. into destinations
   • reduce [to Any]
   • join [to String]
   • toArray [to native Array]
   • toList [to List]
   • every [to Boolean]
   • some [to Boolean]

List API

List.empty

List.empty(): List<any>

returns a new empty List

fantasy-land compatibility for Monoid

Example:

var none = List.empty();
var nada = none.empty();

List.of

List.of<T>(value: T): List<T>

creates a list from values provided

example:

var one = List.of(1)

List.from

List.from(list: Array<T>|List<T>|Iterable<T>): List<T>

creates a list from another collection

example:

var one = List.of(1)

List.range

List.range(start: number, end: number): List<number>

example:

var nums = List.range(0, 5);
//nums == [0,1,2,3,4]

List.times

List.times<T>(n: number, function(i: number): T): List<T>

invokes a callback n times and builds into a List

example:

var nums = List.range(0, 5)
//nums == [0,1,2,3,4]

List.toBuilder

creates a builder from the current list see also: List.Builder to create an empty Builder

List.get

nth<T>(n: number, notFound: any): T|notFound

example

var nums = List.range(0, 5)
var resulta = nums.nth(2);
var resultb = nums.nth(7);
var resultc = nums.nth(7, Maybe.Nothing);
//nums == [0,1,2,3,4]
//resulta = 2
//resultb = undefined
//resultc = Nothing

List.nth

nth<T>(index: number): Maybe<T>

returns the value at the provided index, wrapped in a Maybe.Just if in bounds or a Maybe.Nothing if out of bound

example

var nums = List.range(0, 5)
var maybe_a = nums.nth(2);
var maybe_b = nums.nth(7);
//nums == [0,1,2,3,4]
//maybe_a == Just(2)
//maybe_b == Nothing

List.indexOf

indexOf<T>(value: T): number

List.includes

includes(value: any): boolean

List.find

find<T>(function(value: T): boolean): number

List.iterator

iterator(start: number, end: number): RangedIterator

List.reverseIterator

iterator(start: number, end: number): RangedIterator

List[Symbol.iterator]

returns a iterator for the current collection

List.append

append<T>(value: T): List<T>

List.push

alias for List.append

List.appendAll

appendAll<T>(iterable: Array<T>|List<T>|Iterable<T>): List<T>

List.concat

fantasy-land compatibility for Semigroup alias for List.appendAll

List.prepend

prepend<T>(value: T): List<T>

add an element to the beginning of the list, returning a new list

List.unshift

alias for List.prepend

List.drop

drop(n: number): List

List.take

take(n: number): List

List.update

drop(index: number): List

List.set

alias for List.update

List.slice

slice(from: number, to: number): List

List.removeAt

removeAt(index: number): List

List.remove

removeAt<T>(value: T): List<T>

List.insertAt

insertAt<T>(index: number, value: T): List<T>

List.reduce

reduce<T>(callback: function(accumulator: W, next: T): W, seed: W): List<T>

List.reduceRight

reduceRight<T>(callback: function(accumulator: W, next: T): W, seed: W): List<T>

List.foldl

foldl<T>(callback: function(next: T, accumulator: W): W, seed: W): List<T>

List.foldr

foldr<T>(callback: function(next: T, accumulator: W): W, seed: W): List<T>

List.filter

filter<T>(callback: function(value: T):Boolean): List<T>

List.map

map<T>(callback: function(value: T): W): List<W>

List.every

every(callback: function(value: T):Boolean): Boolean

List.some

some(callback: function(value: T):Boolean): Boolean

List.sortWith

sortWith<T>(function(a: T, b: T): number): List<T>

sorts the list using a provided comparison function

the callback should return one of : 0 : if items are equal 1 : if a is greater than b -1: if b is greater than a

List.sort

sort(): List

sort and return a new list using a Natural sort order

List.intersperse

intersperse<T>(separator: T): List<T>

List.join

join(separator: string): string

List.flatten

flatten(): List

List.flatMap

flatMap<T|Array>(callback: function(value: T): W): List<W>

List.chain

fantasy-land compatibility for Chain alias for List.flatMap

List.ap

fantasy-land compatibility for Applicative

List.traverse

fantasy-land compatibility for Traversible

List.sequence

fantasy-land compatibility for Traversible

List.Builder

create a new empty Builder

Builder

Builders offer faster batched iteration and transformations over multiple collections (like an iterator of iterators) with a fluent API.

Builder.appendAll

appendAll<T>(list: Array<T>): Builder<T>

add a collection to the source list. Sources are lazily iterated over when builder exectutes a "terminating" statement. Any collection type can be used including:

• native Arrays
• Lists
• LinkedLists (an internal type)
• Iterators

Example:

var result = List.Builder()
	.appendAll(myArray)
	.appendAll(myList)
	.appendAll(myIterable)
	.toList()

Builder.concat

alias for appendAll()

Builder.append

append<T>(value: T): Builder<T>

add a single item to the sources list.

Example:

var result = List.Builder()
	.append(1)
	.append(2)
	.append(3)
	.toList()
// result == [1,2,3]

Builder.push

alias for append()

Builder.prepend

prepend<T>(value: T): Builder<T>

add a single item to the beginning of sources list.

Example:

var result = List.Builder()
	.prepend(3)
	.prepend(2)
	.prepend(1)
	.toList()
// result == [1,2,3]

Builder.unshift

alias for prepend()

Builder.map

map<T>(callback: function(value:T): W): Builder<W>

calls a provided callback function once for each element in an sources, in order, and returns a new replacement element.

Example:

const plusOne = (x) => x + 1

var result = List.Builder()
	.appendAll([1,2,3])
	.map(plusOne)
	.toList()
// result == [2,3,4]

Builder.filter

filter<T>(callback: function(value:T): Boolean): Builder<T>

calls the provided callback function once for each element in the sources, in order, and keeps the element if callback returns true

Builder.drop

drop(n: number): Builder

accepts a provided number, removing the first n elements from the sources, leaving the remaining

Builder.dropWhile

dropWhile(callback: function(value:T): Boolean): Builder

accepts a provided callback, removing elements until the callback returns true, leaving the remaining elements untouched

Builder.take

take(n: number): Builder

accepts a provided number, removing the first n elements from the sources, leaving the remaining

Builder.takeWhile

takeWhile(callback: function(value:T): Boolean): Builder

accepts a provided callback, keeping elements until the callback returns false, leaving the remaining elements untouched

Builder.flatten

flatten(): Builder

merges all elements recursively, if they are an Array, List or Iterable, into a single list

var result = List.Builder()
	.appendAll([[1,2,3], [4,5,6], [7,8,9]])
	.flatten()
	.toList()
// result == [1,2,3,4,5,6,7,8,9]

Builder.flatMap

map<T|Array>(callback: function(value:T): W): Builder<W>

transform each element or sub-element(if iterable), then merges into resulting list

const plusOne = (x) => x + 1

var result = List.Builder()
	.appendAll([[1,2,3], [4,5,6], [7,8,9]])
	.flatMap(plusOne)
	.toList()
// result == [2,3,4,5,6,7,8,9,10]

Builder.intersperse

intersperse(value: any): Builder

Accepts a single argument an inserts it between every element in the array. Will not insert as first or last item

var result = List.Builder()
	.appendAll([1,2,3])
	.intersperse("-")
	.toList()
// result == [1, "-", 2, "-", 3]

Builder.unique

unique(): Builder

ensures all elements only occur once in the result

var result = List.Builder()
	.appendAll([1,2,3,1,2,3,3,3])
	.unique()
	.toList()
// result == [1, 2, 3]

Builder.scan

scan<T>(callback: function(accumulator: W, next: T): W, seed: W): Builder<W>

Accepts an callback function and an optionally seed value. incrementally reduces each element in order. non-terminal (i.e. does not produce the final builder result)

Builder.reduce

reduce<T>(callback: function(accumulator: W, next: T): W, seed: W): W

Accepts a reducer callback and an option seed value. Terminal. Returns the result of the builder run through the callback.

Builder.join

join(separator: string): string

Returns the result of the builder as a native Array. Accepts an optional separator. Terminal.

Builder.toArray

toArray<T>(): Array<T>

Returns the result of the builder as an native Array. Accepts no input arguments. Terminal

Builder.toList

toList<T>(): List<T>

Returns the result of the builder as an immutable List. Accepts no input arguments. Terminal

Builder.every

every<T>(callback: function(value:T): Boolean): Boolean

Accepts a callback function, returning a boolean if all elements pass Terminal.

Builder.some

some<T>(callback: function(value:T): Boolean): Boolean

Accepts a callback function, returning a boolean if any elements pass. Terminal