time-to-botec/js/node_modules/@stdlib/utils/stack/README.md

Stack

Stack data structure.

Usage

var stack = require( '@stdlib/utils/stack' );

stack()

Returns a Stack instance.

var s = stack();
// returns <Stack>

s.clear()

Clears a stack.

var s = stack();
// returns <Stack>

// 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.

var s = stack();
// returns <Stack>

// 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.

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.

var s = stack();
// returns <Stack>

// 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.

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.

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.

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.

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.

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

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