@grain/stdlib 0.6.5 → 0.7.0

package/stack.md

@@ -41,12 +41,12 @@ 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:
@@ -69,7 +69,7 @@ No other changes yet.
 </details>
 
 ```grain
-isEmpty : (stack: Stack<a>) => Bool
+isEmpty: (stack: Stack<a>) => Bool
 ```
 
 Checks if the given stack contains no items.
@@ -94,7 +94,7 @@ No other changes yet.
 </details>
 
 ```grain
-size : (stack: Stack<a>) => Number
+size: (stack: Stack<a>) => Number
 ```
 
 Computes the size of the input stack.
@@ -119,7 +119,7 @@ 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.
@@ -144,7 +144,7 @@ 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.
@@ -164,7 +164,7 @@ 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.
@@ -189,7 +189,7 @@ 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
@@ -208,7 +208,7 @@ 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.
@@ -225,6 +225,144 @@ Returns:
 |----|-----------|
 |`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
 
 An immutable stack implementation.
@@ -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,7 +418,7 @@ An empty stack.
 </details>
 
 ```grain
-isEmpty : (stack: ImmutableStack<a>) => Bool
+isEmpty: (stack: ImmutableStack<a>) => Bool
 ```
 
 Checks if the given stack contains no items.
@@ -313,7 +451,7 @@ 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.
@@ -345,7 +483,7 @@ 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.
@@ -378,7 +516,7 @@ Returns:
 </details>
 
 ```grain
-pop : (stack: ImmutableStack<a>) => ImmutableStack<a>
+pop: (stack: ImmutableStack<a>) => ImmutableStack<a>
 ```
 
 Removes the item at the top of the stack.
@@ -410,7 +548,7 @@ Returns:
 </details>
 
 ```grain
-size : (stack: ImmutableStack<a>) => Number
+size: (stack: ImmutableStack<a>) => Number
 ```
 
 Computes the size of the input stack.
@@ -427,3 +565,147 @@ Returns:
 |----|-----------|
 |`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)
+```
+