README.md (4963B)
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 # iterDivide 22 23 > Create an [iterator][mdn-iterator-protocol] which performs element-wise division 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 iterDivide = require( '@stdlib/math/iter/ops/divide' ); 41 ``` 42 43 #### iterDivide( iter0, ...iterator ) 44 45 Returns an [iterator][mdn-iterator-protocol] which performs element-wise division 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 = iterDivide( it1, it2 ); 54 // returns <Object> 55 56 var v = it.next().value; 57 // returns 3.0 58 59 v = it.next().value; 60 // returns 0.5 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, 2.0 ] ); 77 78 var it = iterDivide( arr, 4.0 ); 79 // returns <Object> 80 81 var v = it.next().value; 82 // returns 0.25 83 84 v = it.next().value; 85 // returns 0.5 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 iterSineWave = require( '@stdlib/simulate/iter/sine-wave' ); 119 var iterDivide = require( '@stdlib/math/iter/ops/divide' ); 120 121 // Create an iterator which generates a sine wave: 122 var sine = iterSineWave({ 123 'period': 50, 124 'offset': 0, 125 'iter': 100 126 }); 127 128 // Create an iterator which scales the sine wave amplitude: 129 var it = iterDivide( sine, 10.0 ); 130 131 // Perform manual iteration... 132 var v; 133 while ( true ) { 134 v = it.next(); 135 if ( v.done ) { 136 break; 137 } 138 console.log( v.value ); 139 } 140 ``` 141 142 </section> 143 144 <!-- /.examples --> 145 146 <!-- 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. --> 147 148 <section class="references"> 149 150 </section> 151 152 <!-- /.references --> 153 154 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 155 156 <section class="links"> 157 158 [mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol 159 160 </section> 161 162 <!-- /.links -->