README.md (7113B)
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 # cswap 22 23 > Interchange two complex single-precision floating-point vectors. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var cswap = require( '@stdlib/blas/base/cswap' ); 31 ``` 32 33 #### cswap( N, x, strideX, y, strideY ) 34 35 Interchanges two complex single-precision floating-point vectors. 36 37 ```javascript 38 var Complex64Array = require( '@stdlib/array/complex64' ); 39 var real = require( '@stdlib/complex/real' ); 40 var imag = require( '@stdlib/complex/imag' ); 41 42 var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 43 var y = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 44 45 cswap( x.length, x, 1, y, 1 ); 46 47 var z = y.get( 0 ); 48 // returns <Complex64> 49 50 var re = real( z ); 51 // returns 1.0 52 53 var im = imag( z ); 54 // returns 2.0 55 56 z = x.get( 0 ); 57 // returns <Complex64> 58 59 re = real( z ); 60 // returns 0.0 61 62 im = imag( z ); 63 // returns 0.0 64 ``` 65 66 The function has the following parameters: 67 68 - **N**: number of values to swap. 69 - **x**: input [`Complex64Array`][@stdlib/array/complex64]. 70 - **strideX**: index increment for `x`. 71 - **y**: destination [`Complex64Array`][@stdlib/array/complex64]. 72 - **strideY**: index increment for `y`. 73 74 The `N` and `stride` parameters determine how values from `x` are interchanged with values from `y`. For example, to interchange in reverse order every other value in `x` into the first `N` elements of `y`, 75 76 ```javascript 77 var Complex64Array = require( '@stdlib/array/complex64' ); 78 var floor = require( '@stdlib/math/base/special/floor' ); 79 var real = require( '@stdlib/complex/real' ); 80 var imag = require( '@stdlib/complex/imag' ); 81 82 var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); 83 var y = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 84 85 var N = floor( x.length / 2 ); 86 87 cswap( N, x, -2, y, 1 ); 88 89 var z = y.get( 0 ); 90 // returns <Complex64> 91 92 var re = real( z ); 93 // returns 5.0 94 95 var im = imag( z ); 96 // returns 6.0 97 98 z = x.get( 0 ); 99 // returns <Complex64> 100 101 re = real( z ); 102 // returns 0.0 103 104 im = imag( z ); 105 // returns 0.0 106 ``` 107 108 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 109 110 <!-- eslint-disable stdlib/capitalized-comments --> 111 112 ```javascript 113 var Complex64Array = require( '@stdlib/array/complex64' ); 114 var floor = require( '@stdlib/math/base/special/floor' ); 115 var real = require( '@stdlib/complex/real' ); 116 var imag = require( '@stdlib/complex/imag' ); 117 118 // Initial arrays... 119 var x0 = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); 120 var y0 = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 121 122 // Create offset views... 123 var x1 = new Complex64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 124 var y1 = new Complex64Array( y0.buffer, y0.BYTES_PER_ELEMENT*2 ); // start at 3rd element 125 126 var N = floor( x0.length / 2 ); 127 128 // Interchange in reverse order every other value from `x1` into `y1`... 129 cswap( N, x1, -2, y1, 1 ); 130 131 var z = y0.get( 2 ); 132 // returns <Complex64> 133 134 var re = real( z ); 135 // returns 7.0 136 137 var im = imag( z ); 138 // returns 8.0 139 140 z = x0.get( 1 ); 141 // returns <Complex64> 142 143 re = real( z ); 144 // returns 0.0 145 146 im = imag( z ); 147 // returns 0.0 148 ``` 149 150 #### cswap.ndarray( N, x, strideX, offsetX, y, strideY, offsetY ) 151 152 Interchanges two complex single-precision floating-point vectors using alternative indexing semantics. 153 154 ```javascript 155 var Complex64Array = require( '@stdlib/array/complex64' ); 156 var real = require( '@stdlib/complex/real' ); 157 var imag = require( '@stdlib/complex/imag' ); 158 159 var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 160 var y = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 161 162 cswap.ndarray( x.length, x, 1, 0, y, 1, 0 ); 163 164 var z = y.get( 0 ); 165 // returns <Complex64> 166 167 var re = real( z ); 168 // returns 1.0 169 170 var im = imag( z ); 171 // returns 2.0 172 173 z = x.get( 0 ); 174 // returns <Complex64> 175 176 re = real( z ); 177 // returns 0.0 178 179 im = imag( z ); 180 // returns 0.0 181 ``` 182 183 The function has the following additional parameters: 184 185 - **offsetX**: starting index for `x`. 186 - **offsetY**: starting index for `y`. 187 188 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 interchange every other value in `x` starting from the second value into the last `N` elements in `y` where `x[i] = y[n]`, `x[i+2] = y[n-1]`,..., 189 190 ```javascript 191 var Complex64Array = require( '@stdlib/array/complex64' ); 192 var floor = require( '@stdlib/math/base/special/floor' ); 193 var real = require( '@stdlib/complex/real' ); 194 var imag = require( '@stdlib/complex/imag' ); 195 196 var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); 197 var y = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] ); 198 199 var N = floor( x.length / 2 ); 200 201 cswap.ndarray( N, x, 2, 1, y, -1, y.length-1 ); 202 203 var z = y.get( y.length-1 ); 204 // returns <Complex64> 205 206 var re = real( z ); 207 // returns 3.0 208 209 var im = imag( z ); 210 // returns 4.0 211 212 z = x.get( x.length-1 ); 213 // returns <Complex64> 214 215 re = real( z ); 216 // returns 0.0 217 218 im = imag( z ); 219 // returns 0.0 220 ``` 221 222 </section> 223 224 <!-- /.usage --> 225 226 <section class="notes"> 227 228 ## Notes 229 230 - If `N <= 0`, both functions leave `x` and `y` unchanged. 231 - `cswap()` corresponds to the [BLAS][blas] level 1 function [`cswap`][cswap]. 232 233 </section> 234 235 <!-- /.notes --> 236 237 <section class="examples"> 238 239 ## Examples 240 241 <!-- eslint no-undef: "error" --> 242 243 ```javascript 244 var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); 245 var Complex64Array = require( '@stdlib/array/complex64' ); 246 var cswap = require( '@stdlib/blas/base/cswap' ); 247 248 var re = discreteUniform.factory( 0, 10 ); 249 var im = discreteUniform.factory( -5, 5 ); 250 251 var x = new Complex64Array( 10 ); 252 var y = new Complex64Array( 10 ); 253 254 var i; 255 for ( i = 0; i < x.length; i++ ) { 256 x.set( [ re(), im() ], i ); 257 y.set( [ re(), im() ], i ); 258 } 259 console.log( x.get( 0 ).toString() ); 260 console.log( y.get( 0 ).toString() ); 261 262 // Swap elements in `x` and `y` starting from the end of `y`: 263 cswap( x.length, x, 1, y, -1 ); 264 console.log( x.get( x.length-1 ).toString() ); 265 console.log( y.get( y.length-1 ).toString() ); 266 ``` 267 268 </section> 269 270 <!-- /.examples --> 271 272 <section class="links"> 273 274 [blas]: http://www.netlib.org/blas 275 276 [cswap]: http://www.netlib.org/lapack/explore-html/da/df6/group__complex__blas__level1.html 277 278 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 279 280 [@stdlib/array/complex64]: https://www.npmjs.com/package/@stdlib/array-complex64 281 282 </section> 283 284 <!-- /.links -->