@grain/stdlib 0.5.2 → 0.5.4

package/immutableset.md

@@ -0,0 +1,449 @@
+---
+title: ImmutableSet
+---
+
+An ImmutableSet is a collection of unique values. Operations on an ImmutableSet do not mutate the set's internal state.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import ImmutableSet from "immutableset"
+```
+
+## Types
+
+Type declarations included in the ImmutableSet module.
+
+### ImmutableSet.**ImmutableSet**
+
+```grain
+type ImmutableSet<a>
+```
+
+## Values
+
+Functions and constants for working with ImmutableSets.
+
+### ImmutableSet.**empty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+empty : ImmutableSet<a>
+```
+
+An empty set
+
+### ImmutableSet.**size**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : ImmutableSet<a> -> Number
+```
+
+Provides the count of values within the set.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set`|`ImmutableSet<a>`|The set to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The count of elements in the set|
+
+### ImmutableSet.**isEmpty**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isEmpty : ImmutableSet<a> -> Bool
+```
+
+Determines if the set contains no elements.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set`|`ImmutableSet<a>`|The set to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the given set is empty or `false` otherwise|
+
+### ImmutableSet.**add**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+add : (a, ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Produces a new set by inserting the given value into the set. If the value
+already exists, the new set will have the same elements as the input set.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The value to add|
+|`set`|`ImmutableSet<a>`|The base set|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A new set containing the new element|
+
+### ImmutableSet.**contains**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+contains : (a, ImmutableSet<a>) -> Bool
+```
+
+Determines if the set contains the given value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The value to search for|
+|`set`|`ImmutableSet<a>`|The set to search|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the set contains the given value or `false` otherwise|
+
+### ImmutableSet.**remove**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+remove : (a, ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Produces a new set without the given element. If the value doesn't exist in
+the set, the set will be returned unmodified.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`key`|`a`|The value to exclude|
+|`set`|`ImmutableSet<a>`|The set to exclude from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A new set without the excluded element|
+
+### ImmutableSet.**forEach**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+forEach : ((a -> Void), ImmutableSet<a>) -> Void
+```
+
+Iterates the set, calling an iterator function on each element.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Void`|The iterator function to call with each element|
+|`set`|`ImmutableSet<a>`|The set to iterate|
+
+### ImmutableSet.**reduce**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reduce : (((a, b) -> a), a, ImmutableSet<b>) -> a
+```
+
+Combines all elements of a set using a reducer function.
+
+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|
+|`init`|`a`|The initial value to use for the accumulator on the first iteration|
+|`set`|`ImmutableSet<b>`|The set to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The final accumulator returned from `fn`|
+
+### ImmutableSet.**filter**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+filter : ((a -> Bool), ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Produces a new set without the elements from the input set where a predicate function returns `false`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Bool`|The predicate function to indicate which elements to exclude from the set, where returning `false` indicates the value should be excluded|
+|`set`|`ImmutableSet<a>`|The set to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A new set excluding the elements not fulfilling the predicate|
+
+### ImmutableSet.**reject**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+reject : ((a -> Bool), ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Produces a new set without the elements from the input set where a predicate function returns `true`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Bool`|The predicate function to indicate which elements to exclude from the set, where returning `true` indicates the value should be excluded|
+|`set`|`ImmutableSet<a>`|The set to iterate|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A new set excluding the elements fulfilling the predicate|
+
+### ImmutableSet.**union**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+union : (ImmutableSet<a>, ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Combines two sets into a single set containing all elements from both sets.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set1`|`ImmutableSet<a>`|The first set to combine|
+|`set2`|`ImmutableSet<a>`|The second set to combine|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A set containing all elements of both sets|
+
+### ImmutableSet.**diff**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+diff : (ImmutableSet<a>, ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Combines two sets into a single set containing only the elements not shared between both sets.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set1`|`ImmutableSet<a>`|The first set to combine|
+|`set2`|`ImmutableSet<a>`|The second set to combine|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A set containing only unshared elements from both sets|
+
+### ImmutableSet.**intersect**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+intersect : (ImmutableSet<a>, ImmutableSet<a>) -> ImmutableSet<a>
+```
+
+Combines two sets into a single set containing only the elements shared between both sets.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set1`|`ImmutableSet<a>`|The first set to combine|
+|`set2`|`ImmutableSet<a>`|The second set to combine|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A set containing only shared elements from both sets|
+
+### ImmutableSet.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList : List<a> -> ImmutableSet<a>
+```
+
+Creates a set from a list.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`list`|`List<a>`|The list to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A set containing all list values|
+
+### ImmutableSet.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList : ImmutableSet<a> -> List<a>
+```
+
+Converts a set into a list of its elements.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set`|`ImmutableSet<a>`|The set to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all set values|
+
+### ImmutableSet.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray : Array<a> -> ImmutableSet<a>
+```
+
+Creates a set from an array.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`array`|`Array<a>`|The array to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`ImmutableSet<a>`|A set containing all array values|
+
+### ImmutableSet.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray : ImmutableSet<a> -> Array<a>
+```
+
+Converts a set into an array of its elements.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`set`|`ImmutableSet<a>`|The set to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Array<a>`|An array containing all set values|
+

