README.md (8242B)
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 # Quinary 22 23 > Apply a quinary callback to strided input array elements and assign results to elements in a strided output array. 24 25 <section class="intro"> 26 27 </section> 28 29 <!-- /.intro --> 30 31 <section class="usage"> 32 33 ## Usage 34 35 ```javascript 36 var quinary = require( '@stdlib/strided/base/quinary' ); 37 ``` 38 39 #### quinary( arrays, shape, strides, fcn ) 40 41 Applies a quinary callback to strided input array elements and assigns results to elements in a strided output array. 42 43 ```javascript 44 var Float64Array = require( '@stdlib/array/float64' ); 45 46 function add( x, y, z, w, u ) { 47 return x + y + z + w + u; 48 } 49 50 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 51 var y = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 52 var z = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 53 var w = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 54 var u = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 55 var v = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 56 57 quinary( [ x, y, z, w, u, v ], [ x.length ], [ 1, 1, 1, 1, 1, 1 ], add ); 58 // v => <Float64Array>[ 5.0, 10.0, 15.0, 20.0, 25.0 ] 59 ``` 60 61 The function accepts the following arguments: 62 63 - **arrays**: array-like object containing five strided input arrays and one strided output array. 64 - **shape**: array-like object containing a single element, the number of indexed elements. 65 - **strides**: array-like object containing the stride lengths for the strided input and output arrays. 66 - **fcn**: quinary function to apply. 67 68 The `shape` and `strides` parameters determine which elements in the strided input and output arrays are accessed at runtime. For example, to index every other value in the strided input arrays and to index the first `N` elements of the strided output array in reverse order, 69 70 ```javascript 71 var Float64Array = require( '@stdlib/array/float64' ); 72 var floor = require( '@stdlib/math/base/special/floor' ); 73 74 function add( x, y, z, w, u ) { 75 return x + y + z + w + u; 76 } 77 78 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 79 var y = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 80 var z = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 81 var w = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 82 var u = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 83 var v = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 84 85 var N = floor( x.length / 2 ); 86 87 quinary( [ x, y, z, w, u, v ], [ N ], [ 2, 2, 2, 2, 2, -1 ], add ); 88 // v => <Float64Array>[ 25.0, 15.0, 5.0, 0.0, 0.0, 0.0 ] 89 ``` 90 91 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 92 93 ```javascript 94 var Float64Array = require( '@stdlib/array/float64' ); 95 var floor = require( '@stdlib/math/base/special/floor' ); 96 97 function add( x, y, z, w, u ) { 98 return x + y + z + w + u; 99 } 100 101 // Initial arrays... 102 var x0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 103 var y0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 104 var z0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 105 var w0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 106 var u0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 107 var v0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 108 109 // Create offset views... 110 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 111 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 112 var z1 = new Float64Array( z0.buffer, z0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 113 var w1 = new Float64Array( w0.buffer, w0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 114 var u1 = new Float64Array( u0.buffer, u0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 115 var v1 = new Float64Array( v0.buffer, v0.BYTES_PER_ELEMENT*3 ); // start at 4th element 116 117 var N = floor( x0.length / 2 ); 118 119 quinary( [ x1, y1, z1, w1, u1, v1 ], [ N ], [ -2, -2, -2, -2, -2, 1 ], add ); 120 // u0 => <Float64Array>[ 0.0, 0.0, 0.0, 30.0, 20.0, 10.0 ] 121 ``` 122 123 #### quinary.ndarray( arrays, shape, strides, offsets, fcn ) 124 125 Applies a quinary callback to strided input array elements and assigns results to elements in a strided output array using alternative indexing semantics. 126 127 <!-- eslint-disable max-len --> 128 129 ```javascript 130 var Float64Array = require( '@stdlib/array/float64' ); 131 132 function add( x, y, z, w, u ) { 133 return x + y + z + w + u; 134 } 135 136 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 137 var y = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 138 var z = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 139 var w = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 140 var u = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); 141 var v = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 142 143 quinary.ndarray( [ x, y, z, w, u, v ], [ x.length ], [ 1, 1, 1, 1, 1, 1 ], [ 0, 0, 0, 0, 0, 0 ], add ); 144 // v => <Float64Array>[ 5.0, 10.0, 15.0, 20.0, 25.0 ] 145 ``` 146 147 The function accepts the following additional arguments: 148 149 - **offsets**: array-like object containing the starting indices (i.e., index offsets) for the strided input and output arrays. 150 151 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsets` parameter supports indexing semantics based on starting indices. For example, to index every other value in the strided input arrays starting from the second value and to index the last `N` elements in the strided output array, 152 153 <!-- eslint-disable max-len --> 154 155 ```javascript 156 var Float64Array = require( '@stdlib/array/float64' ); 157 var floor = require( '@stdlib/math/base/special/floor' ); 158 159 function add( x, y, z, w, u ) { 160 return x + y + z + w + u; 161 } 162 163 var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 164 var y = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 165 var z = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 166 var w = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 167 var u = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 168 var v = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 169 170 var N = floor( x.length / 2 ); 171 172 quinary.ndarray( [ x, y, z, w, u, v ], [ N ], [ 2, 2, 2, 2, 2, -1 ], [ 1, 1, 1, 1, 1, v.length-1 ], add ); 173 // v => <Float64Array>[ 0.0, 0.0, 0.0, 30.0, 20.0, 10.0 ] 174 ``` 175 176 </section> 177 178 <!-- /.usage --> 179 180 <section class="notes"> 181 182 </section> 183 184 <!-- /.notes --> 185 186 <section class="examples"> 187 188 ## Examples 189 190 <!-- eslint no-undef: "error" --> 191 192 ```javascript 193 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; 194 var filledarray = require( '@stdlib/array/filled' ); 195 var gfillBy = require( '@stdlib/blas/ext/base/gfill-by' ); 196 var quinary = require( '@stdlib/strided/base/quinary' ); 197 198 function add( x, y, z, w, u ) { 199 return x + y + z + w + u; 200 } 201 202 var N = 10; 203 204 var x = filledarray( 0.0, N, 'generic' ); 205 gfillBy( x.length, x, 1, discreteUniform( -100, 100 ) ); 206 console.log( x ); 207 208 var y = filledarray( 0.0, N, 'generic' ); 209 gfillBy( y.length, y, 1, discreteUniform( -100, 100 ) ); 210 console.log( y ); 211 212 var z = filledarray( 0.0, N, 'generic' ); 213 gfillBy( z.length, z, 1, discreteUniform( -100, 100 ) ); 214 console.log( z ); 215 216 var w = filledarray( 0.0, N, 'generic' ); 217 gfillBy( w.length, w, 1, discreteUniform( -100, 100 ) ); 218 console.log( w ); 219 220 var u = filledarray( 0.0, N, 'generic' ); 221 gfillBy( u.length, u, 1, discreteUniform( -100, 100 ) ); 222 console.log( u ); 223 224 var v = filledarray( 0.0, N, 'generic' ); 225 console.log( v ); 226 227 var shape = [ N ]; 228 var strides = [ 1, 1, 1, 1, 1, -1 ]; 229 var offsets = [ 0, 0, 0, 0, 0, N-1 ]; 230 231 quinary.ndarray( [ x, y, z, w, u, v ], shape, strides, offsets, add ); 232 console.log( v ); 233 ``` 234 235 </section> 236 237 <!-- /.examples --> 238 239 <section class="links"> 240 241 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 242 243 </section> 244 245 <!-- /.links -->