@grain/stdlib 0.5.12 → 0.6.0

package/stack.md

@@ -2,9 +2,11 @@
 title: Stack
 ---
 
-> **Deprecated:** This module will be renamed to ImmutableStack in the v0.6.0 release of Grain.
+A stack is a LIFO (last-in-first-out) data structure where new
+values are added, retrieved, and removed from the end.
 
-An immutable stack implementation. A stack is a LIFO (last-in-first-out) data structure where new values are added, retrieved, and removed from the end.
+The default implementation is mutable, but an immutable stack
+implementation is available in the `Immutable` submodule.
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.3.0</code></summary>
@@ -12,7 +14,7 @@ No other changes yet.
 </details>
 
 ```grain
-import Stack from "stack"
+from "stack" include Stack
 ```
 
 ## Types
@@ -25,55 +27,260 @@ Type declarations included in the Stack module.
 type Stack<a>
 ```
 
-Stacks are immutable data structures that store their data in a List.
+A mutable LIFO (last-in-first-out) data structure.
 
 ## Values
 
 Functions and constants included in the Stack module.
 
-### Stack.**empty**
+### Stack.**make**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.5.4</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-empty : Stack<a>
+make : (?size: Number) => Stack<a>
 ```
 
-An empty stack.
+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
+default size.
 
-### Stack.**make**
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`?size`|`Number`|The initial storage size of the stack|
 
-> **Deprecated:** This will be removed in the v0.6.0 release of Grain.
+Returns:
+
+|type|description|
+|----|-----------|
+|`Stack<a>`|An empty stack|
+
+### Stack.**isEmpty**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-make : () -> Stack<a>
+isEmpty : (stack: Stack<a>) => Bool
 ```
 
-Creates a new stack.
+Checks if the given stack contains no items.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`stack`|`Stack<a>`|The stack to check|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Stack<a>`|An empty stack|
+|`Bool`|`true` if the stack has no items or `false` otherwise|
 
-### Stack.**isEmpty**
+### Stack.**size**
 
 <details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+size : (stack: Stack<a>) => Number
+```
+
+Computes the size of the input stack.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`stack`|`Stack<a>`|The stack to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Number`|The count of the items in the stack|
+
+### Stack.**peek**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+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|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` containing the value at the top of the stack or `None` otherwise.|
+
+### Stack.**push**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
 No other changes yet.
 </details>
 
 ```grain
-isEmpty : Stack<a> -> Bool
+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|
+
+### Stack.**pop**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+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|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|The element removed from the stack|
+
+### Stack.**clear**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+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|
+
+### Stack.**copy**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+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|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Stack<a>`|A new stack containing the elements from the input|
+
+## Stack.Immutable
+
+An immutable stack implementation.
+
+### Types
+
+Type declarations included in the Stack.Immutable module.
+
+#### Stack.Immutable.**ImmutableStack**
+
+```grain
+type ImmutableStack<a>
+```
+
+ImmutableStacks are immutable data structures that store their data in a List.
+
+### Values
+
+Functions and constants included in the Stack.Immutable module.
+
+#### Stack.Immutable.**empty**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.4</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+empty : ImmutableStack<a>
+```
+
+An empty stack.
+
+#### Stack.Immutable.**isEmpty**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.0</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+isEmpty : (stack: ImmutableStack<a>) => Bool
 ```
 
 Checks if the given stack contains no items.
@@ -82,7 +289,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to check|
+|`stack`|`ImmutableStack<a>`|The stack to check|
 
 Returns:
 
@@ -90,22 +297,23 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the stack has no items or `false` otherwise|
 
-### Stack.**peek**
+#### Stack.Immutable.**peek**
 
 <details>
-<summary>Added in <code>0.3.0</code></summary>
+<summary>Added in <code>0.6.0</code></summary>
 <table>
 <thead>
 <tr><th>version</th><th>changes</th></tr>
 </thead>
 <tbody>
+<tr><td><code>0.3.0</code></td><td>Originally a module root API</td></tr>
 <tr><td><code>0.3.1</code></td><td>Rename from `head` to `peek`</td></tr>
 </tbody>
 </table>
 </details>
 
 ```grain
-peek : Stack<a> -> Option<a>
+peek : (stack: ImmutableStack<a>) => Option<a>
 ```
 
 Provides the value at the top of the stack, if it exists.
@@ -114,7 +322,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to inspect|
+|`stack`|`ImmutableStack<a>`|The stack to inspect|
 
 Returns:
 
@@ -122,15 +330,22 @@ Returns:
 |----|-----------|
 |`Option<a>`|`Some(value)` containing the value at the top of the stack or `None` otherwise.|
 
-### Stack.**push**
+#### Stack.Immutable.**push**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.0</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-push : (a, Stack<a>) -> Stack<a>
+push : (value: a, stack: ImmutableStack<a>) => ImmutableStack<a>
 ```
 
 Adds a new item to the top of the stack.
@@ -140,23 +355,30 @@ Parameters:
 |param|type|description|
 |-----|----|-----------|
 |`value`|`a`|The item to be added|
-|`stack`|`Stack<a>`|The stack being updated|
+|`stack`|`ImmutableStack<a>`|The stack being updated|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Stack<a>`|A new stack with the item added to the end|
+|`ImmutableStack<a>`|A new stack with the item added to the end|
 
-### Stack.**pop**
+#### Stack.Immutable.**pop**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.0</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.0</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-pop : Stack<a> -> Stack<a>
+pop : (stack: ImmutableStack<a>) => ImmutableStack<a>
 ```
 
 Removes the item at the top of the stack.
@@ -165,23 +387,30 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`stack`|`Stack<a>`|The stack being updated|
+|`stack`|`ImmutableStack<a>`|The stack being updated|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Stack<a>`|A new stack with the last item removed|
+|`ImmutableStack<a>`|A new stack with the last item removed|
 
-### Stack.**size**
+#### Stack.Immutable.**size**
 
-<details disabled>
-<summary tabindex="-1">Added in <code>0.3.2</code></summary>
-No other changes yet.
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.3.2</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-size : Stack<a> -> Number
+size : (stack: ImmutableStack<a>) => Number
 ```
 
 Computes the size of the input stack.
@@ -190,7 +419,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`stack`|`Stack<a>`|The stack to inspect|
+|`stack`|`ImmutableStack<a>`|The stack to inspect|
 
 Returns: