fj.data
Class List<A>

java.lang.Object
  fj.data.List<A>

public abstract class List<A>
extends Object

Provides an in-memory, immutable, singly linked list.

Version:

2.7

• $LastChangedRevision$
• $LastChangedDate$

Nested Class Summary

static class

List.Buffer<A> A mutable, singly linked list.

Method Summary

List<A>	append(List<A> as) Appends the given list to this list.
<B> List<B>	apply(List<F<A,B>> lf) Performs function application within a list (applicative functor pattern).
static String	asString(List<Character> cs) Returns a string from the given list of characters.
static <A,B> F<F<A,List<B>>,F<List<A>,List<B>>>	bind_()
<B> List<B>	bind(F<A,List<B>> f) Binds the given function across each element of this list with a final join.
<B,C> List<C>	bind(List<B> lb, F<A,F<B,C>> f) Binds the given function across each element of this list and the given list with a final join.
<B,C,D> List<D>	bind(List<B> lb, List<C> lc, F<A,F<B,F<C,D>>> f) Binds the given function across each element of this list and the given lists with a final join.
<B,C,D,E> List<E>	bind(List<B> lb, List<C> lc, List<D> ld, F<A,F<B,F<C,F<D,E>>>> f) Binds the given function across each element of this list and the given lists with a final join.
<B,C,D,E,F$> List<F$>	bind(List<B> lb, List<C> lc, List<D> ld, List<E> le, F<A,F<B,F<C,F<D,F<E,F$>>>>> f) Binds the given function across each element of this list and the given lists with a final join.
<B,C,D,E,F$,G> List<G>	bind(List<B> lb, List<C> lc, List<D> ld, List<E> le, List<F$> lf, F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f) Binds the given function across each element of this list and the given lists with a final join.
<B,C,D,E,F$,G,H> List<H>	bind(List<B> lb, List<C> lc, List<D> ld, List<E> le, List<F$> lf, List<G> lg, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f) Binds the given function across each element of this list and the given lists with a final join.
<B,C,D,E,F$,G,H,I> List<I>	bind(List<B> lb, List<C> lc, List<D> ld, List<E> le, List<F$> lf, List<G> lg, List<H> lh, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f) Binds the given function across each element of this list and the given lists with a final join.
static <A> F<A,F<List<A>,List<A>>>	cons() Returns a function that prepends (cons) an element to a list to produce a new list.
List<A>	cons(A a) Prepends (cons) the given element to this list to product a new list.
static <A> List<A>	cons(A head, List<A> tail) Prepends the given head element to the given tail element to produce a new list.
List<A>	drop(int i) Drops the given number of elements from the head of this list if they are available.
List<A>	dropWhile(F<A,Boolean> f) Removes elements from the head of this list that do not match the given predicate function until an element is found that does match or the list is exhausted.
boolean	exists(F<A,Boolean> f) Returns true if the predicate holds for at least one of the elements of this list, false otherwise (false for the empty list).
List<A>	filter(F<A,Boolean> f) Filters elements from this list by returning only elements which produce true when the given function is applied to them.
Option<A>	find(F<A,Boolean> f) Finds the first occurrence of an element that matches the given predicate or no value if no elements match.
<B> B	foldLeft(F<B,F<A,B>> f, B b) Performs a left-fold reduction across this list.
<B> B	foldRight(F<A,F<B,B>> f, B b) Performs a right-fold reduction across this list.
boolean	forall(F<A,Boolean> f) Returns true if the predicate holds for all of the elements of this list, false otherwise (true for the empty list).
void	foreach(Effect<A> f) Performs a side-effect for each element of this list.
Unit	foreach(F<A,Unit> f) Performs a side-effect for each element of this list.
static List<Character>	fromString(String s) Returns a list of characters from the given string.
abstract A	head() The first element of the linked list or fails for the empty list.
A	index(int i) Returns the element at the given index if it exists, fails otherwise.
List<A>	intersperse(A a) Intersperses the given argument between each element of this list.
static <A> F<List<A>,Boolean>	isEmpty_() Returns a function that determines whether a given list is empty.
boolean	isEmpty() Returns true if this list is empty, false otherwise.
static <A> F<List<A>,Boolean>	isNotEmpty_() Returns a function that determines whether a given list is not empty.
boolean	isNotEmpty() Returns false if this list is empty, true otherwise.
static <A> List<A>	iterateWhile(F<A,A> f, F<A,Boolean> p, A a) Creates a list where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.
static <A> List<A>	join(List<List<A>> o) Joins the given list of lists using a bind operation.
int	length() The length of this list.
static <A> List<A>	list(A... as) Constructs a list from the given elements.
<B> B	list(B nil, F<A,F<List<A>,B>> cons) Performs a reduction on this list using the given arguments.
static <A,B> F<F<A,B>,F<List<A>,List<B>>>	map_()
<B> List<B>	map(F<A,B> f) Maps the given function across this list.
static <A> List<A>	nil() Returns an empty list.
A	orHead(P1<A> a) Returns the head of this list if there is one or the given argument if this list is empty.
List<A>	orTail(P1<List<A>> as) Returns the tail of this list if there is one or the given argument if this list is empty.
static List<Integer>	range(int from, int to) Returns a list of integers from the given from value (inclusive) to the given to value (exclusive).
static <A> List<A>	replicate(int n, A a) Returns a list of the given value replicated the given number of times.
List<A>	reverse() Reverse this list in constant stack space.
<B> List<B>	sequence(List<B> bs) Performs a bind across each list element, but ignores the element value each time.
static <A> List<A>	single(A a) Returns a list of one element containing the given value.
List<A>	snoc(A a) Appends (snoc) the given element to this list to produce a new list.
List<A>	sort(Ord<A> o) Sorts this list using the given order over elements using a merge sort algorithm.
P2<List<A>,List<A>>	splitAt(int i) Splits this list into two lists at the given index.
abstract List<A>	tail() The list without the first element or fails for the empty list.
List<A>	take(int i) Takes the given number of elements from the head of this list if they are available.
List<A>	takeWhile(F<A,Boolean> f) Returns the first elements of the head of this list that match the given predicate function.
Array<A>	toArray() Returns a array projection of this list.
<X> Either<X,A>	toEither(P1<X> x) Returns an either projection of this list; the given argument in Left if empty, or the first element in Right.
Option<A>	toOption() Returns an option projection of this list; None if empty, or the first element in Some.
Stream<A>	toStream() Returns a stream projection of this list.
static <A,B> List<A>	unfold(F<B,Option<P2<A,B>>> f, B b) Unfolds across the given function starting at the given value to produce a list.
<B> List<P2<A,B>>	zip(List<B> bs) Zips this list with the given list to produce a list of pairs.
List<P2<A,Integer>>	zipIndex() Zips this list with the index of its element as a pair.
<B,C> List<C>	zipWith(List<B> bs, F<A,F<B,C>> f) Zips this list with the given list using the given function to produce a new list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

