README.md (3521B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 The Stdlib Authors. 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 19 --> 20 21 # Shuffle 22 23 > Shuffle elements of an array-like object. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var shuffle = require( '@stdlib/random/shuffle' ); 37 ``` 38 39 #### shuffle( arr\[, options] ) 40 41 Shuffles elements of an array-like object. 42 43 ```javascript 44 var arr = [ 1, 2, 3 ]; 45 var out = shuffle( arr ); 46 // e.g., returns [ 3, 1, 2 ] 47 ``` 48 49 The function accepts the following `options`: 50 51 - **copy**: `string` indicating whether to return a copy (`deep`,`shallow` or `none`). Default: `shallow`. 52 53 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`. 54 55 ```javascript 56 var arr = [ 1, 2, 3 ]; 57 var out = shuffle( arr, { 58 'copy': 'none' 59 }); 60 var bool = ( arr === out ); 61 // returns true 62 ``` 63 64 To return a deep copy, set the `copy` option to `deep`. 65 66 ```javascript 67 var obj = { 68 'beep': 'boop' 69 }; 70 var arr = [ [ obj ], [ obj ], [ obj ] ]; 71 72 // Deep copy: 73 var out = shuffle( arr, { 74 'copy': 'deep' 75 }); 76 var bool = ( arr === out ); 77 // returns false 78 79 bool = ( arr[2] === out[2] ); 80 // returns false 81 82 // Shallow copy: 83 out = shuffle( arr, { 84 'copy': 'shallow' 85 }); 86 bool = ( arr === out ); 87 // returns false 88 89 bool = ( arr[2] === out[2] ); 90 // returns true 91 ``` 92 93 #### shuffle.factory( \[options] ) 94 95 Returns a `function` to shuffle elements of `array`-like objects. 96 97 ```javascript 98 var myshuffle = shuffle.factory(); 99 ``` 100 101 The function accepts the following `options`: 102 103 - **copy**: `string` specifying the default copy option (`deep`,`shallow` or `none`). Default: `shallow`. 104 - **seed**: pseudorandom number generator seed. 105 106 To seed the underlying pseudorandom number generator, set the `seed` option. 107 108 ```javascript 109 var myshuffle = shuffle.factory({ 110 'seed': 239 111 }); 112 113 var out = myshuffle( [ 0, 1, 2, 3, 4 ] ); 114 // e.g., returns [ 3, 4, 1, 0, 2 ] 115 ``` 116 117 By default, the returned functions create shallow copies when shuffling. To override the default `copy` strategy, set the `copy` option. 118 119 ```javascript 120 var myshuffle = shuffle.factory({ 121 'copy': 'none', 122 'seed': 867 123 }); 124 125 // Created shuffle function mutates input array by default: 126 var arr = [ 1, 2, 3, 4, 5, 6 ]; 127 var out = myshuffle( arr ); 128 var bool = ( arr === out ); 129 // returns true 130 131 // Default option can be overridden: 132 arr = [ 1, 2, 3, 4 ]; 133 out = myshuffle( arr, { 134 'copy': 'shallow' 135 }); 136 bool = ( arr === out ); 137 // returns false 138 ``` 139 140 </section> 141 142 <!-- /.usage --> 143 144 <section class="examples"> 145 146 ## Examples 147 148 <!-- eslint no-undef: "error" --> 149 150 ```javascript 151 var shuffle = require( '@stdlib/random/shuffle' ); 152 153 var result; 154 var data; 155 var i; 156 157 data = new Array( 20 ); 158 for ( i = 0; i < data.length; i++ ) { 159 data[ i ] = i; 160 } 161 162 for ( i = 0; i < 10; i++ ) { 163 result = shuffle( data ); 164 console.log( result ); 165 } 166 ``` 167 168 </section> 169 170 <!-- /.examples --> 171 172 <section class="links"> 173 174 </section> 175 176 <!-- /.links -->