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