head

public abstract A head()

The first element of the linked list or fails for the empty list.

Returns:

The first element of the linked list or fails for the empty list.

tail

public abstract List<A> tail()

The list without the first element or fails for the empty list.

Returns:

The list without the first element or fails for the empty list.

length

public int length()

The length of this list.

Returns:

The length of this list.

isEmpty

public boolean isEmpty()

Returns true if this list is empty, false otherwise.

Returns:

true if this list is empty, false otherwise.

isNotEmpty

public boolean isNotEmpty()

Returns false if this list is empty, true otherwise.

Returns:

false if this list is empty, true otherwise.

list

public <B> B list(B nil,
                  F<A,F<List<A>,B>> cons)

Performs a reduction on this list using the given arguments.

Parameters:

nil - The value to return if this list is empty.

cons - The function to apply to the head and tail of this list if it is not empty.

Returns:

A reduction on this list.

orHead

public A orHead(P1<A> a)

Returns the head of this list if there is one or the given argument if this list is empty.

Parameters:

a - The argument to return if this list is empty.

Returns:

The head of this list if there is one or the given argument if this list is empty.

orTail

public List<A> orTail(P1<List<A>> as)

Returns the tail of this list if there is one or the given argument if this list is empty.

Parameters:

as - The argument to return if this list is empty.

