diff --git a/lib/node_modules/@stdlib/array/uint64/README.md b/lib/node_modules/@stdlib/array/uint64/README.md index 02da19409141..eb6a2ed4f384 100644 --- a/lib/node_modules/@stdlib/array/uint64/README.md +++ b/lib/node_modules/@stdlib/array/uint64/README.md @@ -278,6 +278,103 @@ u = arr.at( -100 ); // returns undefined ``` + + +#### Uint64Array.prototype.copyWithin( target, start\[, end] ) + +Copies a sequence of elements within the array starting at `start` and ending at `end` (non-inclusive) to the position starting at `target`. + +```javascript +var Uint64 = require( '@stdlib/number/uint64/ctor' ); + +var arr = new Uint64Array( 4 ); + +// Set the array elements: +arr.set( 1, 0 ); +arr.set( 2, 1 ); +arr.set( 3, 2 ); +arr.set( 4, 3 ); + +// Get the first array element: +var z = arr.get( 0 ); +// returns [ 1n ] + +// Get the second array element: +z = arr.get( 1 ); +// returns [ 2n ] + +// Copy the last two elements to the first two elements: +arr.copyWithin( 0, 2 ); + +// Get the first array element: +z = arr.get( 0 ); +// returns [ 3n ] + +// Get the second array element: +z = arr.get( 1 ); +// returns [ 4n ] +``` + +By default, `end` equals the number of array elements (i.e., one more than the last array index). To limit the sequence length, provide an `end` argument. + +```javascript +var Uint64 = require( '@stdlib/number/uint64/ctor' ); + +var arr = new Uint64Array( 4 ); + +// Set the array elements: +arr.set( 1, 0 ); +arr.set( 2, 1 ); +arr.set( 3, 2 ); +arr.set( 4, 3 ); + +// Get the third array element: +var z = arr.get( 2 ); +// returns [ 3n ] + +// Get the last array element: +z = arr.get( 3 ); +// returns [ 4n ] + +// Copy the first two elements to the last two elements: +arr.copyWithin( 2, 0, 2 ); + +// Get the third array element: +z = arr.get( 2 ); +// returns [ 1n ] + +// Get the last array element: +z = arr.get( 3 ); +// returns [ 2n ] +``` + +When a `target`, `start`, and/or `end` index is negative, the respective index is determined relative to the last array element. The following example achieves the same behavior as the previous example: + +```javascript +var Uint64 = require( '@stdlib/number/uint64/ctor' ); + +var arr = new Uint64Array( [ 1, 2, 3, 4 ] ); + +// Get the third array element: +var z = arr.get( 2 ); +// returns [ 3n ] + +// Get the last array element: +z = arr.get( 3 ); +// returns [ 4n ] + +// Copy the first two elements to the last two elements using negative indices: +arr.copyWithin( -2, -4, -2 ); + +// Get the third array element: +z = arr.get( 2 ); +// returns [ 1n ] + +// Get the last array element: +z = arr.get( 3 ); +// returns [ 2n ] +``` + #### Uint64Array.prototype.entries() diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.js new file mode 100644 index 000000000000..d416f14ae33a --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.js @@ -0,0 +1,53 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var isUint64Array = require( '@stdlib/assert/is-uint64array' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Uint64Array = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:copyWithin', pkg ), function benchmark( b ) { + var arr; + var out; + var i; + + arr = new Uint64Array( 10 ); + + // Benchmark worst case scenario (i.e., copying all but one element to an overlapping region)... + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = arr.copyWithin( 1, 0 ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isUint64Array( out ) ) { + b.fail( 'should return a Uint64Array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.length.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.length.js new file mode 100644 index 000000000000..80678f6ca5d2 --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.copy_within.length.js @@ -0,0 +1,96 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isUint64Array = require( '@stdlib/assert/is-uint64array' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Uint64Array = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var arr = new Uint64Array( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var out; + var i; + + // Benchmark worst case scenario (i.e., copying all but one element to an overlapping region)... + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = arr.copyWithin( 1, 0 ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isUint64Array( out ) ) { + b.fail( 'should return a Uint64Array' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( format( '%s:copyWithin:len=%d', pkg, len ), f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.get.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.get.js index bee09657497b..def833746eb2 100644 --- a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.get.js +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.get.js @@ -36,8 +36,7 @@ bench( format( '%s:get', pkg ), function benchmark( b ) { var v; var i; - arr = zeroTo( 10, 'generic' ); - arr = new Uint64Array( arr ); + arr = new Uint64Array( zeroTo( 10, 'generic' ) ); N = arr.length; b.tic(); diff --git a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt index c737fc5bf588..8098f50dba68 100644 --- a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt @@ -252,6 +252,35 @@ [ 2n ] +{{alias}}.prototype.copyWithin( target, start[, end] ) + Copies a sequence of elements within the array starting at `start` and + ending at `end` (non-inclusive) to the position starting at `target`. + + Parameters + ---------- + target: integer + Target start index position. + + start: integer + Source start index position. + + end: integer (optional) + Source end index position. Default: out.length. + + Returns + ------- + out: Uint64Array + Modified array. + + Examples + -------- + > var arr = new {{alias}}( [ 1, 2, 3, 4 ] ); + > arr.copyWithin( 0, 2 ) + [ 3n, 4n, 3n, 4n ] + > var z = arr.get( 0 ) + [ 3n ] + + {{alias}}.prototype.entries() Returns an iterator for iterating over array key-value pairs. diff --git a/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts index 78b11c503625..0643dba70b4a 100644 --- a/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts @@ -426,6 +426,25 @@ declare class Uint64Array implements Uint64ArrayInterface { */ at( i: number ): Uint64 | void; + /** + * Copies a sequence of elements within the array to the position starting at `target`. + * + * @param target - index at which to start copying elements + * @param start - source index at which to copy elements from + * @param end - source index at which to stop copying elements from + * @returns modified array + * + * @example + * var Uint64 = require( '@stdlib/number/uint64/ctor' ); + * + * var arr = new Uint64Array( [ 1, 2, 3, 4 ] ); + * + * // Copy the first two elements to the last two elements: + * arr.copyWithin( 2, 0, 2 ); + * // arr => [ 1n, 2n, 1n, 2n ] + */ + copyWithin( target: number, start: number, end?: number ): Uint64Array; + /** * Returns an iterator for iterating over array key-value pairs. * diff --git a/lib/node_modules/@stdlib/array/uint64/lib/main.js b/lib/node_modules/@stdlib/array/uint64/lib/main.js index 684cb8e4b9bd..5b0b4eb7125a 100644 --- a/lib/node_modules/@stdlib/array/uint64/lib/main.js +++ b/lib/node_modules/@stdlib/array/uint64/lib/main.js @@ -597,6 +597,40 @@ setReadOnlyAccessor( Uint64Array.prototype, 'byteOffset', function get() { */ setReadOnly( Uint64Array.prototype, 'BYTES_PER_ELEMENT', Uint64Array.BYTES_PER_ELEMENT ); +/** +* Copies a sequence of elements within the array to the position starting at `target`. +* +* @name copyWithin +* @memberof Uint64Array.prototype +* @type {Function} +* @param {integer} target - index at which to start copying elements +* @param {integer} start - source index at which to copy elements from +* @param {integer} [end] - source index at which to stop copying elements from +* @throws {TypeError} `this` must be a 64-bit unsigned integer array +* @returns {Uint64Array} modified array +* +* @example +* var Uint64 = require( '@stdlib/number/uint64/ctor' ); +* +* var arr = new Uint64Array( [ 1, 2, 3, 4 ] ); +* +* // Copy the first two elements to the last two elements: +* arr.copyWithin( 2, 0, 2 ); +* // arr => [ 1n, 2n, 1n, 2n ] +*/ +setReadOnly( Uint64Array.prototype, 'copyWithin', function copyWithin( target, start ) { + if ( !isUint64Array( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a 64-bit unsigned integer array.' ); + } + // FIXME: prefer a functional `copyWithin` implementation which addresses lack of universal browser support (e.g., IE11 and Safari) or ensure that typed arrays are polyfilled + if ( arguments.length === 2 ) { + this._buffer.copyWithin( target*2, start*2 ); + } else { + this._buffer.copyWithin( target*2, start*2, arguments[2]*2 ); + } + return this; +}); + /** * Returns an iterator for iterating over array key-value pairs. * diff --git a/lib/node_modules/@stdlib/array/uint64/test/test.copy_within.js b/lib/node_modules/@stdlib/array/uint64/test/test.copy_within.js new file mode 100644 index 000000000000..d1d4ce4b4918 --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/test/test.copy_within.js @@ -0,0 +1,257 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isEqual = require( '@stdlib/number/uint64/base/assert/is-equal' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var Uint64 = require( '@stdlib/number/uint64/ctor' ); +var Uint64Array = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof Uint64Array, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the prototype of the main export is a `copyWithin` method for copying a sequence of array elements within a 64-bit unsigned integer array', function test( t ) { + t.strictEqual( hasOwnProp( Uint64Array.prototype, 'copyWithin' ), true, 'has property' ); + t.strictEqual( isFunction( Uint64Array.prototype.copyWithin ), true, 'has method' ); + t.end(); +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a 64-bit unsigned integer array instance', function test( t ) { + var values; + var arr; + var i; + + arr = new Uint64Array( 5 ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return arr.copyWithin.call( value, 3, 0 ); + }; + } +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a 64-bit unsigned integer array instance (end)', function test( t ) { + var values; + var arr; + var i; + + arr = new Uint64Array( 5 ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return arr.copyWithin.call( value, 3, 0, 5 ); + }; + } +}); + +tape( 'the method copies a sequence of elements within an array', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 0, 3 ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 2 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (negative target)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( -arr.length, 3 ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 2 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (negative start)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 0, -2 ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 2 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (end=length)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 0, 3, arr.length ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 2 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (non-inclusive end)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 2, 0, 2 ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 1 ) ), true, 'returns expected value' ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 1 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (negative end)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 2, 0, -3 ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 1 ) ), true, 'returns expected value' ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 1 ) ), true, 'returns expected value' ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (target >= length)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( arr.length, 3 ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 1 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 2 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 3 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 4 ) ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method copies a sequence of elements within an array (target > start)', function test( t ) { + var arr; + + arr = new Uint64Array( [ 0, 1, 2, 3, 4 ] ); + + arr.copyWithin( 2, 0 ); + + // Remain the same: + t.strictEqual( isEqual( arr.get( 0 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 1 ), new Uint64( 1 ) ), true, 'returns expected value' ); + + // Overwritten: + t.strictEqual( isEqual( arr.get( 2 ), new Uint64( 0 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 3 ), new Uint64( 1 ) ), true, 'returns expected value' ); + t.strictEqual( isEqual( arr.get( 4 ), new Uint64( 2 ) ), true, 'returns expected value' ); + + t.end(); +});