ESC
No recent searches
Search by
Standard Library  /  List

Grain Docs

Welcome to Grain! Editor Setup Getting Grain

The Guide

Hello World The Basics Conditionals Functions Shadowing and Mutation Loops Lists and arrays Custom Data Types Modules Pattern Matching

Reference

Building for Production Built-in Types The Grain CLI Graindoc

Standard Library

Pervasives BigInt Array Buffer Bytes Char Exception Float32 Float64 Hash Int16 Int32 Int64 Int8 Json List Map Marshal Number Option Path PriorityQueue Queue Random Range Rational Regex Result Stack Set String Uint16 Uint32 Uint64 Uint8 Uri wasi / File wasi / Process wasi / Random wasi / Time

List

Utilities for working with lists.

Edit on GitHub
Added in 0.2.0
versionchanges
0.1.0Originally named `lists`
0.2.0Renamed to `list`
 
from "list" include List

Values

Functions and constants included in the List module.

List.init

Added in 0.3.0 No other changes yet. 
init : (length: Number, fn: (Number => a)) => List<a>

Creates a new list of the specified length where each element is initialized with the result of an initializer function. The initializer is called with the index of each list element.

Parameters:

length: The length of the new list
fn: The initializer function to call with each index, where the value returned will be used to initialize the element

Returns:

List<a>: The new list

Examples:

List.init(5, n => n + 3) // [3, 4, 5, 6, 7]

List.length

Added in 0.1.0
versionchanges
0.2.0Made the function tail-recursive
 
length : (list: List<a>) => Number

Computes the length of the input list.

Parameters:

list: The list to inspect

Returns:

Number: The number of elements in the list

List.isEmpty

Added in 0.6.0 No other changes yet. 
isEmpty : (list: List<a>) => Bool

Determines if the list contains no elements.

Parameters:

list: The list to inspect

Returns:

Bool: true if the list is empty and false otherwise

List.reverse

Added in 0.1.0 No other changes yet. 
reverse : (list: List<a>) => List<a>

Creates a new list with all elements in reverse order.

Parameters:

list: The list to reverse

Returns:

List<a>: The new list

List.append

Added in 0.1.0 No other changes yet. 
append : (list1: List<a>, list2: List<a>) => List<a>

Creates a new list with the elements of the first list followed by the elements of the second list.

Parameters:

list1: The list containing elements to appear first
list2: The list containing elements to appear second

Returns:

List<a>: The new list containing elements from list1 followed by elements from list2

List.contains

Added in 0.1.0 No other changes yet. 
contains : (search: a, list: List<a>) => Bool

Checks if the value is an element of the input list. Uses the generic == structural equality operator.

Parameters:

search: The value to compare
list: The list to inspect

Returns:

Bool: true if the value exists in the list or false otherwise

List.reduce

Added in 0.2.0
versionchanges
0.1.0Originally named `foldLeft`
0.2.0Renamed to `reduce`
 
reduce : (fn: ((a, b) => a), initial: a, list: List<b>) => a

Combines all elements of a list using a reducer function, starting from the “head”, or left side, of the list.

In List.reduce(fn, initial, list), fn is called with an accumulator and each element of the list, and returns a new accumulator. The final value is the last accumulator returned. The accumulator starts with value initial.

Parameters:

fn: The reducer function to call on each element, where the value returned will be the next accumulator value
initial: The initial value to use for the accumulator on the first iteration
list: The list to iterate

Returns:

a: The final accumulator returned from fn

Examples:

List.reduce((a, b) => a + b, 0, [1, 2, 3]) // 6

List.reduceRight

Added in 0.2.0
versionchanges
0.1.0Originally named `foldRight`
0.2.0Renamed to `reduceRight`
 
reduceRight : (fn: ((a, b) => b), initial: b, list: List<a>) => b

Combines all elements of a list using a reducer function, starting from the “end”, or right side, of the list.

In List.reduceRight(fn, initial, list), fn is called with each element of the list and an accumulator, and returns a new accumulator. The final value is the last accumulator returned. The accumulator starts with value initial.

Parameters:

fn: The reducer function to call on each element, where the value returned will be the next accumulator value
initial: The initial value to use for the accumulator on the first iteration
list: The list to iterate

Returns:

b: The final accumulator returned from fn

Examples:

List.reduceRight((a, b) => b ++ a, "", ["baz", "bar", "foo"]) // "foobarbaz"

List.map

