# Stack
> Stack data structure.
## Usage
```javascript
var stack = require( '@stdlib/utils/stack' );
```
#### stack()
Returns a `Stack` instance.
```javascript
var s = stack();
// returns
```
##### s.clear()
Clears a stack.
```javascript
var s = stack();
// returns
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Peek at the top value:
var v = s.first();
// returns 'bar'
// Examine the stack length:
var len = s.length;
// returns 2
// Clear all stack items:
s.clear();
// Peek at the top value:
v = s.first();
// returns undefined
// Examine the stack length:
len = s.length;
// returns 0
```
##### s.first()
Returns the top stack value (i.e., the value which is "first-out"). If the stack is currently empty, the returned value is `undefined`.
```javascript
var s = stack();
// returns
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Peek at the top value:
var v = s.first();
// returns 'bar'
```
##### s.iterator()
Returns an iterator for iterating over a stack. If an environment supports `Symbol.iterator`, the returned iterator is iterable.
```javascript
var s = stack();
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Create an iterator:
var it = s.iterator();
// Iterate over the stack...
var v = it.next().value;
// returns 'bar'
v = it.next().value;
// returns 'foo'
var bool = it.next().done;
// returns true
```
**Note**: in order to prevent confusion arising from stack mutation during iteration, a returned iterator **always** iterates over a stack "snapshot", which is defined as the list of stack elements at the time of `s.iterator()` invocation.
##### s.last()
Returns the bottom stack value (i.e., the value which is "last-out"). If the stack is currently empty, the returned value is `undefined`.
```javascript
var s = stack();
// returns
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Peek at the bottom value:
var v = s.last();
// returns 'foo'
```
##### s.length
Stack length.
```javascript
var s = stack();
// Examine the initial stack length:
var len = s.length;
// returns 0
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Retrieve the current stack length:
len = s.length;
// returns 2
```
##### s.pop()
Removes a value from the stack. If the stack is currently empty, the returned value is `undefined`.
```javascript
var s = stack();
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Remove the top value:
var v = s.pop();
// returns 'bar'
// Add a new value to the stack:
s.push( 'beep' );
// Remove the top value:
v = s.pop();
// returns 'beep'
```
##### s.push( value )
Adds a value to the stack.
```javascript
var s = stack();
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Remove the top value:
var v = s.pop();
// returns 'bar'
// Add a new value to the stack:
s.push( 'beep' );
// Remove the top value:
v = s.pop();
// returns 'beep'
```
##### s.toArray()
Returns an array of stack values.
```javascript
var s = stack();
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Get an array of stack values:
var vals = s.toArray();
// returns [ 'bar', 'foo' ]
```
**Note**: the order of the returned array is reverse stack insertion order (i.e., the "newest" stack elements come before the "oldest" stack elements).
##### s.toJSON()
Serializes a stack as JSON.
```javascript
var s = stack();
// Add values to the stack:
s.push( 'foo' ).push( 'bar' );
// Serialize to JSON:
var o = s.toJSON();
// returns { 'type': 'stack', 'data': [ 'bar', 'foo' ] }
```
**Note**: `JSON.stringify()` implicitly calls this method when stringifying a stack instance.
## Notes
- A stack is also known as a Last-In-First-Out (LIFO) queue.
## Examples
```javascript
var Stack = require( '@stdlib/utils/stack' );
var stack;
var iter;
var len;
var v;
var i;
// Create a new stack:
stack = new Stack();
// Add some values to the stack:
stack.push( 'foo' );
stack.push( 'bar' );
stack.push( 'beep' );
stack.push( 'boop' );
// Peek at the top and bottom stack values:
v = stack.first();
// returns 'boop'
v = stack.last();
// returns 'foo'
// Inspect the stack length:
len = stack.length;
// returns 4
// Remove the top value:
v = stack.pop();
// returns 'boop'
// Inspect the stack length:
len = stack.length;
// returns 3
// Iterate over the stack:
iter = stack.iterator();
for ( i = 0; i < len; i++ ) {
console.log( 'Stack value #%d: %s', i+1, iter.next().value );
}
// Clear the stack:
stack.clear();
// Inspect the stack length:
len = stack.length;
// returns 0
```