@grain/stdlib 0.5.13 → 0.6.0

package/list.md

@@ -18,12 +18,12 @@ Utilities for working with lists.
 </details>
 
 ```grain
-import List from "list"
+from "list" include List
 ```
 
 ## Values
 
-Functions for working with the List data type.
+Functions and constants included in the List module.
 
 ### List.**init**
 
@@ -33,7 +33,7 @@ No other changes yet.
 </details>
 
 ```grain
-init : (Number, (Number -> a)) -> List<a>
+init : (length: Number, fn: (Number => a)) => List<a>
 ```
 
 Creates a new list of the specified length where each element is
@@ -45,7 +45,7 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`length`|`Number`|The length of the new list|
-|`fn`|`Number -> a`|The initializer function to call with each index, where the value returned will be used to initialize the element|
+|`fn`|`Number => a`|The initializer function to call with each index, where the value returned will be used to initialize the element|
 
 Returns:
 
@@ -74,7 +74,7 @@ List.init(5, n => n + 3) // [3, 4, 5, 6, 7]
 </details>
 
 ```grain
-length : List<a> -> Number
+length : (list: List<a>) => Number
 ```
 
 Computes the length of the input list.
@@ -91,6 +91,31 @@ Returns:
 |----|-----------|
 |`Number`|The number of elements in the list|
 
+### List.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : (list: List<a>) => Bool
+```
+
+Determines if the list contains no elements.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`list`|`List<a>`|The list to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the list is empty and `false` otherwise|
+
 ### List.**reverse**
 
 <details disabled>
@@ -99,7 +124,7 @@ No other changes yet.
 </details>
 
 ```grain
-reverse : List<a> -> List<a>
+reverse : (list: List<a>) => List<a>
 ```
 
 Creates a new list with all elements in reverse order.
@@ -124,7 +149,7 @@ No other changes yet.
 </details>
 
 ```grain
-append : (List<a>, List<a>) -> List<a>
+append : (list1: List<a>, list2: List<a>) => List<a>
 ```
 
 Creates a new list with the elements of the first list followed by
@@ -151,7 +176,7 @@ No other changes yet.
 </details>
 
 ```grain
-contains : (a, List<a>) -> Bool
+contains : (search: a, list: List<a>) => Bool
 ```
 
 Checks if the value is an element of the input list.
@@ -186,7 +211,7 @@ Returns:
 </details>
 
 ```grain
-reduce : (((a, b) -> a), a, List<b>) -> a
+reduce : (fn: ((a, b) => a), initial: a, list: List<b>) => a
 ```
 
 Combines all elements of a list using a reducer function,
@@ -201,7 +226,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, b) -> a`|The reducer function to call on each element, where the value returned will be the next accumulator value|
+|`fn`|`(a, b) => a`|The reducer function to call on each element, where the value returned will be the next accumulator value|
 |`initial`|`a`|The initial value to use for the accumulator on the first iteration|
 |`list`|`List<b>`|The list to iterate|
 
@@ -233,7 +258,7 @@ List.reduce((a, b) => a + b, 0, [1, 2, 3]) // 6
 </details>
 
 ```grain
-reduceRight : (((a, b) -> b), b, List<a>) -> b
+reduceRight : (fn: ((a, b) => b), initial: b, list: List<a>) => b
 ```
 
 Combines all elements of a list using a reducer function,
@@ -248,7 +273,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, b) -> b`|The reducer function to call on each element, where the value returned will be the next accumulator value|
+|`fn`|`(a, b) => b`|The reducer function to call on each element, where the value returned will be the next accumulator value|
 |`initial`|`b`|The initial value to use for the accumulator on the first iteration|
 |`list`|`List<a>`|The list to iterate|
 
@@ -272,7 +297,7 @@ No other changes yet.
 </details>
 
 ```grain