Added in 0.1.0 No other changes yet. 
map : (fn: (a => b), list: List<a>) => List<b>

Produces a new list initialized with the results of a mapper function called on each element of the input list.

Parameters:

fn: The mapper function to call on each element, where the value returned will be used to initialize the element in the new list
list: The list to iterate

Returns:

List<b>: The new list with mapped values

List.mapi

Added in 0.1.0 No other changes yet. 
mapi : (fn: ((a, Number) => b), list: List<a>) => List<b>

Produces a new list initialized with the results of a mapper function called on each element of the input list and its index.

Parameters:

fn: The mapper function to call on each element, where the value returned will be used to initialize the element in the new list
list: The list to iterate

Returns:

List<b>: The new list with mapped values

List.flatMap

Added in 0.2.0 No other changes yet. 
flatMap : (fn: (a => List<b>), list: List<a>) => List<b>

Produces a new list by calling a function on each element of the input list. Each iteration produces an intermediate list, which are all appended to produce a “flattened” list of all results.

Parameters:

fn: The function to be called on each element, where the value returned will be a list that gets appended to the new list
list: The list to iterate

Returns:

List<b>: The new list

List.every

Added in 0.1.0 No other changes yet. 
every : (fn: (a => Bool), list: List<a>) => Bool

Checks that the given condition is satisfied for all elements in the input list.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to check

Returns:

Bool: true if all elements satify the condition or false otherwise

List.some

Added in 0.1.0 No other changes yet. 
some : (fn: (a => Bool), list: List<a>) => Bool

Checks that the given condition is satisfied at least once by an element in the input list.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to iterate

Returns:

Bool: true if one or more elements satify the condition or false otherwise

List.forEach

Added in 0.1.0 No other changes yet. 
forEach : (fn: (a => Void), list: List<a>) => Void

Iterates a list, calling an iterator function on each element.

Parameters:

fn: The iterator function to call with each element
list: The list to iterate

List.forEachi

Added in 0.1.0 No other changes yet. 
forEachi : (fn: ((a, Number) => Void), list: List<a>) => Void

Iterates a list, calling an iterator function on each element. Also passes the index as the second argument to the function.

Parameters:

fn: The iterator function to call with each element
list: The list to iterate

List.filter

Added in 0.1.0 No other changes yet. 
filter : (fn: (a => Bool), list: List<a>) => List<a>

Produces a new list by calling a function on each element of the input list and only including it in the result list if the element satisfies the condition.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to iterate

Returns:

List<a>: The new list containing elements where fn returned true

List.filteri

Added in 0.3.0 No other changes yet. 
filteri : (fn: ((a, Number) => Bool), list: List<a>) => List<a>

Produces a new list by calling a function on each element of the input list and only including it in the result list if the element satisfies the condition. Also passes the index to the function.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to iterate

Returns:

List<a>: The new list containing elements where fn returned true

List.reject

Added in 0.1.0 No other changes yet. 
reject : (fn: (a => Bool), list: List<a>) => List<a>

Produces a new list by calling a function on each element of the input list and excluding it from the result list if the element satisfies the condition.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to iterate

Returns:

List<a>: The new list containing elements where fn returned false

List.head

Added in 0.2.0
versionchanges
0.1.0Originally named `hd`
0.2.0Renamed to `head`
0.3.0Return type converted to `Option` type
 
head : (list: List<a>) => Option<a>

Provides Some(element) containing the first element, or “head”, of the input list or None if the list is empty.

Parameters:

list: The list to access

Returns:

Option<a>: Some(firstElement) if the list has elements or None otherwise

List.tail

Added in 0.2.0
versionchanges
0.1.0Originally named `tl`
0.2.0Renamed to `tail`
0.3.0Return type converted to `Option` type
 
tail : (list: List<a>) => Option<List<a>>

Provides Some(tail) containing all list items except the first element, or “tail”, of the input list or None if the list is empty.

Parameters:

list: The list to access

Returns:

Option<List<a>>: Some(tail) if the list has elements or None otherwise

List.nth

Added in 0.1.0
versionchanges
0.1.0Originally failed for index out-of-bounds or list empty
0.3.0Return type converted to `Option` type
 
nth : (index: Number, list: List<a>) => Option<a>

Provides Some(element) containing the element in the list at the specified index or None if the index is out-of-bounds or the list is empty.

Parameters:

index: The index to access
list: The list to access

Returns:

