@grain/stdlib 0.6.6 → 0.7.1

package/stack.md

@@ -41,25 +41,25 @@ No other changes yet.
 </details>
 
 ```grain
-make : (?size: Number) => Stack<a>
+make: (?size: Number) => Stack<a>
 ```
 
 Creates a new stack with an initial storage of the given size. As values are
 added or removed, the internal storage may grow or shrink. Generally, you
-won’t need to care about the storage size of your map and can use the
+won’t need to care about the storage size of your stack and can use the
 default size.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`?size`|`Number`|The initial storage size of the stack|
+| param   | type     | description                           |
+| ------- | -------- | ------------------------------------- |
+| `?size` | `Number` | The initial storage size of the stack |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Stack<a>`|An empty stack|
+| type       | description    |
+| ---------- | -------------- |
+| `Stack<a>` | An empty stack |
 
 ### Stack.**isEmpty**
 
@@ -69,22 +69,22 @@ No other changes yet.
 </details>
 
 ```grain
-isEmpty : (stack: Stack<a>) => Bool
+isEmpty: (stack: Stack<a>) => Bool
 ```
 
 Checks if the given stack contains no items.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to check|
+| param   | type       | description        |
+| ------- | ---------- | ------------------ |
+| `stack` | `Stack<a>` | The stack to check |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Bool`|`true` if the stack has no items or `false` otherwise|
+| type   | description                                           |
+| ------ | ----------------------------------------------------- |
+| `Bool` | `true` if the stack has no items or `false` otherwise |
 
 ### Stack.**size**
 
@@ -94,22 +94,22 @@ No other changes yet.
 </details>
 
 ```grain
-size : (stack: Stack<a>) => Number
+size: (stack: Stack<a>) => Number
 ```
 
 Computes the size of the input stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to inspect|
+| param   | type       | description          |
+| ------- | ---------- | -------------------- |
+| `stack` | `Stack<a>` | The stack to inspect |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Number`|The count of the items in the stack|
+| type     | description                         |
+| -------- | ----------------------------------- |
+| `Number` | The count of the items in the stack |
 
 ### Stack.**peek**
 
@@ -119,22 +119,22 @@ No other changes yet.
 </details>
 
 ```grain
-peek : (stack: Stack<a>) => Option<a>
+peek: (stack: Stack<a>) => Option<a>
 ```
 
 Provides the value at the top of the stack, if it exists.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to inspect|
+| param   | type       | description          |
+| ------- | ---------- | -------------------- |
+| `stack` | `Stack<a>` | The stack to inspect |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Option<a>`|`Some(value)` containing the value at the top of the stack or `None` otherwise.|
+| type        | description                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Option<a>` | `Some(value)` containing the value at the top of the stack or `None` otherwise. |
 
 ### Stack.**push**
 
@@ -144,17 +144,17 @@ No other changes yet.
 </details>
 
 ```grain
-push : (value: a, stack: Stack<a>) => Void
+push: (value: a, stack: Stack<a>) => Void
 ```
 
 Adds a new item to the top of the stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`value`|`a`|The item to be added|
-|`stack`|`Stack<a>`|The stack being updated|
+| param   | type       | description             |
+| ------- | ---------- | ----------------------- |
+| `value` | `a`        | The item to be added    |
+| `stack` | `Stack<a>` | The stack being updated |
 
 ### Stack.**pop**
 
@@ -164,22 +164,22 @@ No other changes yet.
 </details>
 
 ```grain
-pop : (stack: Stack<a>) => Option<a>
+pop: (stack: Stack<a>) => Option<a>
 ```
 
 Removes the item at the top of the stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack being updated|
+| param   | type       | description             |
+| ------- | ---------- | ----------------------- |
+| `stack` | `Stack<a>` | The stack being updated |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Option<a>`|The element removed from the stack|
+| type        | description                        |
+| ----------- | ---------------------------------- |
+| `Option<a>` | The element removed from the stack |
 
 ### Stack.**clear**
 
@@ -189,16 +189,16 @@ No other changes yet.
 </details>
 
 ```grain
-clear : (stack: Stack<a>) => Void
+clear: (stack: Stack<a>) => Void
 ```
 
 Clears the stack by removing all of its elements
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to clear|
+| param   | type       | description        |
+| ------- | ---------- | ------------------ |
+| `stack` | `Stack<a>` | The stack to clear |
 
 ### Stack.**copy**
 
@@ -208,22 +208,160 @@ No other changes yet.
 </details>
 
 ```grain
-copy : (stack: Stack<a>) => Stack<a>
+copy: (stack: Stack<a>) => Stack<a>
 ```
 
 Produces a shallow copy of the input stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to copy|
