time-to-botec/squiggle/node_modules/@stdlib/random/shuffle/README.md

Shuffle

Shuffle elements of an array-like object.

Usage

var shuffle = require( '@stdlib/random/shuffle' );

shuffle( arr[, options] )

Shuffles elements of an array-like object.

var arr = [ 1, 2, 3 ];
var out = shuffle( arr );
// e.g., returns [ 3, 1, 2 ]

The function accepts the following options:

• copy: string indicating whether to return a copy (deep,shallow or none). Default: shallow.

By default, the function returns a shallow copy. To mutate the input array (e.g., when input values can be discarded or when optimizing memory usage), set copy to none.

var arr = [ 1, 2, 3 ];
var out = shuffle( arr, {
    'copy': 'none'
});
var bool = ( arr === out );
// returns true

To return a deep copy, set the copy option to deep.

var obj = {
    'beep': 'boop'
};
var arr = [ [ obj ], [ obj ], [ obj ] ];

// Deep copy:
var out = shuffle( arr, {
    'copy': 'deep'
});
var bool = ( arr === out );
// returns false

bool = ( arr[2] === out[2] );
// returns false

// Shallow copy:
out = shuffle( arr, {
    'copy': 'shallow'
});
bool = ( arr === out );
// returns false

bool = ( arr[2] === out[2] );
// returns true

shuffle.factory( [options] )

Returns a function to shuffle elements of array-like objects.

var myshuffle = shuffle.factory();

The function accepts the following options:

• copy: string specifying the default copy option (deep,shallow or none). Default: shallow.
• seed: pseudorandom number generator seed.

To seed the underlying pseudorandom number generator, set the seed option.

var myshuffle = shuffle.factory({
    'seed': 239
});

var out = myshuffle( [ 0, 1, 2, 3, 4 ] );
// e.g., returns [ 3, 4, 1, 0, 2 ]

By default, the returned functions create shallow copies when shuffling. To override the default copy strategy, set the copy option.

var myshuffle = shuffle.factory({
    'copy': 'none',
    'seed': 867
});

// Created shuffle function mutates input array by default:
var arr = [ 1, 2, 3, 4, 5, 6 ];
var out = myshuffle( arr );
var bool = ( arr === out );
// returns true

// Default option can be overridden:
arr = [ 1, 2, 3, 4 ];
out = myshuffle( arr, {
    'copy': 'shallow'
});
bool = ( arr === out );
// returns false

Examples

var shuffle = require( '@stdlib/random/shuffle' );

var result;
var data;
var i;

data = new Array( 20 );
for ( i = 0; i < data.length; i++ ) {
    data[ i ] = i;
}

for ( i = 0; i < 10; i++ ) {
    result = shuffle( data );
    console.log( result );
}