Option<a>: Some(element) if the list contains an element at the index or None otherwise

List.flatten

Added in 0.1.0 No other changes yet. 
flatten : (list: List<List<a>>) => List<a>

Flattens nested lists.

Parameters:

list: The list to flatten

Returns:

List<a>: A new list containing all nested list elements combined

Examples:

List.flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]

List.insert

Added in 0.1.0
versionchanges
0.6.0Swapped order of `index` and `value` parameters
 
insert : (index: Number, value: a, list: List<a>) => List<a>

Inserts a new value into a list at the specified index.

Parameters:

index: The index to update
value: The value to insert
list: The list to update

Returns:

List<a>: The new list

Throws:

Failure(String)

  • When index is negative
  • When index is more than 0 and greater than the list size

List.count

Added in 0.1.0
versionchanges
0.2.0Made the function tail-recursive
 
count : (fn: (a => Bool), list: List<a>) => Number

Counts the number of elements in a list that satisfy the given condition.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to iterate

Returns:

Number: The total number of elements that satisfy the condition

List.part

Added in 0.1.0 No other changes yet. 
part : (count: Number, list: List<a>) => (List<a>, List<a>)

Split a list into two, with the first list containing the required number of elements.

Parameters:

count: The number of elements required
list: The list to split

Returns:

(List<a>, List<a>): Two lists where the first contains exactly the required amount of elements and the second contains any remaining elements

Throws:

Failure(String)

  • When count is negative
  • When the list doesn’t contain at least the required amount of elements

List.rotate

Added in 0.1.0
versionchanges
0.6.0No longer throws if `count` outside list length bounds
 
rotate : (n: Number, list: List<a>) => List<a>

Rotates list elements by the specified amount to the left, such that nth element is the first in the new list.

If value is negative, list elements will be rotated by the specified amount to the right. See examples.

Parameters:

n: The number of elements to rotate by
list: The list to be rotated

Examples:

List.rotate(2, [1, 2, 3, 4, 5]) // [3, 4, 5, 1, 2]
List.rotate(-1, [1, 2, 3, 4, 5]) // [5, 1, 2, 3, 4]
List.rotate(-7, [1, 2, 3, 4, 5]) // [4, 5, 1, 2, 3]

List.unique

Added in 0.2.0
versionchanges
0.1.0Originally named `uniq`
0.2.0Renamed to `unique`
 
unique : (list: List<a>) => List<a>

Produces a new list with any duplicates removed. Uses the generic == structural equality operator.

Parameters:

list: The list to filter

Returns:

List<a>: The new list with only unique values

List.zip

Added in 0.5.3 No other changes yet. 
zip : (list1: List<a>, list2: List<b>) => List<(a, b)>

Produces a new list filled with tuples of elements from both given lists. The first tuple will contain the first item of each list, the second tuple will contain the second item of each list, and so on.

Calling this function with lists of different sizes will cause the returned list to have the length of the smaller list.

Parameters:

list1: The list to provide values for the first tuple element
list2: The list to provide values for the second tuple element

Returns:

List<(a, b)>: The new list containing indexed pairs of (a, b)

Examples:

List.zip([1, 2, 3], [4, 5, 6]) // [(1, 4), (2, 5), (3, 6)]
List.zip([1, 2, 3], [4, 5]) // [(1, 4), (2, 5)]

List.zipWith

Added in 0.5.3 No other changes yet. 
zipWith : (fn: ((a, b) => c), list1: List<a>, list2: List<b>) => List<c>

Produces a new list filled with elements defined by applying a function on pairs from both given lists. The first element will contain the result of applying the function to the first elements of each list, the second element will contain the result of applying the function to the second elements of each list, and so on.

Calling this function with lists of different sizes will cause the returned list to have the length of the smaller list.

Parameters:

fn: The function to apply to pairs of elements
list1: The list whose elements will each be passed to the function as the first argument
list2: The list whose elements will each be passed to the function as the second argument

Returns:

List<c>: The new list containing elements derived from applying the function to pairs of input list elements

Examples:

List.zipWith((a, b) => a + b, [1, 2, 3], [4, 5, 6]) // [5, 7, 9]
List.zipWith((a, b) => a * b, [1, 2, 3], [4, 5]) // [4, 10]

List.unzip

Added in 0.5.3 No other changes yet. 
unzip : (list: List<(a, b)>) => (List<a>, List<b>)

Produces two lists by splitting apart a list of tuples.

