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