+| param   | type       | description       |
+| ------- | ---------- | ----------------- |
+| `stack` | `Stack<a>` | The stack to copy |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Stack<a>`|A new stack containing the elements from the input|
+| type       | description                                        |
+| ---------- | -------------------------------------------------- |
+| `Stack<a>` | A new stack containing the elements from the input |
+
+### Stack.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList: (stack: Stack<a>) => List<a>
+```
+
+Creates a list containing the elements of a stack.
+
+Parameters:
+
+| param   | type       | description          |
+| ------- | ---------- | -------------------- |
+| `stack` | `Stack<a>` | The stack to convert |
+
+Returns:
+
+| type      | description                        |
+| --------- | ---------------------------------- |
+| `List<a>` | A list containing all stack values |
+
+Examples:
+
+```grain
+let stack = Stack.make()
+Stack.push(1, stack)
+Stack.push(2, stack)
+assert Stack.toList(stack) == [2, 1]
+```
+
+### Stack.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList: (list: List<a>) => Stack<a>
+```
+
+Creates a stack from a list.
+
+Parameters:
+
+| param  | type      | description         |
+| ------ | --------- | ------------------- |
+| `list` | `List<a>` | The list to convert |
+
+Returns:
+
+| type       | description                        |
+| ---------- | ---------------------------------- |
+| `Stack<a>` | A stack containing all list values |
+
+Examples:
+
+```grain
+let stack = Stack.fromList([3, 2, 1])
+assert Stack.pop(stack) == Some(3)
+assert Stack.pop(stack) == Some(2)
+assert Stack.pop(stack) == Some(1)
+assert Stack.pop(stack) == None
+```
+
+### Stack.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray: (stack: Stack<a>) => Array<a>
+```
+
+Creates an array containing the elements of a stack.
+
+Parameters:
+
+| param   | type       | description          |
+| ------- | ---------- | -------------------- |
+| `stack` | `Stack<a>` | The stack to convert |
+
+Returns:
+
+| type       | description                          |
+| ---------- | ------------------------------------ |
+| `Array<a>` | An array containing all stack values |
+
+Examples:
+
+```grain
+let stack = Stack.make()
+Stack.push(1, stack)
+Stack.push(2, stack)
+assert Stack.toArray(stack) == [> 2, 1]
+```
+
+### Stack.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray: (arr: Array<a>) => Stack<a>
+```
+
+Creates a stack from an array.
+
+Parameters:
+
+| param | type       | description          |
+| ----- | ---------- | -------------------- |
+| `arr` | `Array<a>` | The array to convert |
+
+Returns:
+
+| type       | description                         |
+| ---------- | ----------------------------------- |
+| `Stack<a>` | A stack containing all array values |
+
+Examples:
+
+```grain
+let s = Stack.fromArray([> 3, 2, 1])
+assert Stack.pop(s) == Some(3)
+assert Stack.pop(s) == Some(2)
+assert Stack.pop(s) == Some(1)
+assert Stack.pop(s) == None
+```
 
 ## Stack.Immutable
 
@@ -260,7 +398,7 @@ Functions and constants included in the Stack.Immutable module.
 </details>
 
 ```grain
-empty : ImmutableStack<a>
+empty: ImmutableStack<a>
 ```
 
 An empty stack.
@@ -280,22 +418,22 @@ An empty stack.
 </details>
 
 ```grain
-isEmpty : (stack: ImmutableStack<a>) => Bool
+isEmpty: (stack: ImmutableStack<a>) => Bool
 ```
 
 Checks if the given stack contains no items.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`ImmutableStack<a>`|The stack to check|
+| param   | type                | description        |
+| ------- | ------------------- | ------------------ |
+| `stack` | `ImmutableStack<a>` | The stack to check |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Bool`|`true` if the stack has no items or `false` otherwise|
+| type   | description                                           |
+| ------ | ----------------------------------------------------- |
+| `Bool` | `true` if the stack has no items or `false` otherwise |
 
 #### Stack.Immutable.**peek**
 
@@ -313,22 +451,22 @@ Returns:
 </details>
 
 ```grain
-peek : (stack: ImmutableStack<a>) => Option<a>
+peek: (stack: ImmutableStack<a>) => Option<a>
 ```
 
 Provides the value at the top of the stack, if it exists.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`ImmutableStack<a>`|The stack to inspect|
+| param   | type                | description          |
+| ------- | ------------------- | -------------------- |
+| `stack` | `ImmutableStack<a>` | The stack to inspect |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Option<a>`|`Some(value)` containing the value at the top of the stack or `None` otherwise.|
+| type        | description                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Option<a>` | `Some(value)` containing the value at the top of the stack or `None` otherwise. |
 
 #### Stack.Immutable.**push**
 
@@ -345,23 +483,23 @@ Returns:
 </details>
 
 ```grain
-push : (value: a, stack: ImmutableStack<a>) => ImmutableStack<a>
+push: (value: a, stack: ImmutableStack<a>) => ImmutableStack<a>
 ```
 
 Adds a new item to the top of the stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`value`|`a`|The item to be added|