-map : ((a -> b), List<a>) -> List<b>
+map : (fn: (a => b), list: List<a>) => List<b>
 ```
 
 Produces a new list initialized with the results of a mapper function
@@ -282,7 +307,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
+|`fn`|`a => b`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -299,7 +324,7 @@ No other changes yet.
 </details>
 
 ```grain
-mapi : (((a, Number) -> b), List<a>) -> List<b>
+mapi : (fn: ((a, Number) => b), list: List<a>) => List<b>
 ```
 
 Produces a new list initialized with the results of a mapper function
@@ -309,7 +334,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, Number) -> b`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
+|`fn`|`(a, Number) => b`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -326,7 +351,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatMap : ((a -> List<b>), List<a>) -> List<b>
+flatMap : (fn: (a => List<b>), list: List<a>) => List<b>
 ```
 
 Produces a new list by calling a function on each element
@@ -338,7 +363,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> List<b>`|The function to be called on each element, where the value returned will be a list that gets appended to the new list|
+|`fn`|`a => List<b>`|The function to be called on each element, where the value returned will be a list that gets appended to the new list|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -355,7 +380,7 @@ No other changes yet.
 </details>
 
 ```grain
-every : ((a -> Bool), List<a>) -> Bool
+every : (fn: (a => Bool), list: List<a>) => Bool
 ```
 
 Checks that the given condition is satisfied for all
@@ -365,7 +390,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to check|
 
 Returns:
@@ -382,7 +407,7 @@ No other changes yet.
 </details>
 
 ```grain
-some : ((a -> Bool), List<a>) -> Bool
+some : (fn: (a => Bool), list: List<a>) => Bool
 ```
 
 Checks that the given condition is satisfied **at least
@@ -392,7 +417,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -409,7 +434,7 @@ No other changes yet.
 </details>
 
 ```grain
-forEach : ((a -> Void), List<a>) -> Void
+forEach : (fn: (a => Void), list: List<a>) => Void
 ```
 
 Iterates a list, calling an iterator function on each element.
@@ -418,7 +443,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Void`|The iterator function to call with each element|
+|`fn`|`a => Void`|The iterator function to call with each element|
 |`list`|`List<a>`|The list to iterate|
 
 ### List.**forEachi**
@@ -429,7 +454,7 @@ No other changes yet.
 </details>
 
 ```grain
-forEachi : (((a, Number) -> Void), List<a>) -> Void
+forEachi : (fn: ((a, Number) => Void), list: List<a>) => Void
 ```
 
 Iterates a list, calling an iterator function on each element.
@@ -439,7 +464,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, Number) -> Void`|The iterator function to call with each element|
+|`fn`|`(a, Number) => Void`|The iterator function to call with each element|
 |`list`|`List<a>`|The list to iterate|
 
 ### List.**filter**
@@ -450,7 +475,7 @@ No other changes yet.
 </details>
 
 ```grain
-filter : ((a -> Bool), List<a>) -> List<a>
+filter : (fn: (a => Bool), list: List<a>) => List<a>
 ```
 
 Produces a new list by calling a function on each element of
@@ -461,7 +486,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -478,7 +503,7 @@ No other changes yet.
 </details>
 
 ```grain
-filteri : (((a, Number) -> Bool), List<a>) -> List<a>
+filteri : (fn: ((a, Number) => Bool), list: List<a>) => List<a>
 ```
 
 Produces a new list by calling a function on each element of
@@ -489,7 +514,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, Number) -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`(a, Number) => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -506,7 +531,7 @@ No other changes yet.
 </details>
 
 ```grain
-reject : ((a -> Bool), List<a>) -> List<a>
+reject : (fn: (a => Bool), list: List<a>) => List<a>
 ```
 
 Produces a new list by calling a function on each element of
@@ -517,7 +542,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -543,7 +568,7 @@ Returns:
 </details>
 
 ```grain
-head : List<a> -> Option<a>
+head : (list: List<a>) => Option<a>
 ```
 
 Provides `Some(element)` containing the first element, or "head", of
@@ -578,7 +603,7 @@ Returns:
 </details>
 
 ```grain
