Usage

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

#### shuffle( arr\[, options] )

Shuffles elements of an array-like object.

`javascript
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.

`javascript
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.

`javascript
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.

`javascript
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.

`javascript
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.

`javascript
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
`