README.md (4971B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2019 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 # iterMod 22 23 > Create an [iterator][mdn-iterator-protocol] which performs an element-wise modulo operation of two or more [iterators][mdn-iterator-protocol]. 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 iterMod = require( '@stdlib/math/iter/ops/mod' ); 41 ``` 42 43 #### iterMod( iter0, ...iterator ) 44 45 Returns an [iterator][mdn-iterator-protocol] which performs an element-wise modulo operation of two or more [iterators][mdn-iterator-protocol]. 46 47 ```javascript 48 var array2iterator = require( '@stdlib/array/to-iterator' ); 49 50 var it1 = array2iterator( [ 3.0, -2.0 ] ); 51 var it2 = array2iterator( [ 1.0, 4.0 ] ); 52 53 var it = iterMod( it1, it2 ); 54 // returns <Object> 55 56 var v = it.next().value; 57 // returns 0.0 58 59 v = it.next().value; 60 // returns -2.0 61 62 var bool = it.next().done; 63 // returns true 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][mdn-iterator-protocol] 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 If provided a numeric value as an [`iterator`][mdn-iterator-protocol] argument, the value is broadcast as an **infinite** [iterator][mdn-iterator-protocol] which **always** returns the provided value. 72 73 ```javascript 74 var array2iterator = require( '@stdlib/array/to-iterator' ); 75 76 var arr = array2iterator( [ 1.0, 7.0 ] ); 77 78 var it = iterMod( arr, 4.0 ); 79 // returns <Object> 80 81 var v = it.next().value; 82 // returns 1.0 83 84 v = it.next().value; 85 // returns 3.0 86 87 var bool = it.next().done; 88 // returns true 89 ``` 90 91 </section> 92 93 <!-- /.usage --> 94 95 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 96 97 <section class="notes"> 98 99 ## Notes 100 101 - If an iterated value is non-numeric (including `NaN`), the returned [iterator][mdn-iterator-protocol] returns `NaN`. If non-numeric iterated values are possible, you are advised to provide an [`iterator`][mdn-iterator-protocol] which type checks and handles non-numeric values accordingly. 102 - The length of the returned [iterator][mdn-iterator-protocol] is equal to the length of the shortest provided [iterator][mdn-iterator-protocol]. In other words, the returned [iterator][mdn-iterator-protocol] ends once **one** of the provided [iterators][mdn-iterator-protocol] ends. 103 - If an environment supports `Symbol.iterator` **and** provided [iterators][mdn-iterator-protocol] are iterable, the returned [iterator][mdn-iterator-protocol] is iterable. 104 105 </section> 106 107 <!-- /.notes --> 108 109 <!-- Package usage examples. --> 110 111 <section class="examples"> 112 113 ## Examples 114 115 <!-- eslint no-undef: "error" --> 116 117 ```javascript 118 var iterDiscreteUniform = require( '@stdlib/random/iter/discrete-uniform' ); 119 var iterMod = require( '@stdlib/math/iter/ops/mod' ); 120 121 // Create an iterator which generates pseudorandom integers: 122 var rand = iterDiscreteUniform( 0, 100, { 123 'iter': 100 124 }); 125 126 // Create an iterator which performs an element-wise modulo operation: 127 var it = iterMod( rand, 10 ); 128 129 // Perform manual iteration... 130 var v; 131 while ( true ) { 132 v = it.next(); 133 if ( v.done ) { 134 break; 135 } 136 console.log( v.value ); 137 } 138 ``` 139 140 </section> 141 142 <!-- /.examples --> 143 144 <!-- 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. --> 145 146 <section class="references"> 147 148 </section> 149 150 <!-- /.references --> 151 152 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 153 154 <section class="links"> 155 156 [mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol 157 158 </section> 159 160 <!-- /.links -->