-tail : List<a> -> Option<List<a>>
+tail : (list: List<a>) => Option<List<a>>
 ```
 
 Provides `Some(tail)` containing all list items except the first element, or "tail", of
@@ -612,7 +637,7 @@ Returns:
 </details>
 
 ```grain
-nth : (Number, List<a>) -> Option<a>
+nth : (index: Number, list: List<a>) => Option<a>
 ```
 
 Provides `Some(element)` containing the element in the list at the specified index
@@ -639,7 +664,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatten : List<List<a>> -> List<a>
+flatten : (list: List<List<a>>) => List<a>
 ```
 
 Flattens nested lists.
@@ -664,13 +689,20 @@ List.flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
 
 ### List.**insert**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.1.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.1.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Swapped order of `index` and `value` parameters</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-insert : (a, Number, List<a>) -> List<a>
+insert : (index: Number, value: a, list: List<a>) => List<a>
 ```
 
 Inserts a new value into a list at the specified index.
@@ -679,8 +711,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`value`|`a`|The value to insert|
 |`index`|`Number`|The index to update|
+|`value`|`a`|The value to insert|
 |`list`|`List<a>`|The list to update|
 
 Returns:
@@ -711,7 +743,7 @@ Throws:
 </details>
 
 ```grain
-count : ((a -> Bool), List<a>) -> Number
+count : (fn: (a => Bool), list: List<a>) => Number
 ```
 
 Counts the number of elements in a list that satisfy the given condition.
@@ -720,7 +752,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to iterate|
 
 Returns:
@@ -737,7 +769,7 @@ No other changes yet.
 </details>
 
 ```grain
-part : (Number, List<a>) -> (List<a>, List<a>)
+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.
@@ -764,16 +796,24 @@ Throws:
 
 ### List.**rotate**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.1.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.1.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>No longer throws if `count` outside list length bounds</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-rotate : (Number, List<a>) -> List<a>
+rotate : (n: Number, list: List<a>) => List<a>
 ```
 
-Rotates list elements by the specified amount to the left.
+Rotates list elements by the specified amount to the left, such that `n`th
+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.
@@ -782,15 +822,9 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`count`|`Number`|The number of elements to rotate by|
+|`n`|`Number`|The number of elements to rotate by|
 |`list`|`List<a>`|The list to be rotated|
 
-Throws:
-
-`Failure(String)`
-
-* When the list doesn't contain at least the required amount of elements
-
 Examples:
 
 ```grain
@@ -801,6 +835,10 @@ 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]
 ```
 
+```grain
+List.rotate(-7, [1, 2, 3, 4, 5]) // [4, 5, 1, 2, 3]
+```
+
 ### List.**unique**
 
 <details>
@@ -817,7 +855,7 @@ List.rotate(-1, [1, 2, 3, 4, 5]) // [5, 1, 2, 3, 4]
 </details>
 
 ```grain
-unique : List<a> -> List<a>
+unique : (list: List<a>) => List<a>
 ```
 
 Produces a new list with any duplicates removed.
@@ -843,7 +881,7 @@ No other changes yet.
 </details>
 
 ```grain
-zip : (List<a>, List<b>) -> List<(a, b)>
+zip : (list1: List<a>, list2: List<b>) => List<(a, b)>
 ```
 
 Produces a new list filled with tuples of elements from both given lists.
@@ -884,7 +922,7 @@ No other changes yet.
 </details>
 
 ```grain
-zipWith : (((a, b) -> c), List<a>, List<b>) -> List<c>
+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
@@ -900,7 +938,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`(a, b) -> c`|The function to apply to pairs of elements|
+|`fn`|`(a, b) => c`|The function to apply to pairs of elements|
 |`list1`|`List<a>`|The list whose elements will each be passed to the function as the first argument|
 |`list2`|`List<b>`|The list whose elements will each be passed to the function as the second argument|
 
