time-to-botec/js/node_modules/@stdlib/array/to-circular-iterator/README.md

circarray2iterator

Create an iterator which repeatedly iterates over the elements of an array-like object.

Usage

var circarray2iterator = require( '@stdlib/array/to-circular-iterator' );

circarray2iterator( src[, options][, mapFcn[, thisArg]] )

Returns an iterator which repeatedly iterates over each element in an array-like object.

var it = circarray2iterator( [ 1, 2, 3, 4 ] );
// returns <Object>

var v = it.next().value;
// returns 1

v = it.next().value;
// returns 2

v = it.next().value;
// returns 3

v = it.next().value;
// returns 4

v = it.next().value;
// returns 1

v = it.next().value;
// returns 2

v = it.next().value;
// returns 3

v = it.next().value;
// returns 4

// ...

The returned iterator protocol-compliant object has the following properties:

• next: function which returns an iterator protocol-compliant object containing the next iterated value (if one exists) assigned to a value property and a done property having a boolean value indicating whether the iterator is finished.
• return: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object.

The function accepts the following options:

• iter: number of iterations. Default: 1e308.
• dir: iteration direction. If set to -1, the iterator iterates over elements from right-to-left. Default: 1.

To limit the number of iterations, set the iter option.

var opts = {
    'iter': 5
};
var it = circarray2iterator( [ 1, 2, 3, 4 ], opts );
// returns <Object>

var v = it.next().value;
// returns 1

v = it.next().value;
// returns 2

v = it.next().value;
// returns 3

v = it.next().value;
// returns 4

v = it.next().value;
// returns 1

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

To iterate over elements from right to left, set the dir option to -1.

var opts = {
    'dir': -1
};
var it = circarray2iterator( [ 1, 2, 3, 4 ], opts );
// returns <Object>

var v = it.next().value;
// returns 4

v = it.next().value;
// returns 3

v = it.next().value;
// returns 2

v = it.next().value;
// returns 1

v = it.next().value;
// returns 4

v = it.next().value;
// returns 3

// ...

To invoke a function for each src value, provide a callback function.

function fcn( v ) {
    return v * 10.0;
}

var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn );
// returns <Object>

var v = it.next().value;
// returns 10.0

v = it.next().value;
// returns 20.0

v = it.next().value;
// returns 30.0

// ...

The invoked function is provided four arguments:

• value: iterated value
• index: iterated value index
• n: iteration count
• src: source array-like object

function fcn( v, i ) {
    return v * (i+1);
}

var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn );
// returns <Object>

var v = it.next().value;
// returns 1

v = it.next().value;
// returns 4

v = it.next().value;
// returns 9

// ...

To set the callback function execution context, provide a thisArg.

function fcn( v ) {
    this.count += 1;
    return v * 10.0;
}

var ctx = {
    'count': 0
};

var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn, ctx );
// returns <Object>

var v = it.next().value;
// returns 10.0

v = it.next().value;
// returns 20.0

v = it.next().value;
// returns 30.0

var count = ctx.count;
// returns 3

Notes

• If an environment supports Symbol.iterator, the returned iterator is iterable.
• If provided a generic array, the returned iterator does not ignore holes. To achieve greater performance for sparse arrays, use a custom iterator.
• A returned iterator does not copy a provided array-like object. To ensure iterable reproducibility, copy a provided array-like object before creating an iterator. Otherwise, any changes to the contents of an array-like object will be reflected in the returned iterator.
• In environments supporting Symbol.iterator, the function explicitly does not invoke an array's @@iterator method, regardless of whether this method is defined. To convert an array to an implementation defined iterator, invoke this method directly.

Examples

var Float64Array = require( '@stdlib/array/float64' );
var inmap = require( '@stdlib/utils/inmap' );
var randu = require( '@stdlib/random/base/randu' );
var circarray2iterator = require( '@stdlib/array/to-circular-iterator' );

function scale( v, i, n ) {
    return v * n;
}

// Create an array filled with random numbers:
var arr = inmap( new Float64Array( 10 ), randu );

// Create an iterator from the array which scales iterated values:
var opts = {
    'iter': arr.length * 10
};
var it = circarray2iterator( arr, opts, scale );

// Perform manual iteration...
var v;
while ( true ) {
    v = it.next();
    if ( v.done ) {
        break;
    }
    console.log( v.value );
}