-|`stack`|`ImmutableStack<a>`|The stack being updated|
+| param   | type                | description             |
+| ------- | ------------------- | ----------------------- |
+| `value` | `a`                 | The item to be added    |
+| `stack` | `ImmutableStack<a>` | The stack being updated |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`ImmutableStack<a>`|A new stack with the item added to the end|
+| type                | description                                |
+| ------------------- | ------------------------------------------ |
+| `ImmutableStack<a>` | A new stack with the item added to the end |
 
 #### Stack.Immutable.**pop**
 
@@ -378,22 +516,22 @@ Returns:
 </details>
 
 ```grain
-pop : (stack: ImmutableStack<a>) => ImmutableStack<a>
+pop: (stack: ImmutableStack<a>) => ImmutableStack<a>
 ```
 
 Removes the item at the top of the stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`ImmutableStack<a>`|The stack being updated|
+| param   | type                | description             |
+| ------- | ------------------- | ----------------------- |
+| `stack` | `ImmutableStack<a>` | The stack being updated |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`ImmutableStack<a>`|A new stack with the last item removed|
+| type                | description                            |
+| ------------------- | -------------------------------------- |
+| `ImmutableStack<a>` | A new stack with the last item removed |
 
 #### Stack.Immutable.**size**
 
@@ -410,20 +548,164 @@ Returns:
 </details>
 
 ```grain
-size : (stack: ImmutableStack<a>) => Number
+size: (stack: ImmutableStack<a>) => Number
 ```
 
 Computes the size of the input stack.
 
 Parameters:
 
-|param|type|description|
-|-----|----|-----------|
-|`stack`|`ImmutableStack<a>`|The stack to inspect|
+| param   | type                | description          |
+| ------- | ------------------- | -------------------- |
+| `stack` | `ImmutableStack<a>` | The stack to inspect |
 
 Returns:
 
-|type|description|
-|----|-----------|
-|`Number`|The count of the items in the stack|
+| type     | description                         |
+| -------- | ----------------------------------- |
+| `Number` | The count of the items in the stack |
+
+#### Stack.Immutable.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList: (stack: ImmutableStack<a>) => List<a>
+```
+
+Creates a list containing the elements of a stack.
+
+Parameters:
+
+| param   | type                | description          |
+| ------- | ------------------- | -------------------- |
+| `stack` | `ImmutableStack<a>` | The stack to convert |
+
+Returns:
+
+| type      | description                        |
+| --------- | ---------------------------------- |
+| `List<a>` | A list containing all stack values |
+
+Examples:
+
+```grain
+use Stack.{ module Immutable as Stack }
+let stack = Stack.empty
+let stack = Stack.push(1, stack)
+let stack = Stack.push(2, stack)
+assert Stack.toList(stack) == [2, 1]
+```
+
+#### Stack.Immutable.**fromList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromList: (list: List<a>) => ImmutableStack<a>
+```
+
+Creates a stack from a list.
+
+Parameters:
+
+| param  | type      | description         |
+| ------ | --------- | ------------------- |
+| `list` | `List<a>` | The list to convert |
+
+Returns:
+
+| type                | description                        |
+| ------------------- | ---------------------------------- |
+| `ImmutableStack<a>` | A stack containing all list values |
+
+Examples:
+
+```grain
+use Stack.{ module Immutable as Stack }
+let stack = Stack.fromList([2, 1])
+assert Stack.peek(stack) == Some(2)
+let stack = Stack.pop(stack)
+assert Stack.peek(stack) == Some(1)
+let stack = Stack.pop(stack)
+assert Stack.isEmpty(stack)
+```
+
+#### Stack.Immutable.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray: (stack: ImmutableStack<a>) => Array<a>
+```
+
+Creates an array containing the elements of a stack.
+
+Parameters:
+
+| param   | type                | description          |
+| ------- | ------------------- | -------------------- |
+| `stack` | `ImmutableStack<a>` | The stack to convert |
+
+Returns:
+
+| type       | description                          |
+| ---------- | ------------------------------------ |
+| `Array<a>` | An array containing all stack values |
+
+Examples:
+
+```grain
+use Stack.{ module Immutable as Stack }
+let stack = Stack.empty
+let stack = Stack.push(1, stack)
+let stack = Stack.push(2, stack)
+assert Stack.toArray(stack) == [> 2, 1]
+```
+
+#### Stack.Immutable.**fromArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.7.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+fromArray: (arr: Array<a>) => ImmutableStack<a>
+```
+
+Creates a stack from an array.
+
+Parameters:
+
+| param | type       | description          |
+| ----- | ---------- | -------------------- |
+| `arr` | `Array<a>` | The array to convert |
+
+Returns:
+
+| type                | description                         |
+| ------------------- | ----------------------------------- |
+| `ImmutableStack<a>` | A stack containing all array values |
+
+Examples:
+
+```grain
+use Stack.{ module Immutable as Stack }
+let stack = Stack.fromArray([> 2, 1])
+assert Stack.peek(stack) == Some(2)
+let stack = Stack.pop(stack)
+assert Stack.peek(stack) == Some(1)
+let stack = Stack.pop(stack)
+assert Stack.isEmpty(stack)
+```