Parameters:

list: The list of tuples to split

Returns:

(List<a>, List<b>): An list containing all elements from the first tuple element, and a list containing all elements from the second tuple element

List.drop

Added in 0.2.0 No other changes yet. 
drop : (count: Number, list: List<a>) => List<a>

Produces a new list with the specified number of elements removed from the beginning of the input list.

Parameters:

count: The amount of elements to remove
list: The input list

Returns:

List<a>: The new list without the dropped elements

Throws:

Failure(String)

  • When count is negative

List.dropWhile

Added in 0.2.0 No other changes yet. 
dropWhile : (fn: (a => Bool), list: List<a>) => List<a>

Produces a new list with the elements removed from the beginning of the input list until they no longer satisfy the given condition. Stops when the predicate function returns false.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The input list

Returns:

List<a>: The new list without the dropped elements

List.take

Added in 0.2.0 No other changes yet. 
take : (count: Number, list: List<a>) => List<a>

Produces a new list with–at most—the specified amount elements from the beginning of the input list.

Parameters:

count: The amount of elements to keep
list: The input list

Returns:

List<a>: The new list containing the taken elements

Throws:

Failure(String)

  • When count is negative

List.takeWhile

Added in 0.2.0 No other changes yet. 
takeWhile : (fn: (a => Bool), list: List<a>) => List<a>

Produces a new list with elements from the beginning of the input list as long as they satisfy the given condition. Stops when the predicate function returns false.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The input list

Returns:

List<a>: The new list containing the taken elements

List.find

Added in 0.2.0
versionchanges
0.2.0Originally failed if the list was empty
0.3.0Return type converted to `Option` type
 
find : (fn: (a => Bool), list: List<a>) => Option<a>

Finds the first element in a list that satifies the given condition.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to search

Returns:

Option<a>: Some(element) containing the first value found or None otherwise

List.findIndex

Added in 0.2.0
versionchanges
0.2.0Originally failed if the list was empty
0.3.0Return type converted to `Option` type
 
findIndex : (fn: (a => Bool), list: List<a>) => Option<Number>

Finds the first index in a list where the element satifies the given condition.

Parameters:

fn: The function to call on each element, where the returned value indicates if the element satisfies the condition
list: The list to search

Returns:

Option<Number>: Some(index) containing the index of the first element found or None otherwise

List.product

Added in 0.2.0 No other changes yet. 
product : (list1: List<a>, list2: List<b>) => List<(a, b)>

Combines two lists into a Cartesian product of tuples containing all ordered pairs (a, b).

Parameters:

list1: The list to provide values for the first tuple element
list2: The list to provide values for the second tuple element

Returns:

List<(a, b)>: The new list containing all pairs of (a, b)

List.sub

Added in 0.2.0 No other changes yet. 
sub : (start: Number, length: Number, list: List<a>) => List<a>

Provides the subset of a list given zero-based start index and amount of elements to include.

Parameters:

start: The index of the list where the subset will begin (inclusive)
length: The amount of elements to be included in the subset
list: The input list

Returns:

List<a>: The subset of the list

Throws:

Failure(String)

  • When start is negative
  • When length is negative

List.join

Added in 0.4.0 No other changes yet. 
join : (separator: String, list: List<String>) => String

Combine the given list of strings into one string with the specified separator inserted between each item.

Parameters:

separator: The separator to insert between elements
list: The list to combine

Returns:

String: The combined elements with the separator between each

List.revAppend

Added in 0.4.5 No other changes yet. 
revAppend : (list1: List<a>, list2: List<a>) => List<a>

Reverses the first list and appends the second list to the end.

Parameters:

list1: The list to reverse
list2: The list to append

Returns:

List<a>: The new list

List.sort

Added in 0.4.5
versionchanges
0.6.0Made `compare` a default argument
 
sort : (?compare: ((num1: a, num2: a) => Number), list: List<a>) => List<a>

Sorts the given list based on a given comparator function. The resulting list is sorted in increasing order.

Ordering is calculated using a comparator function which takes two list elements and must return 0 if both are equal, a positive number if the first is greater, and a negative number if the first is smaller.

Parameters:

?compare: The comparator function used to indicate sort order
list: The list to be sorted

Returns:

List<a>: The sorted list
Json Map

Sign up for farm-to-inbox developer news

You can unsubscribe at any time. Read our privacy policy.

Copyright © 2024 The Grain Programming Language