README.md (6650B)
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 # circarray2iterator 22 23 > Create an iterator which repeatedly iterates over the elements of an array-like object. 24 25 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <!-- Package usage documentation. --> 34 35 <section class="usage"> 36 37 ## Usage 38 39 ```javascript 40 var circarray2iterator = require( '@stdlib/array/to-circular-iterator' ); 41 ``` 42 43 #### circarray2iterator( src\[, options]\[, mapFcn\[, thisArg]] ) 44 45 Returns an iterator which repeatedly iterates over each element in an array-like `object`. 46 47 ```javascript 48 var it = circarray2iterator( [ 1, 2, 3, 4 ] ); 49 // returns <Object> 50 51 var v = it.next().value; 52 // returns 1 53 54 v = it.next().value; 55 // returns 2 56 57 v = it.next().value; 58 // returns 3 59 60 v = it.next().value; 61 // returns 4 62 63 v = it.next().value; 64 // returns 1 65 66 v = it.next().value; 67 // returns 2 68 69 v = it.next().value; 70 // returns 3 71 72 v = it.next().value; 73 // returns 4 74 75 // ... 76 ``` 77 78 The returned iterator protocol-compliant object has the following properties: 79 80 - **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. 81 - **return**: function which closes an iterator and returns a single (optional) argument in an iterator protocol-compliant object. 82 83 The function accepts the following `options`: 84 85 - **iter**: number of iterations. Default: `1e308`. 86 - **dir**: iteration direction. If set to `-1`, the iterator iterates over elements from right-to-left. Default: `1`. 87 88 To limit the number of iterations, set the `iter` option. 89 90 ```javascript 91 var opts = { 92 'iter': 5 93 }; 94 var it = circarray2iterator( [ 1, 2, 3, 4 ], opts ); 95 // returns <Object> 96 97 var v = it.next().value; 98 // returns 1 99 100 v = it.next().value; 101 // returns 2 102 103 v = it.next().value; 104 // returns 3 105 106 v = it.next().value; 107 // returns 4 108 109 v = it.next().value; 110 // returns 1 111 112 var bool = it.next().done; 113 // returns true 114 ``` 115 116 To iterate over elements from right to left, set the `dir` option to `-1`. 117 118 ```javascript 119 var opts = { 120 'dir': -1 121 }; 122 var it = circarray2iterator( [ 1, 2, 3, 4 ], opts ); 123 // returns <Object> 124 125 var v = it.next().value; 126 // returns 4 127 128 v = it.next().value; 129 // returns 3 130 131 v = it.next().value; 132 // returns 2 133 134 v = it.next().value; 135 // returns 1 136 137 v = it.next().value; 138 // returns 4 139 140 v = it.next().value; 141 // returns 3 142 143 // ... 144 ``` 145 146 To invoke a function for each `src` value, provide a callback function. 147 148 ```javascript 149 function fcn( v ) { 150 return v * 10.0; 151 } 152 153 var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn ); 154 // returns <Object> 155 156 var v = it.next().value; 157 // returns 10.0 158 159 v = it.next().value; 160 // returns 20.0 161 162 v = it.next().value; 163 // returns 30.0 164 165 // ... 166 ``` 167 168 The invoked function is provided four arguments: 169 170 - `value`: iterated value 171 - `index`: iterated value index 172 - `n`: iteration count 173 - `src`: source array-like object 174 175 ```javascript 176 function fcn( v, i ) { 177 return v * (i+1); 178 } 179 180 var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn ); 181 // returns <Object> 182 183 var v = it.next().value; 184 // returns 1 185 186 v = it.next().value; 187 // returns 4 188 189 v = it.next().value; 190 // returns 9 191 192 // ... 193 ``` 194 195 To set the callback function execution context, provide a `thisArg`. 196 197 ```javascript 198 function fcn( v ) { 199 this.count += 1; 200 return v * 10.0; 201 } 202 203 var ctx = { 204 'count': 0 205 }; 206 207 var it = circarray2iterator( [ 1, 2, 3, 4 ], fcn, ctx ); 208 // returns <Object> 209 210 var v = it.next().value; 211 // returns 10.0 212 213 v = it.next().value; 214 // returns 20.0 215 216 v = it.next().value; 217 // returns 30.0 218 219 var count = ctx.count; 220 // returns 3 221 ``` 222 223 </section> 224 225 <!-- /.usage --> 226 227 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 228 229 <section class="notes"> 230 231 ## Notes 232 233 - If an environment supports `Symbol.iterator`, the returned iterator is iterable. 234 - If provided a generic `array`, the returned iterator does **not** ignore holes. To achieve greater performance for sparse arrays, use a custom iterator. 235 - 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. 236 - 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. 237 238 </section> 239 240 <!-- /.notes --> 241 242 <!-- Package usage examples. --> 243 244 <section class="examples"> 245 246 ## Examples 247 248 <!-- eslint no-undef: "error" --> 249 250 ```javascript 251 var Float64Array = require( '@stdlib/array/float64' ); 252 var inmap = require( '@stdlib/utils/inmap' ); 253 var randu = require( '@stdlib/random/base/randu' ); 254 var circarray2iterator = require( '@stdlib/array/to-circular-iterator' ); 255 256 function scale( v, i, n ) { 257 return v * n; 258 } 259 260 // Create an array filled with random numbers: 261 var arr = inmap( new Float64Array( 10 ), randu ); 262 263 // Create an iterator from the array which scales iterated values: 264 var opts = { 265 'iter': arr.length * 10 266 }; 267 var it = circarray2iterator( arr, opts, scale ); 268 269 // Perform manual iteration... 270 var v; 271 while ( true ) { 272 v = it.next(); 273 if ( v.done ) { 274 break; 275 } 276 console.log( v.value ); 277 } 278 ``` 279 280 </section> 281 282 <!-- /.examples --> 283 284 <!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 285 286 <section class="references"> 287 288 </section> 289 290 <!-- /.references --> 291 292 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 293 294 <section class="links"> 295 296 </section> 297 298 <!-- /.links -->