package/list.gr

@@ -520,8 +520,8 @@ export let part = (count, list) => {
  * @since v0.1.0
  */
 export let rotate = (count, list) => {
-  let (beginning, end) = if (count >= 0) part(count, list)
-    else part(length(list) + count, list)
+  let (beginning, end) =
+    if (count >= 0) part(count, list) else part(length(list) + count, list)
   append(end, beginning)
 }
 
@@ -548,6 +548,79 @@ export let unique = list => {
   iter(list, [])
 }
 
+/**
+ * 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.
+ *
+ * @param list1: The list to provide values for the first tuple element
+ * @param list2: The list to provide values for the second tuple element
+ * @returns The new list containing indexed pairs of `(a, b)`
+ *
+ * @example List.zip([1, 2, 3], [4, 5, 6]) // [(1, 4), (2, 5), (3, 6)]
+ * @example List.zip([1, 2, 3], [4, 5]) // [(1, 4), (2, 5)]
+ * 
+ * @since v0.5.3
+ */
+export let zip = (list1, list2) => {
+  let rec zipInner = (list1, list2, acc) => {
+    match ((list1, list2)) {
+      ([first1, ...rest1], [first2, ...rest2]) =>
+        zipInner(rest1, rest2, [(first1, first2), ...acc]),
+      _ => acc,
+    }
+  }
+  reverse(zipInner(list1, list2, []))
+}
+
+/**
+ * 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.
+ *
+ * @param fn: The function to apply to pairs of elements
+ * @param list1: The list whose elements will each be passed to the function as the first argument
+ * @param list2: The list whose elements will each be passed to the function as the second argument
+ * @returns The new list containing elements derived from applying the function to pairs of input list elements
+ *
+ * @example List.zipWith((a, b) => a + b, [1, 2, 3], [4, 5, 6]) // [5, 7, 9]
+ * @example List.zipWith((a, b) => a * b, [1, 2, 3], [4, 5]) // [4, 10]
+ * 
+ * @since v0.5.3
+ */
+export let zipWith = (fn, list1, list2) => {
+  let rec zipWithInner = (list1, list2, acc) => {
+    match ((list1, list2)) {
+      ([first1, ...rest1], [first2, ...rest2]) =>
+        zipWithInner(rest1, rest2, [fn(first1, first2), ...acc]),
+      _ => acc,
+    }
+  }
+  reverse(zipWithInner(list1, list2, []))
+}
+
+/**
+ * Produces two lists by splitting apart a list of tuples.
+ *
+ * @param list: The list of tuples to split
+ * @returns An list containing all elements from the first tuple element, and a list containing all elements from the second tuple element
+ *
+ * @since v0.5.3
+ */
+export let unzip = list => {
+  reduceRight(((first, second), (firstUnzipped, secondUnzipped)) => {
+    ([first, ...firstUnzipped], [second, ...secondUnzipped])
+  }, ([], []), list)
+}
+
 /**
  * Produces a new list with the specified number of elements removed from
  * the beginning of the input list.

package/list.md

@@ -819,6 +819,116 @@ Returns:
 |----|-----------|
 |`List<a>`|The new list with only unique values|
 
+### List.**zip**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+zip : (List<a>, 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:
+
+|param|type|description|
+|-----|----|-----------|
+|`list1`|`List<a>`|The list to provide values for the first tuple element|
+|`list2`|`List<b>`|The list to provide values for the second tuple element|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<(a, b)>`|The new list containing indexed pairs of `(a, b)`|
+
+Examples:
+
+```grain
+List.zip([1, 2, 3], [4, 5, 6]) // [(1, 4), (2, 5), (3, 6)]
+```
+
+```grain
+List.zip([1, 2, 3], [4, 5]) // [(1, 4), (2, 5)]
+```
+
+### List.**zipWith**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+zipWith : (((a, b) -> c), List<a>, 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:
+
+|param|type|description|
+|-----|----|-----------|
+|`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|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<c>`|The new list containing elements derived from applying the function to pairs of input list elements|
+
+Examples:
+
+```grain
+List.zipWith((a, b) => a + b, [1, 2, 3], [4, 5, 6]) // [5, 7, 9]
+```
+
+```grain
+List.zipWith((a, b) => a * b, [1, 2, 3], [4, 5]) // [4, 10]
+```
+
+### List.**unzip**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.5.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+unzip : List<(a, b)> -> (List<a>, List<b>)
+```
+
+Produces two lists by splitting apart a list of tuples.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`list`|`List<(a, b)>`|The list of tuples to split|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`(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**
 
 <details disabled>

package/map.gr

@@ -504,8 +504,7 @@ export let reject = (predicate, map) => {
   filter((key, value) => !predicate(key, value), map)
 }
 
-// TODO: Should return a Record type instead of a Tuple
-// Waiting on https://github.com/grain-lang/grain/issues/190
+// TODO(#190): Should return a Record type instead of a Tuple
 /**
  * Provides data representing the internal state state of the map.
  *