README.md (7271B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2021 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 <!-- lint disable maximum-heading-length --> 22 23 # mapBy 24 25 > Apply a unary function to each element retrieved from a strided input array according to a callback function and assign each result to an element in a strided output array. 26 27 <section class="intro"> 28 29 </section> 30 31 <!-- /.intro --> 32 33 <section class="usage"> 34 35 ## Usage 36 37 ```javascript 38 var mapBy = require( '@stdlib/strided/base/map-by' ); 39 ``` 40 41 #### mapBy( N, x, strideX, y, strideY, fcn, clbk\[, thisArg] ) 42 43 Applies a unary function to each element retrieved from a strided input array according to a callback function and assigns each result to an element in a strided output array. 44 45 ```javascript 46 var abs = require( '@stdlib/math/base/special/abs' ); 47 48 function accessor( v ) { 49 return v * 2.0; 50 } 51 52 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ]; 53 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 54 55 mapBy( x.length, x, 1, y, 1, abs, accessor ); 56 // y => [ 4.0, 2.0, 6.0, 10.0, 8.0, 0.0, 2.0, 6.0 ] 57 ``` 58 59 The function accepts the following arguments: 60 61 - **N**: number of indexed elements. 62 - **x**: input [`Array`][mdn-array], [`typed array`][mdn-typed-array], or an array-like object (excluding strings and functions). 63 - **strideX**: index increment for `x`. 64 - **y**: output [`Array`][mdn-array], [`typed array`][mdn-typed-array], or an array-like object (excluding strings and functions). 65 - **strideY**: index increment for `y`. 66 - **fcn**: unary function to apply to callback return values. 67 - **clbk**: callback function. 68 - **thisArg**: execution context (_optional_). 69 70 The invoked callback function is provided six arguments: 71 72 - **value**: input array element. 73 - **idx**: iteration index (zero-based). 74 - **xi**: input array strided index (`offsetX + idx*strideX`). 75 - **yi**: output array strided index (`offsetY + idx*strideY`). 76 - **x**: input array/collection. 77 - **y**: output array/collection. 78 79 To set the callback execution context, provide a `thisArg`. 80 81 ```javascript 82 var abs = require( '@stdlib/math/base/special/abs' ); 83 84 function accessor( v ) { 85 this.count += 1; 86 return v * 2.0; 87 } 88 89 var context = { 90 'count': 0 91 }; 92 93 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ]; 94 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 95 96 mapBy( x.length, x, 1, y, 1, abs, accessor, context ); 97 // y => [ 4.0, 2.0, 6.0, 10.0, 8.0, 0.0, 2.0, 6.0 ] 98 99 var cnt = context.count; 100 // returns 8 101 ``` 102 103 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to index every other value in `x` and to index the first `N` elements of `y` in reverse order, 104 105 ```javascript 106 var abs = require( '@stdlib/math/base/special/abs' ); 107 108 function accessor( v ) { 109 return v * 2.0; 110 } 111 112 var x = [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ]; 113 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 114 115 mapBy( 3, x, 2, y, -1, abs, accessor ); 116 // y => [ 10.0, 6.0, 2.0, 0.0, 0.0, 0.0 ] 117 ``` 118 119 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 120 121 ```javascript 122 var Float64Array = require( '@stdlib/array/float64' ); 123 var abs = require( '@stdlib/math/base/special/abs' ); 124 125 function accessor( v ) { 126 return v * 2.0; 127 } 128 129 // Initial arrays... 130 var x0 = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ] ); 131 var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 132 133 // Create offset views... 134 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 135 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 136 137 mapBy( 3, x1, -2, y1, 1, abs, accessor ); 138 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 12.0, 8.0, 4.0 ] 139 ``` 140 141 #### mapBy.ndarray( N, x, strideX, offsetX, y, strideY, offsetY, fcn, clbk\[, thisArg] ) 142 143 Applies a unary function to each element retrieved from a strided input array according to a callback function and assigns each result to an element in a strided output array using alternative indexing semantics. 144 145 ```javascript 146 var abs = require( '@stdlib/math/base/special/abs' ); 147 148 function accessor( v ) { 149 return v * 2.0; 150 } 151 152 var x = [ -1.0, -2.0, -3.0, -4.0, -5.0 ]; 153 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0 ]; 154 155 mapBy.ndarray( x.length, x, 1, 0, y, 1, 0, abs, accessor ); 156 // y => [ 2.0, 4.0, 6.0, 8.0, 10.0 ] 157 ``` 158 159 The function accepts the following additional arguments: 160 161 - **offsetX**: starting index for `x`. 162 - **offsetY**: starting index for `y`. 163 164 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to index every other value in `x` starting from the second value and to index the last `N` elements in `y`, 165 166 ```javascript 167 var abs = require( '@stdlib/math/base/special/abs' ); 168 169 function accessor( v ) { 170 return v * 2.0; 171 } 172 173 var x = [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ]; 174 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 175 176 mapBy.ndarray( 3, x, 2, 1, y, -1, y.length-1, abs, accessor ); 177 // y => [ 0.0, 0.0, 0.0, 12.0, 8.0, 4.0 ] 178 ``` 179 180 </section> 181 182 <!-- /.usage --> 183 184 <section class="notes"> 185 186 ## Notes 187 188 - If a provided callback function does not return any value (or equivalently, explicitly returns `undefined`), the value is **ignored**. 189 190 ```javascript 191 var abs = require( '@stdlib/math/base/special/abs' ); 192 193 function accessor() { 194 // No-op... 195 } 196 197 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ]; 198 var y = [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]; 199 200 mapBy( x.length, x, 1, y, 1, abs, accessor ); 201 // y => [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] 202 ``` 203 204 </section> 205 206 <!-- /.notes --> 207 208 <section class="examples"> 209 210 ## Examples 211 212 <!-- eslint no-undef: "error" --> 213 214 ```javascript 215 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); 216 var filledarray = require( '@stdlib/array/filled' ); 217 var abs = require( '@stdlib/math/base/special/abs' ); 218 var mapBy = require( '@stdlib/strided/base/map-by' ); 219 220 function accessor( v, i ) { 221 if ( (i%3) === 0 ) { 222 // Simulate a "missing" value... 223 return; 224 } 225 return v; 226 } 227 228 var x = filledarray( 0.0, 10, 'generic' ); 229 var y = filledarray( null, 10, 'generic' ); 230 231 var i; 232 for ( i = 0; i < x.length; i++ ) { 233 x[ i ] = discreteUniform( -100.0, 100.0 ); 234 } 235 console.log( x ); 236 console.log( y ); 237 238 mapBy.ndarray( x.length, x, 1, 0, y, -1, y.length-1, abs, accessor ); 239 console.log( y ); 240 ``` 241 242 </section> 243 244 <!-- /.examples --> 245 246 <section class="links"> 247 248 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 249 250 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 251 252 </section> 253 254 <!-- /.links -->