README.md (4251B)
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 # itercuprod 22 23 > Create an [iterator][mdn-iterator-protocol] which iteratively computes a cumulative product. 24 25 <section class="intro"> 26 27 The cumulative product is defined as 28 29 <!-- <equation class="equation" label="eq:cumulative_product" align="center" raw="\begin{align*} p_0 &= x_0 \\ p_1 &= x_1 \cdot p_0 \\ p_2 &= x_2 \cdot p_1 \\ p_n &= x_n \cdot p_{n-1} = x_n \cdot \prod_{i=0}^{n-1} x_i \end{align*}" alt="Equation for the cumulative product."> --> 30 31 <div class="equation" align="center" data-raw-text="\begin{align*} p_0 &= x_0 \\ p_1 &= x_1 \cdot p_0 \\ p_2 &= x_2 \cdot p_1 \\ p_n &= x_n \cdot p_{n-1} = x_n \cdot \prod_{i=0}^{n-1} x_i \end{align*}" data-equation="eq:cumulative_product"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@e70489fe2d16d2496f77b516c791cf5c0c078ae1/lib/node_modules/@stdlib/stats/iter/cuprod/docs/img/equation_cumulative_product.svg" alt="Equation for the cumulative product."> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 </section> 39 40 <!-- /.intro --> 41 42 <!-- Package usage documentation. --> 43 44 <section class="usage"> 45 46 ## Usage 47 48 ```javascript 49 var itercuprod = require( '@stdlib/stats/iter/cuprod' ); 50 ``` 51 52 #### itercuprod( iterator ) 53 54 Returns an [iterator][mdn-iterator-protocol] which iteratively computes a cumulative product. 55 56 ```javascript 57 var array2iterator = require( '@stdlib/array/to-iterator' ); 58 59 var arr = array2iterator( [ 2.0, 1.0, 3.0, -7.0, -5.0 ] ); 60 var it = itercuprod( arr ); 61 62 var p = it.next().value; 63 // returns 2.0 64 65 p = it.next().value; 66 // returns 2.0 67 68 p = it.next().value; 69 // returns 6.0 70 71 p = it.next().value; 72 // returns -42.0 73 74 p = it.next().value; 75 // returns 210.0 76 ``` 77 78 </section> 79 80 <!-- /.usage --> 81 82 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 83 84 <section class="notes"> 85 86 ## Notes 87 88 - If an iterated value is non-numeric (including `NaN`), the function returns `NaN` for **all** future iterations. 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. 89 - For [iterators][mdn-iterator-protocol] which can generate many values or which may output large numbers, care should be taken to prevent overflow. 90 91 </section> 92 93 <!-- /.notes --> 94 95 <!-- Package usage examples. --> 96 97 <section class="examples"> 98 99 ## Examples 100 101 <!-- eslint no-undef: "error" --> 102 103 ```javascript 104 var runif = require( '@stdlib/random/iter/uniform' ); 105 var itercuprod = require( '@stdlib/stats/iter/cuprod' ); 106 107 // Create an iterator for generating uniformly distributed pseudorandom numbers: 108 var rand = runif( -10.0, 10.0, { 109 'seed': 1234, 110 'iter': 100 111 }); 112 113 // Create an iterator for iteratively computing a cumulative product: 114 var it = itercuprod( rand ); 115 116 // Perform manual iteration... 117 var v; 118 while ( true ) { 119 v = it.next(); 120 if ( typeof v.value === 'number' ) { 121 console.log( 'prod: %d', v.value ); 122 } 123 if ( v.done ) { 124 break; 125 } 126 } 127 ``` 128 129 </section> 130 131 <!-- /.examples --> 132 133 <!-- 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. --> 134 135 <section class="references"> 136 137 </section> 138 139 <!-- /.references --> 140 141 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 142 143 <section class="links"> 144 145 [mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol 146 147 </section> 148 149 <!-- /.links -->