README.md (5990B)
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 # abs 22 23 > Compute the [absolute value][absolute-value] for each element in a strided array. 24 25 <section class="intro"> 26 27 The [absolute value][absolute-value] is defined as 28 29 <!-- <equation class="equation" label="eq:absolute_value" align="center" raw="|x| = \begin{cases} x & \textrm{if}\ x \geq 0 \\ -x & \textrm{if}\ x < 0\end{cases}" alt="Absolute value"> --> 30 31 <div class="equation" align="center" data-raw-text="|x| = \begin{cases} x & \textrm{if}\ x \geq 0 \\ -x & \textrm{if}\ x < 0\end{cases}" data-equation="eq:absolute_value"> 32 <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@5080b1c6024f68941c0bd4829b354fc345de408a/lib/node_modules/@stdlib/math/strided/special/abs/docs/img/equation_absolute_value.svg" alt="Absolute value"> 33 <br> 34 </div> 35 36 <!-- </equation> --> 37 38 </section> 39 40 <!-- /.intro --> 41 42 <section class="usage"> 43 44 ## Usage 45 46 ```javascript 47 var abs = require( '@stdlib/math/strided/special/abs' ); 48 ``` 49 50 #### abs( N, x, strideX, y, strideY ) 51 52 Computes the [absolute value][absolute-value] for each element in `x` and assigns the results to elements in `y`. 53 54 ```javascript 55 var Float64Array = require( '@stdlib/array/float64' ); 56 57 var x = new Float64Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 58 59 // Compute the absolute values in-place: 60 abs( x.length, x, 1, x, 1 ); 61 // x => <Float64Array>[ 2.0, 1.0, 3.0, 5.0, 4.0, 0.0, 1.0, 3.0 ] 62 ``` 63 64 The function accepts the following arguments: 65 66 - **N**: number of indexed elements. 67 - **x**: input array-like object. 68 - **strideX**: index increment for `x`. 69 - **y**: output array-like object. 70 - **strideY**: index increment for `y`. 71 72 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 the first `N` elements of `y` in reverse order, 73 74 ```javascript 75 var Float64Array = require( '@stdlib/array/float64' ); 76 var floor = require( '@stdlib/math/base/special/floor' ); 77 78 var x = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ] ); 79 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 80 81 var N = floor( x.length / 2 ); 82 83 abs( N, x, 2, y, -1 ); 84 // y => <Float64Array>[ 5.0, 3.0, 1.0, 0.0, 0.0, 0.0 ] 85 ``` 86 87 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 88 89 ```javascript 90 var Float64Array = require( '@stdlib/array/float64' ); 91 var floor = require( '@stdlib/math/base/special/floor' ); 92 93 // Initial arrays... 94 var x0 = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ] ); 95 var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 96 97 // Create offset views... 98 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 99 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 100 101 var N = floor( x0.length / 2 ); 102 103 abs( N, x1, -2, y1, 1 ); 104 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 6.0, 4.0, 2.0 ] 105 ``` 106 107 #### abs.ndarray( N, x, strideX, offsetX, y, strideY, offsetY ) 108 109 Computes the [absolute value][absolute-value] for each element in `x` and assigns the result to an element in `y` using alternative indexing semantics. 110 111 ```javascript 112 var Float64Array = require( '@stdlib/array/float64' ); 113 114 var x = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0 ] ); 115 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 116 117 abs.ndarray( x.length, x, 1, 0, y, 1, 0 ); 118 // y => <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ] 119 ``` 120 121 The function accepts the following additional arguments: 122 123 - **offsetX**: starting index for `x`. 124 - **offsetY**: starting index for `y`. 125 126 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`, 127 128 ```javascript 129 var Float64Array = require( '@stdlib/array/float64' ); 130 var floor = require( '@stdlib/math/base/special/floor' ); 131 132 var x = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0, -6.0 ] ); 133 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 134 135 var N = floor( x.length / 2 ); 136 137 abs.ndarray( N, x, 2, 1, y, -1, y.length-1 ); 138 // y => <Float64Array>[ 0.0, 0.0, 0.0, 6.0, 4.0, 2.0 ] 139 ``` 140 141 </section> 142 143 <!-- /.usage --> 144 145 <section class="notes"> 146 147 </section> 148 149 <!-- /.notes --> 150 151 <section class="examples"> 152 153 ## Examples 154 155 <!-- eslint no-undef: "error" --> 156 157 ```javascript 158 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; 159 var filledarray = require( '@stdlib/array/filled' ); 160 var dtypes = require( '@stdlib/array/dtypes' ); 161 var gfillBy = require( '@stdlib/blas/ext/base/gfill-by' ); 162 var abs = require( '@stdlib/math/strided/special/abs' ); 163 164 var dt; 165 var x; 166 var y; 167 var i; 168 169 dt = dtypes(); 170 for ( i = 0; i < dt.length; i++ ) { 171 x = filledarray( 0.0, 10, dt[ i ] ); 172 gfillBy( x.length, x, 1, discreteUniform( -100, 100 ) ); 173 console.log( x ); 174 175 y = filledarray( 0.0, x.length, dt[ i ] ); 176 console.log( y ); 177 178 abs.ndarray( x.length, x, 1, 0, y, -1, y.length-1 ); 179 console.log( y ); 180 console.log( '' ); 181 } 182 ``` 183 184 </section> 185 186 <!-- /.examples --> 187 188 <section class="links"> 189 190 [absolute-value]: https://en.wikipedia.org/wiki/Absolute_value 191 192 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 193 194 </section> 195 196 <!-- /.links -->