README.md (5056B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 # iterMap 22 23 > Create an [iterator][mdn-iterator-protocol] which invokes a unary function accepting a single numeric argument for each iterated value. 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 iterMap = require( '@stdlib/math/iter/tools/map' ); 41 ``` 42 43 #### iterMap( iterator, fcn\[, options] ) 44 45 Returns an [iterator][mdn-iterator-protocol] which invokes a unary `function` accepting a single numeric argument for each iterated value. 46 47 ```javascript 48 var array2iterator = require( '@stdlib/array/to-iterator' ); 49 var sin = require( '@stdlib/math/base/special/sin' ); 50 51 var it = iterMap( array2iterator( [ 1, 2, 3, 4 ] ), sin ); 52 // returns <Object> 53 54 var r = it.next().value; 55 // returns <number> 56 57 r = it.next().value; 58 // returns <number> 59 60 r = it.next().value; 61 // returns <number> 62 63 // ... 64 ``` 65 66 The returned [iterator][mdn-iterator-protocol] protocol-compliant object has the following properties: 67 68 - **next**: function which returns an [iterator][mdn-iterator-protocol] 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. 69 - **return**: function which closes an [iterator][mdn-iterator-protocol] and returns a single (optional) argument in an [iterator][mdn-iterator-protocol] protocol-compliant object. 70 71 The invoked `function` is provided one argument: 72 73 - `value`: iterated value 74 75 ```javascript 76 var array2iterator = require( '@stdlib/array/to-iterator' ); 77 78 function fcn( v ) { 79 return v + 10; 80 } 81 82 var it = iterMap( array2iterator( [ 1, 2, 3, 4 ] ), fcn ); 83 // returns <Object> 84 85 var r = it.next().value; 86 // returns 11 87 88 r = it.next().value; 89 // returns 12 90 91 r = it.next().value; 92 // returns 13 93 94 // ... 95 ``` 96 97 The function supports the following `options`: 98 99 - **invalid**: return value when an input [iterator][mdn-iterator-protocol] yields a non-numeric value. Default: `NaN`. 100 101 By default, the function returns an [iterator][mdn-iterator-protocol] which returns `NaN` when an input [iterator][mdn-iterator-protocol] yields a non-numeric value. To specify a different return value, set the `invalid` option. 102 103 ```javascript 104 var array2iterator = require( '@stdlib/array/to-iterator' ); 105 var sin = require( '@stdlib/math/base/special/sin' ); 106 107 var opts = { 108 'invalid': null 109 }; 110 var it = iterMap( array2iterator( [ '1', '2', '3' ] ), sin, opts ); 111 // returns <Object> 112 113 var v = it.next().value; 114 // returns null 115 116 v = it.next().value; 117 // returns null 118 119 // ... 120 ``` 121 122 </section> 123 124 <!-- /.usage --> 125 126 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 127 128 <section class="notes"> 129 130 ## Notes 131 132 - If an environment supports `Symbol.iterator` **and** a provided [iterator][mdn-iterator-protocol] is iterable, the returned [iterator][mdn-iterator-protocol] is iterable. 133 134 </section> 135 136 <!-- /.notes --> 137 138 <!-- Package usage examples. --> 139 140 <section class="examples"> 141 142 ## Examples 143 144 <!-- eslint no-undef: "error" --> 145 146 ```javascript 147 var randu = require( '@stdlib/random/iter/randu' ); 148 var sin = require( '@stdlib/math/base/special/sin' ); 149 var iterMap = require( '@stdlib/math/iter/tools/map' ); 150 151 // Create a seeded iterator for generating pseudorandom numbers: 152 var rand = randu({ 153 'seed': 1234, 154 'iter': 10 155 }); 156 157 // Create an iterator which consumes the pseudorandom number iterator: 158 var it = iterMap( rand, sin ); 159 160 // Perform manual iteration... 161 var r; 162 while ( true ) { 163 r = it.next(); 164 if ( r.done ) { 165 break; 166 } 167 console.log( r.value ); 168 } 169 ``` 170 171 </section> 172 173 <!-- /.examples --> 174 175 <!-- 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. --> 176 177 <section class="references"> 178 179 </section> 180 181 <!-- /.references --> 182 183 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 184 185 <section class="links"> 186 187 [mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol 188 189 </section> 190 191 <!-- /.links -->