Returns:

The tail of this list if there is one or the given argument if this list is empty.

toOption

public Option<A> toOption()

Returns an option projection of this list; None if empty, or the first element in Some.

Returns:

An option projection of this list.

toEither

public <X> Either<X,A> toEither(P1<X> x)

Returns an either projection of this list; the given argument in Left if empty, or the first element in Right.

Parameters:

x - The value to return in left if this list is empty.

Returns:

An either projection of this list.

toStream

public Stream<A> toStream()

Returns a stream projection of this list.

Returns:

A stream projection of this list.

toArray

public Array<A> toArray()

Returns a array projection of this list.

Returns:

A array projection of this list.

cons

public List<A> cons(A a)

Prepends (cons) the given element to this list to product a new list.

Parameters:

a - The element to prepend.

Returns:

A new list with the given element at the head.

map

public <B> List<B> map(F<A,B> f)

Maps the given function across this list.

Parameters:

f - The function to map across this list.

Returns:

A new list after the given function has been applied to each element.

foreach

public Unit foreach(F<A,Unit> f)

Performs a side-effect for each element of this list.

Parameters:

f - The side-effect to perform for the given element.

Returns:

The unit value.

foreach

public void foreach(Effect<A> f)

Performs a side-effect for each element of this list.

Parameters:

f - The side-effect to perform for the given element.

filter

public List<A> filter(F<A,Boolean> f)

Filters elements from this list by returning only elements which produce true when the given function is applied to them.

Parameters:

f - The predicate function to filter on.

Returns:

A new list whose elements all match the given predicate.

takeWhile

public List<A> takeWhile(F<A,Boolean> f)

Returns the first elements of the head of this list that match the given predicate function.

Parameters:

f - The predicate function to apply on this list until it finds an element that does not hold, or the list is exhausted.

Returns:

The first elements of the head of this list that match the given predicate function.

dropWhile

public List<A> dropWhile(F<A,Boolean> f)

Removes elements from the head of this list that do not match the given predicate function until an element is found that does match or the list is exhausted.

Parameters:

f - The predicate function to apply through this list.

Returns:

The list whose first element does not match the given predicate function.

bind

public <B> List<B> bind(F<A,List<B>> f)

Binds the given function across each element of this list with a final join.

Parameters:

f - The function to apply to each element of this list.

Returns:

A new list after performing the map, then final join.

bind

public <B,C> List<C> bind(List<B> lb,
                          F<A,F<B,C>> f)

Binds the given function across each element of this list and the given list with a final join.

Parameters:

lb - A given list to bind the given function with.

