Skip to content

README.md

Latest commit

 

History

History
466 lines (310 loc) · 9.13 KB

README.md

File metadata and controls

466 lines (310 loc) · 9.13 KB

FIFO

First-in-first-out (FIFO) queue.

Usage

var fifo = require( '@stdlib/dstructs/fifo' );

fifo()

Returns a new first-in-first-out (FIFO) queue instance.

var queue = fifo();
// returns <FIFO>
queue.clear()

Clears a queue.

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Peek at the first value:
var v = queue.first();
// returns 'foo'

// Examine the queue length:
var len = queue.length;
// returns 2

// Clear all queue items:
queue.clear();

// Peek at the first value:
v = queue.first();
// returns undefined

// Examine the queue length:
len = queue.length;
// returns 0
queue.every( predicate[, thisArg] )

Tests whether all elements in a queue pass a test implemented by a predicate function.

// Test whether all elements are greater than 0:
function predicate( v ) {
    return v > 0;
}

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 1 ).push( 2 ).push( 3 );

var bool = queue.every( predicate );
// returns true

The predicate function is provided three arguments:

  • value: current queue element.
  • index: current queue element index.
  • q: the queue on which the method was called.

To set the function execution context, provide a thisArg.

function predicate( v ) {
    this.count += 1;
    return v > 0;
}

// Create a queue:
var queue = fifo();

// Add values to the queue:
queue.push( 1 ).push( 2 ).push( 3 );

// Define an execution context:
var ctx = {
    'count': 0
};

// Test whether all elements are greater than 0:
var bool = queue.every( predicate, ctx );
// returns true

var n = ctx.count;
// returns 3
queue.first()

Returns the "oldest" queue value (i.e., the value which is "first-out"). If the queue is currently empty, the returned value is undefined.

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Peek at the first value:
var v = queue.first();
// returns 'foo'
queue.get( index )

Returns a queue element located at a nonnegative integer position (index) i.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' ).push( 'baz' );

// Access elements by index via the accessor protocol:
var v = queue.get( 0 );
// returns 'foo'

v = queue.get( 1 );
// returns 'bar'

v = queue.get( 2 );
// returns 'baz'

If provided an out-of-bounds index, the method returns undefined.

var queue = fifo();

// Out-of-bounds indices return undefined:
var v = queue.get( 10 );
// returns undefined
queue.iterator()

Returns an iterator for iterating over a queue. If an environment supports Symbol.iterator, the returned iterator is iterable.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Create an iterator:
var it = queue.iterator();

// Iterate over the queue...
var v = it.next().value;
// returns 'foo'

v = it.next().value;
// returns 'bar'

var bool = it.next().done;
// returns true

Note: in order to prevent confusion arising from queue mutation during iteration, a returned iterator always iterates over a queue "snapshot", which is defined as the list of queue elements at the time of queue.iterator() invocation.

queue.last()

Returns the "newest" queue value (i.e., the value which is "last-out"). If the queue is currently empty, the returned value is undefined.

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Peek at the last value:
var v = queue.last();
// returns 'bar'
queue.length

Queue length.

var queue = fifo();

// Examine the initial queue length:
var len = queue.length;
// returns 0

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Retrieve the current queue length:
len = queue.length;
// returns 2
queue.pop()

Removes a value from the queue. If the queue is currently empty, the returned value is undefined.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Remove the first value:
var v = queue.pop();
// returns 'foo'

// Add a new value to the queue:
queue.push( 'beep' );

// Remove the "oldest" queue value:
v = queue.pop();
// returns 'bar'
queue.push( value )

Adds a value to the queue.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Remove the first value:
var v = queue.pop();
// returns 'foo'

// Add a new value to the queue:
queue.push( 'beep' );

// Remove the "oldest" queue value:
v = queue.pop();
// returns 'bar'
queue.set( value, index )

Sets a queue element at a specified index.

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' ).push( 'baz' );

// Set elements by index:
queue.set( 'beep', 0 );
var v = queue.get( 0 );
// returns 'beep'

queue.set( 'boop', 1 );
v = queue.get( 1 );
// returns 'boop'

By default, the method sets queue elements starting at position (index) i = 0. To set elements starting elsewhere in the queue, provide an index argument i.

var queue = fifo();
// returns <FIFO>

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' ).push( 'baz' );

// By default, sets element at index 0:
queue.set( 'beep' );
var v = queue.get( 0 );
// returns 'beep'

// Set element at a specified index:
queue.set( 'boop', 1 );

v = queue.get( 1 );
// returns 'boop'
queue.toArray()

Returns an array of queue values.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Get an array of queue values:
var vals = queue.toArray();
// returns [ 'foo', 'bar' ]
queue.toJSON()

Serializes a queue as JSON.

var queue = fifo();

// Add values to the queue:
queue.push( 'foo' ).push( 'bar' );

// Serialize to JSON:
var o = queue.toJSON();
// returns { 'type': 'fifo', 'data': [ 'foo', 'bar' ] }

Note: JSON.stringify() implicitly calls this method when stringifying a queue instance.

Examples

var fifo = require( '@stdlib/dstructs/fifo' );

// Create a new FIFO queue:
var queue = fifo();

// Add some values to the queue:
queue.push( 'foo' );
queue.push( 'bar' );
queue.push( 'beep' );
queue.push( 'boop' );

// Peek at the first and last queue values:
var v = queue.first();
// returns 'foo'

v = queue.last();
// returns 'boop'

// Inspect the queue length:
var len = queue.length;
// returns 4

// Remove the "oldest" queue value:
v = queue.pop();
// returns 'foo'

// Inspect the queue length:
len = queue.length;
// returns 3

// Iterate over the queue:
var iter = queue.iterator();
var i;
for ( i = 0; i < len; i++ ) {
    console.log( 'Queue value #%d: %s', i+1, iter.next().value );
}

// Clear the queue:
queue.clear();

// Inspect the queue length:
len = queue.length;
// returns 0

See Also