README.md (5512B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # gcopy 22 23 > Copy values from `x` into `y`. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var gcopy = require( '@stdlib/blas/base/gcopy' ); 31 ``` 32 33 #### gcopy( N, x, strideX, y, strideY ) 34 35 Copies values from `x` into `y`. 36 37 ```javascript 38 var x = [ 1.0, 2.0, 3.0, 4.0, 5.0 ]; 39 var y = [ 6.0, 7.0, 8.0, 9.0, 10.0 ]; 40 41 gcopy( x.length, x, 1, y, 1 ); 42 // y => [ 1.0, 2.0, 3.0, 4.0, 5.0 ] 43 ``` 44 45 The function has the following parameters: 46 47 - **N**: number of values to copy. 48 - **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array]. 49 - **strideX**: index increment for `x`. 50 - **y**: destination [`array`][mdn-array] or [`typed array`][mdn-typed-array]. 51 - **strideY**: index increment for `y`. 52 53 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`, 54 55 ```javascript 56 var floor = require( '@stdlib/math/base/special/floor' ); 57 58 var x = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]; 59 var y = [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ]; 60 61 var N = floor( x.length / 2 ); 62 63 gcopy( N, x, -2, y, 1 ); 64 // y => [ 5.0, 3.0, 1.0, 10.0, 11.0, 12.0 ] 65 ``` 66 67 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. 68 69 <!-- eslint-disable stdlib/capitalized-comments --> 70 71 ```javascript 72 var Float64Array = require( '@stdlib/array/float64' ); 73 var floor = require( '@stdlib/math/base/special/floor' ); 74 75 // Initial arrays... 76 var x0 = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); 77 var y0 = new Float64Array( [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] ); 78 79 // Create offset views... 80 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 81 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element 82 83 var N = floor( x0.length / 2 ); 84 85 // Copy in reverse order every other value from `x1` into `y1`... 86 gcopy( N, x1, -2, y1, 1 ); 87 // y0 => <Float64Array>[ 7.0, 8.0, 9.0, 6.0, 4.0, 2.0 ] 88 ``` 89 90 #### gcopy.ndarray( N, x, strideX, offsetX, y, strideY, offsetY ) 91 92 Copies values from `x` into `y` using alternative indexing semantics. 93 94 ```javascript 95 var x = [ 1.0, 2.0, 3.0, 4.0, 5.0 ]; 96 var y = [ 6.0, 7.0, 8.0, 9.0, 10.0 ]; 97 98 gcopy.ndarray( x.length, x, 1, 0, y, 1, 0 ); 99 // y => [ 1.0, 2.0, 3.0, 4.0, 5.0 ] 100 ``` 101 102 The function has the following additional parameters: 103 104 - **offsetX**: starting index for `x`. 105 - **offsetY**: starting index for `y`. 106 107 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]`,..., 108 109 ```javascript 110 var floor = require( '@stdlib/math/base/special/floor' ); 111 112 var x = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]; 113 var y = [ 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ]; 114 115 var N = floor( x.length / 2 ); 116 117 gcopy.ndarray( N, x, 2, 1, y, -1, y.length-1 ); 118 // y => [ 7.0, 8.0, 9.0, 6.0, 4.0, 2.0 ] 119 ``` 120 121 </section> 122 123 <!-- /.usage --> 124 125 <section class="notes"> 126 127 ## Notes 128 129 - If `N <= 0`, both functions return `y` unchanged. 130 - `gcopy()` corresponds to the [BLAS][blas] level 1 function [`dcopy`][dcopy] with the exception that this implementation works with any array type, not just Float64Arrays. Depending on the environment, the typed versions ([`dcopy`][@stdlib/blas/base/dcopy], [`scopy`][@stdlib/blas/base/scopy], etc.) are likely to be significantly more performant. 131 132 </section> 133 134 <!-- /.notes --> 135 136 <section class="examples"> 137 138 ## Examples 139 140 <!-- eslint no-undef: "error" --> 141 142 ```javascript 143 var randu = require( '@stdlib/random/base/randu' ); 144 var round = require( '@stdlib/math/base/special/round' ); 145 var Float64Array = require( '@stdlib/array/float64' ); 146 var Uint8ClampedArray = require( '@stdlib/array/uint8c' ); 147 var gcopy = require( '@stdlib/blas/base/gcopy' ); 148 149 var x; 150 var y; 151 var i; 152 153 x = new Float64Array( 10 ); 154 y = new Uint8ClampedArray( 10 ); 155 for ( i = 0; i < x.length; i++ ) { 156 x[ i ] = round( randu()*500.0 ); 157 y[ i ] = round( randu()*255.0 ); 158 } 159 console.log( x ); 160 console.log( y ); 161 162 // Copy elements from `x` into `y` starting from the end of `y`: 163 gcopy( x.length, x, 1, y, -1 ); 164 console.log( y ); 165 ``` 166 167 </section> 168 169 <!-- /.examples --> 170 171 <section class="links"> 172 173 [blas]: http://www.netlib.org/blas 174 175 [dcopy]: http://www.netlib.org/lapack/explore-html/de/da4/group__double__blas__level1.html 176 177 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 178 179 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 180 181 [@stdlib/blas/base/dcopy]: https://www.npmjs.com/package/@stdlib/blas/tree/main/base/dcopy 182 183 [@stdlib/blas/base/scopy]: https://www.npmjs.com/package/@stdlib/blas/tree/main/base/scopy 184 185 </section> 186 187 <!-- /.links -->