f - The function to apply to each element of this list and the given list.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D> List<D> bind(List<B> lb,
                            List<C> lc,
                            F<A,F<B,F<C,D>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D,E> List<E> bind(List<B> lb,
                              List<C> lc,
                              List<D> ld,
                              F<A,F<B,F<C,F<D,E>>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

ld - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D,E,F$> List<F$> bind(List<B> lb,
                                  List<C> lc,
                                  List<D> ld,
                                  List<E> le,
                                  F<A,F<B,F<C,F<D,F<E,F$>>>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

ld - A given list to bind the given function with.

le - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D,E,F$,G> List<G> bind(List<B> lb,
                                   List<C> lc,
                                   List<D> ld,
                                   List<E> le,
                                   List<F$> lf,
                                   F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

ld - A given list to bind the given function with.

le - A given list to bind the given function with.

lf - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H> List<H> bind(List<B> lb,
                                     List<C> lc,
                                     List<D> ld,
                                     List<E> le,
                                     List<F$> lf,
                                     List<G> lg,
                                     F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

ld - A given list to bind the given function with.

le - A given list to bind the given function with.

lf - A given list to bind the given function with.

lg - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H,I> List<I> bind(List<B> lb,
                                       List<C> lc,
                                       List<D> ld,
                                       List<E> le,
                                       List<F$> lf,
                                       List<G> lg,
                                       List<H> lh,
                                       F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)

Binds the given function across each element of this list and the given lists with a final join.

Parameters:

lb - A given list to bind the given function with.

lc - A given list to bind the given function with.

ld - A given list to bind the given function with.

le - A given list to bind the given function with.

lf - A given list to bind the given function with.

lg - A given list to bind the given function with.

lh - A given list to bind the given function with.

f - The function to apply to each element of this list and the given lists.

Returns:

A new list after performing the map, then final join.

sequence

public <B> List<B> sequence(List<B> bs)

Performs a bind across each list element, but ignores the element value each time.

Parameters:

bs - The list to apply in the final join.

Returns:

A new list after the final join.

apply

public <B> List<B> apply(List<F<A,B>> lf)

Performs function application within a list (applicative functor pattern).

Parameters:

lf - The list of functions to apply.

Returns:

A new list after applying the given list of functions through this list.

append

public List<A> append(List<A> as)

Appends the given list to this list.

Parameters:

as - The list to append to this one.

Returns:

A new list that has appended the given list.

foldRight

public <B> B foldRight(F<A,F<B,B>> f,
                       B b)

Performs a right-fold reduction across this list. This function uses O(length) stack space.

Parameters:

f - The function to apply on each element of the list.

b - The beginning value to start the application from.

Returns:

The final result after the right-fold reduction.

foldLeft

public <B> B foldLeft(F<B,F<A,B>> f,
                      B b)

Performs a left-fold reduction across this list. This function runs in constant space.

Parameters:

f - The function to apply on each element of the list.

b - The beginning value to start the application from.

Returns:

The final result after the left-fold reduction.

reverse

public List<A> reverse()

Reverse this list in constant stack space.

Returns:

A new list that is the reverse of this one.

index

public A index(int i)

Returns the element at the given index if it exists, fails otherwise.

Parameters:

i - The index at which to get the element to return.

Returns:

The element at the given index if it exists, fails otherwise.

take

public List<A> take(int i)

Takes the given number of elements from the head of this list if they are available.

Parameters:

i - The maximum number of elements to take from this list.

Returns:

A new list with a length the same, or less than, this list.

drop

public List<A> drop(int i)

Drops the given number of elements from the head of this list if they are available.

Parameters:

i - The number of elements to drop from the head of this list.

Returns:

A list with a length the same, or less than, this list.

splitAt

public P2<List<A>,List<A>> splitAt(int i)

Splits this list into two lists at the given index. If the index goes out of bounds, then it is normalised so that this function never fails.

Parameters:

i - The index at which to split this list in two parts.

Returns:

A pair of lists split at the given index of this list.

sort

public List<A> sort(Ord<A> o)

Sorts this list using the given order over elements using a merge sort algorithm.

Parameters:

o - The order over the elements of this list.

Returns:

A sorted list according to the given order.

zipWith

public <B,C> List<C> zipWith(List<B> bs,
                             F<A,F<B,C>> f)

Zips this list with the given list using the given function to produce a new list. If this list and the given list have different lengths, then the longer list is normalised so this function never fails.

Parameters:

bs - The list to zip this list with.

f - The function to zip this list and the given list with.

Returns:

A new list with a length the same as the shortest of this list and the given list.

zip

public <B> List<P2<A,B>> zip(List<B> bs)

Zips this list with the given list to produce a list of pairs. If this list and the given list have different lengths, then the longer list is normalised so this function never fails.

Parameters:

bs - The list to zip this list with.

Returns:

A new list with a length the same as the shortest of this list and the given list.

zipIndex

public List<P2<A,Integer>> zipIndex()

Zips this list with the index of its element as a pair.

Returns:

A new list with the same length as this list.

snoc

public List<A> snoc(A a)

Appends (snoc) the given element to this list to produce a new list.

Parameters:

a - The element to append to this list.

Returns:

A new list with the given element appended.

forall

public boolean forall(F<A,Boolean> f)

Returns true if the predicate holds for all of the elements of this list, false otherwise (true for the empty list).

Parameters:

f - The predicate function to test on each element of this list.

Returns:

true if the predicate holds for all of the elements of this list, false otherwise.

exists

public boolean exists(F<A,Boolean> f)

Returns true if the predicate holds for at least one of the elements of this list, false otherwise (false for the empty list).

Parameters:

f - The predicate function to test on the elements of this list.

Returns:

true if the predicate holds for at least one of the elements of this list.

find

public Option<A> find(F<A,Boolean> f)

Finds the first occurrence of an element that matches the given predicate or no value if no elements match.

Parameters:

f - The predicate function to test on elements of this list.

Returns:

The first occurrence of an element that matches the given predicate or no value if no elements match.

intersperse

public List<A> intersperse(A a)

Intersperses the given argument between each element of this list.

Parameters:

a - The separator to intersperse in this list.

Returns:

A list with the given separator interspersed.

list

public static <A> List<A> list(A... as)

Constructs a list from the given elements.

Parameters:

as - The elements to construct a list with.

Returns:

A list with the given elements.

nil

public static <A> List<A> nil()

Returns an empty list.

Returns:

An empty list.

cons

public static <A> F<A,F<List<A>,List<A>>> cons()

Returns a function that prepends (cons) an element to a list to produce a new list.

Returns:

A function that prepends (cons) an element to a list to produce a new list.

cons

public static <A> List<A> cons(A head,
                               List<A> tail)

Prepends the given head element to the given tail element to produce a new list.

Parameters:

head - The element to prepend.

tail - The list to prepend to.

Returns:

The list with the given element prepended.

isEmpty_

public static <A> F<List<A>,Boolean> isEmpty_()

Returns a function that determines whether a given list is empty.

Returns:

A function that determines whether a given list is empty.

isNotEmpty_

public static <A> F<List<A>,Boolean> isNotEmpty_()

Returns a function that determines whether a given list is not empty.

Returns:

A function that determines whether a given list is not empty.

join

public static <A> List<A> join(List<List<A>> o)

Joins the given list of lists using a bind operation.

Parameters:

o - The list of lists to join.

Returns:

A new list that is the join of the given lists.

unfold

public static <A,B> List<A> unfold(F<B,Option<P2<A,B>>> f,
                                   B b)

Unfolds across the given function starting at the given value to produce a list.

Parameters:

f - The function to unfold across.

b - The start value to begin the unfold.

Returns:

A new list that is a result of unfolding until the function does not produce a value.

replicate

public static <A> List<A> replicate(int n,
                                    A a)

Returns a list of the given value replicated the given number of times.

Parameters:

n - The number of times to replicate the given value.

a - The value to replicate.

Returns:

A list of the given value replicated the given number of times.

range

public static List<Integer> range(int from,
                                  int to)

Returns a list of integers from the given from value (inclusive) to the given to value (exclusive).

Parameters:

from - The minimum value for the list (inclusive).

to - The maximum value for the list (exclusive).

Returns:

A list of integers from the given from value (inclusive) to the given to value (exclusive).

fromString

public static List<Character> fromString(String s)

Returns a list of characters from the given string. The inverse of this function is asString(List).

Parameters:

s - The string to produce the list of characters from.

Returns:

A list of characters from the given string.

asString

public static String asString(List<Character> cs)

Returns a string from the given list of characters. The invers of this function is fromString(String).

Parameters:

cs - The list of characters to produce the string from.

Returns:

A string from the given list of characters.

single

public static <A> List<A> single(A a)

Returns a list of one element containing the given value.

Parameters:

a - The value for the head of the returned list.

Returns:

A list of one element containing the given value.

iterateWhile

public static <A> List<A> iterateWhile(F<A,A> f,
                                       F<A,Boolean> p,
                                       A a)

Creates a list where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.

Parameters:

f - The function to iterate with.

p - The predicate which must be true for the next item in order to continue the iteration.

a - The input to the first iteration.

Returns:

A list where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.

bind_

public static <A,B> F<F<A,List<B>>,F<List<A>,List<B>>> bind_()

Returns:

The bind function for lists.

map_

public static <A,B> F<F<A,B>,F<List<A>,List<B>>> map_()

Returns:

The map function for lists.