@@ -928,7 +966,7 @@ No other changes yet.
 </details>
 
 ```grain
-unzip : List<(a, b)> -> (List<a>, List<b>)
+unzip : (list: List<(a, b)>) => (List<a>, List<b>)
 ```
 
 Produces two lists by splitting apart a list of tuples.
@@ -953,7 +991,7 @@ No other changes yet.
 </details>
 
 ```grain
-drop : (Number, List<a>) -> List<a>
+drop : (count: Number, list: List<a>) => List<a>
 ```
 
 Produces a new list with the specified number of elements removed from
@@ -986,7 +1024,7 @@ No other changes yet.
 </details>
 
 ```grain
-dropWhile : ((a -> Bool), List<a>) -> List<a>
+dropWhile : (fn: (a => Bool), list: List<a>) => List<a>
 ```
 
 Produces a new list with the elements removed from the beginning
@@ -997,7 +1035,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The input list|
 
 Returns:
@@ -1014,7 +1052,7 @@ No other changes yet.
 </details>
 
 ```grain
-take : (Number, List<a>) -> List<a>
+take : (count: Number, list: List<a>) => List<a>
 ```
 
 Produces a new list with–at most—the specified amount elements from
@@ -1047,7 +1085,7 @@ No other changes yet.
 </details>
 
 ```grain
-takeWhile : ((a -> Bool), List<a>) -> List<a>
+takeWhile : (fn: (a => Bool), list: List<a>) => List<a>
 ```
 
 Produces a new list with elements from the beginning of the input list
@@ -1058,7 +1096,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The input list|
 
 Returns:
@@ -1083,7 +1121,7 @@ Returns:
 </details>
 
 ```grain
-find : ((a -> Bool), List<a>) -> Option<a>
+find : (fn: (a => Bool), list: List<a>) => Option<a>
 ```
 
 Finds the first element in a list that satifies the given condition.
@@ -1092,7 +1130,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to search|
 
 Returns:
@@ -1117,7 +1155,7 @@ Returns:
 </details>
 
 ```grain
-findIndex : ((a -> Bool), List<a>) -> Option<Number>
+findIndex : (fn: (a => Bool), list: List<a>) => Option<Number>
 ```
 
 Finds the first index in a list where the element satifies the given condition.
@@ -1126,7 +1164,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
+|`fn`|`a => Bool`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
 |`list`|`List<a>`|The list to search|
 
 Returns:
@@ -1143,7 +1181,7 @@ No other changes yet.
 </details>
 
 ```grain
-product : (List<a>, List<b>) -> List<(a, b)>
+product : (list1: List<a>, list2: List<b>) => List<(a, b)>
 ```
 
 Combines two lists into a Cartesian product of tuples containing
@@ -1170,7 +1208,7 @@ No other changes yet.
 </details>
 
 ```grain
-sub : (Number, Number, List<a>) -> List<a>
+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
@@ -1205,7 +1243,7 @@ No other changes yet.
 </details>
 
 ```grain
-join : (String, List<String>) -> String
+join : (separator: String, list: List<String>) => String
 ```
 
 Combine the given list of strings into one string with the specified
@@ -1232,7 +1270,7 @@ No other changes yet.
 </details>
 
 ```grain
-revAppend : (List<a>, List<a>) -> List<a>
+revAppend : (list1: List<a>, list2: List<a>) => List<a>
 ```
 
 Reverses the first list and appends the second list to the end.
@@ -1252,13 +1290,20 @@ Returns:
 
 ### List.**sort**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.4.5</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.4.5</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.6.0</code></td><td>Made `compare` a default argument</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-sort : (((a, a) -> Number), List<a>) -> List<a>
+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.
@@ -1269,7 +1314,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`comp`|`(a, a) -> Number`|The comparator function used to indicate sort order|
+|`?compare`|`(num1: a, num2: a) => Number`|The comparator function used to indicate sort order|
 |`list`|`List<a>`|The list to be sorted|
 
 Returns: