FIFO

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

    Usage

    var fifo = require( '@stdlib/utils/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.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.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.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/utils/fifo' );
    
    var queue;
    var iter;
    var len;
    var v;
    var i;
    
    // Create a new FIFO queue:
    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:
    v = queue.first();
    // returns 'foo'
    
    v = queue.last();
    // returns 'boop'
    
    // Inspect the queue length:
    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:
    iter = queue.iterator();
    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