README.md (4898B)
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 # drev 22 23 > Reverse a double-precision floating-point strided array in-place. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var drev = require( '@stdlib/blas/ext/base/drev' ); 31 ``` 32 33 #### drev( N, x, stride ) 34 35 Reverses a double-precision floating-point strided array `x` in-place. 36 37 ```javascript 38 var Float64Array = require( '@stdlib/array/float64' ); 39 40 var x = new Float64Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 41 42 drev( x.length, x, 1 ); 43 // x => <Float64Array>[ -3.0, -1.0, 0.0, 4.0, -5.0, 3.0, 1.0, -2.0 ] 44 ``` 45 46 The function has the following parameters: 47 48 - **N**: number of indexed elements. 49 - **x**: input [`Float64Array`][@stdlib/array/float64]. 50 - **stride**: index increment. 51 52 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to reverse every other element 53 54 ```javascript 55 var Float64Array = require( '@stdlib/array/float64' ); 56 var floor = require( '@stdlib/math/base/special/floor' ); 57 58 var x = new Float64Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 59 var N = floor( x.length / 2 ); 60 61 drev( N, x, 2 ); 62 // x => <Float64Array>[ -1.0, 1.0, 4.0, -5.0, 3.0, 0.0, -2.0, -3.0 ] 63 ``` 64 65 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 66 67 ```javascript 68 var Float64Array = require( '@stdlib/array/float64' ); 69 var floor = require( '@stdlib/math/base/special/floor' ); 70 71 // Initial array... 72 var x0 = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); 73 74 // Create an offset view... 75 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 76 var N = floor( x0.length/2 ); 77 78 // Reverse every other element... 79 drev( N, x1, 2 ); 80 // x0 => <Float64Array>[ 1.0, -6.0, 3.0, -4.0, 5.0, -2.0 ] 81 ``` 82 83 #### drev.ndarray( N, x, stride, offset ) 84 85 Reverses a double-precision floating-point strided array `x` in-place using alternative indexing semantics. 86 87 ```javascript 88 var Float64Array = require( '@stdlib/array/float64' ); 89 90 var x = new Float64Array( [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0 ] ); 91 92 drev.ndarray( x.length, x, 1, 0 ); 93 // x => <Float64Array>[ -3.0, -1.0, 0.0, 4.0, -5.0, 3.0, 1.0, -2.0 ] 94 ``` 95 96 The function has the following additional parameters: 97 98 - **offset**: starting index. 99 100 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to access only the last three elements of `x` 101 102 ```javascript 103 var Float64Array = require( '@stdlib/array/float64' ); 104 105 var x = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); 106 107 drev.ndarray( 3, x, 1, x.length-3 ); 108 // x => <Float64Array>[ 1.0, -2.0, 3.0, -6.0, 5.0, -4.0 ] 109 ``` 110 111 </section> 112 113 <!-- /.usage --> 114 115 <section class="notes"> 116 117 ## Notes 118 119 - If `N <= 0`, both functions return `x` unchanged. 120 - Where possible, one should "reverse" a strided array by negating its stride, which is an `O(1)` operation, in contrast to performing an in-place reversal, which is `O(N)`. However, in certain circumstances, this is not tenable, particularly when interfacing with libraries which assume and/or expect a specific memory layout (e.g., strided array elements arranged in memory in ascending order). In general, when working with strided arrays, only perform an in-place reversal when strictly necessary. 121 122 </section> 123 124 <!-- /.notes --> 125 126 <section class="examples"> 127 128 ## Examples 129 130 <!-- eslint no-undef: "error" --> 131 132 ```javascript 133 var round = require( '@stdlib/math/base/special/round' ); 134 var randu = require( '@stdlib/random/base/randu' ); 135 var Float64Array = require( '@stdlib/array/float64' ); 136 var drev = require( '@stdlib/blas/ext/base/drev' ); 137 138 var rand; 139 var sign; 140 var x; 141 var i; 142 143 x = new Float64Array( 10 ); 144 for ( i = 0; i < x.length; i++ ) { 145 rand = round( randu()*100.0 ); 146 sign = randu(); 147 if ( sign < 0.5 ) { 148 sign = -1.0; 149 } else { 150 sign = 1.0; 151 } 152 x[ i ] = sign * rand; 153 } 154 console.log( x ); 155 156 drev( x.length, x, 1 ); 157 console.log( x ); 158 ``` 159 160 </section> 161 162 <!-- /.examples --> 163 164 <section class="links"> 165 166 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64 167 168 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 169 170 </section> 171 172 <!-- /.links -->