From 9c9c16ec60ef920e4550345e752c323c700c7635 Mon Sep 17 00:00:00 2001
From: ShraddheyaS <shendreshraddheya@gmail.com>
Date: Tue, 29 Sep 2020 00:58:47 +0530
Subject: [PATCH] Add functional equivalent of Array.prototype.copyWithin
---
.../@stdlib/utils/copy-within/README.md | 131 +++++++++
.../utils/copy-within/benchmark/benchmark.js | 53 ++++
.../copy-within/benchmark/benchmark.length.js | 128 +++++++++
.../copy-within/benchmark/benchmark.object.js | 62 ++++
.../benchmark/benchmark.typed_array.js | 272 ++++++++++++++++++
.../@stdlib/utils/copy-within/docs/repl.txt | 45 +++
.../utils/copy-within/docs/types/index.d.ts | 58 ++++
.../utils/copy-within/docs/types/test.ts | 42 +++
.../utils/copy-within/examples/index.js | 41 +++
.../@stdlib/utils/copy-within/lib/index.js | 49 ++++
.../@stdlib/utils/copy-within/lib/main.js | 132 +++++++++
.../@stdlib/utils/copy-within/package.json | 78 +++++
.../@stdlib/utils/copy-within/test/test.js | 152 ++++++++++
13 files changed, 1243 insertions(+)
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/README.md
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.length.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.object.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.typed_array.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/docs/repl.txt
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/docs/types/index.d.ts
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/docs/types/test.ts
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/examples/index.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/lib/index.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/lib/main.js
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/package.json
create mode 100644 lib/node_modules/@stdlib/utils/copy-within/test/test.js
diff --git a/lib/node_modules/@stdlib/utils/copy-within/README.md b/lib/node_modules/@stdlib/utils/copy-within/README.md
new file mode 100644
index 000000000000..fe85ff4e5392
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/README.md
@@ -0,0 +1,131 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2020 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.
+
+-->
+
+# copyWithin
+
+> Copy a part of a collection to another location in the same collection.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var copyWithin = require( '@stdlib/utils/copy-within' );
+```
+
+#### copyWithin( collection, target\[, start\[, end\]\] )
+
+Copies a part of a `collection` to another location in the same `collection`. A `collection` may be either an [`Array`][mdn-array], [`Typed Array`][mdn-typed-array], or an array-like [`Object`][mdn-object] (i.e., an [`Object`][mdn-object] having a valid writable `length` property).
+
+```javascript
+var arr = [ 1, 2, 3, 4, 5 ];
+
+var out = copyWithin( arr, 0, 2, 4 );
+// returns [ 3, 4, 3, 4, 5 ]
+
+var bool = ( out === arr );
+// returns true
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Float64Array= require( '@stdlib/array/float64' );
+var copyWithin = require( '@stdlib/utils/copy-within' );
+
+var bool;
+var arr;
+var out;
+
+arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+out = copyWithin( arr, 0, 2, 4 );
+// returns <Float64Array>[ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+
+bool = ( out === arr );
+// returns true
+
+arr = [ 1, 2, 3, 4, 5 ];
+out = copyWithin( arr, 0, 3, 4 );
+// returns [ 4, 2, 3, 4, 5 ]
+
+bool = ( out === arr );
+// returns true
+
+out = copyWithin( arr, 1, 3 );
+// returns [ 4, 4, 5, 4, 5 ]
+
+bool = ( out === arr );
+// returns true
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays
+
+[mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+</section>
+
+<!-- /.links -->
diff --git a/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.js b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.js
new file mode 100644
index 000000000000..86362afad8d5
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.js
@@ -0,0 +1,53 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 isCollection = require( '@stdlib/assert/is-collection' );
+var pkg = require( './../package.json' ).name;
+var copyWithin = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg+'::array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.length.js
new file mode 100644
index 000000000000..49397b37659c
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.length.js
@@ -0,0 +1,128 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 isCollection = require( '@stdlib/assert/is-collection' );
+var typedarray = require( '@stdlib/array/typed' );
+var pkg = require( './../package.json' ).name;
+var copyWithin = require( './../lib' );
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @param {string} dtype - data type
+* @returns {Function} benchmark function
+*/
+function createBenchmark( len, dtype ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < len; i++ ) {
+ arr[ i ] = i;
+ }
+ arr = typedarray( arr, dtype );
+ return benchmark;
+
+ /**
+ * Benchmark function.
+ *
+ * @private
+ * @param {Benchmark} b - benchmark instance
+ */
+ function benchmark( b ) {
+ var out;
+ var i;
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = copyWithin( arr, i%len );
+ if ( !isCollection( out ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( out ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ 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, 'float64' );
+ bench( pkg+':len='+len+',dtype=float64', f );
+
+ f = createBenchmark( len, 'float32' );
+ bench( pkg+':len='+len+',dtype=float32', f );
+
+ f = createBenchmark( len, 'int32' );
+ bench( pkg+':len='+len+',dtype=int32', f );
+
+ f = createBenchmark( len, 'int16' );
+ bench( pkg+':len='+len+',dtype=int16', f );
+
+ f = createBenchmark( len, 'int8' );
+ bench( pkg+':len='+len+',dtype=int8', f );
+
+ f = createBenchmark( len, 'uint32' );
+ bench( pkg+':len='+len+',dtype=uint32', f );
+
+ f = createBenchmark( len, 'uint16' );
+ bench( pkg+':len='+len+',dtype=uint16', f );
+
+ f = createBenchmark( len, 'uint8' );
+ bench( pkg+':len='+len+',dtype=uint8', f );
+
+ f = createBenchmark( len, 'uint8c' );
+ bench( pkg+':len='+len+',dtype=uint8c', f );
+ }
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.object.js b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.object.js
new file mode 100644
index 000000000000..5a4538a2144f
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.object.js
@@ -0,0 +1,62 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 isCollection = require( '@stdlib/assert/is-collection' );
+var pkg = require( './../package.json' ).name;
+var copyWithin = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg+'::object', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = {
+ 'length': 10,
+ '0': 0,
+ '1': 1,
+ '2': 2,
+ '3': 3,
+ '4': 4,
+ '5': 5,
+ '6': 6,
+ '7': 7,
+ '8': 8,
+ '9': 9
+ };
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.typed_array.js b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.typed_array.js
new file mode 100644
index 000000000000..23bff2f983ca
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/benchmark/benchmark.typed_array.js
@@ -0,0 +1,272 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 isCollection = require( '@stdlib/assert/is-collection' );
+var Float32Array = require( '@stdlib/array/float32' );
+var Float64Array = require( '@stdlib/array/float64' );
+var Int8Array = require( '@stdlib/array/int8' );
+var Int16Array = require( '@stdlib/array/int16' );
+var Int32Array = require( '@stdlib/array/int32' );
+var Uint8Array = require( '@stdlib/array/uint8' );
+var Uint8ClampedArray = require( '@stdlib/array/uint8c' );
+var Uint16Array = require( '@stdlib/array/uint16' );
+var Uint32Array = require( '@stdlib/array/uint32' );
+var pkg = require( './../package.json' ).name;
+var copyWithin = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg+'::float64array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Float64Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::float32array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Float32Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::int32array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Int32Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::uint32array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Uint32Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::int16array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Int16Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::uint16array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Uint16Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::int8array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Int8Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::uint8array', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Uint8Array( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
+
+bench( pkg+'::uint8clampedarray', function benchmark( b ) {
+ var arr;
+ var i;
+
+ arr = [];
+ for ( i = 0; i < 10; i++ ) {
+ arr.push( i );
+ }
+
+ arr = new Uint8ClampedArray( arr );
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ arr = copyWithin( arr, i % 10 );
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ }
+ b.toc();
+ if ( !isCollection( arr ) ) {
+ b.fail( 'should return an array-like object' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+});
diff --git a/lib/node_modules/@stdlib/utils/copy-within/docs/repl.txt b/lib/node_modules/@stdlib/utils/copy-within/docs/repl.txt
new file mode 100644
index 000000000000..2ad92ad92849
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/docs/repl.txt
@@ -0,0 +1,45 @@
+
+{{alias}}( collection, target[, start[, end]] )
+ Copies a part of a collection to another location in the same collection.
+
+ Parameters
+ ----------
+ collection: Array|TypedArray|Object
+ A collection. If the collection is an `Object`, the collection should
+ be array-like.
+
+ target: integer
+ Zero-based index at which to copy the sequence to.
+
+ start: integer (optional)
+ Zero-based index at which to start copying elements from. Default: 0.
+
+ end: integer (optional)
+ Zero-based index at which to end copying elements from.
+ Default: collection.length.
+
+ Returns
+ -------
+ out: Array|TypedArray|Object
+ Updated collection.
+
+ Examples
+ --------
+ // Arrays:
+ > var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+ > arr = {{alias}}( arr, 0, 2, 4 )
+ [ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+
+ // Typed arrays:
+ > arr = new {{alias:@stdlib/array/float64}}( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+ > arr = {{alias}}( arr, 1 )
+ <Float64Array>[ 1.0, 1.0, 2.0, 3.0, 4.0 ]
+
+ // Array-like object:
+ > arr = { 'length': 5, '0': 1.0, '1': 2.0, '2': 3.0, '3': 4.0, '4': 5.0 };
+ > arr = {{alias}}( arr, 0, 1, 4 )
+ { 'length': 5, '0': 2.0, '1': 3.0, '2': 4.0, '3': 4.0, '4': 5.0 }
+
+ See Also
+ --------
+
diff --git a/lib/node_modules/@stdlib/utils/copy-within/docs/types/index.d.ts b/lib/node_modules/@stdlib/utils/copy-within/docs/types/index.d.ts
new file mode 100644
index 000000000000..6e308a17cda9
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/docs/types/index.d.ts
@@ -0,0 +1,58 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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.
+*/
+
+// TypeScript Version: 2.0
+
+/// <reference types="@stdlib/types"/>
+
+import { Collection } from '@stdlib/types/object';
+
+/**
+* Copies a part of a collection to another location in the same collection.
+*
+* @param collection - collection
+* @param target - target index
+* @param start - source start index (default: 0)
+* @param end - source end index (default: collection.length)
+* @throws first argument must be a collection
+* @throws second argument must be an integer
+* @throws third argument must be an integer
+* @throws fourth argument must be an integer
+* @returns updated collection
+*
+* @example
+* var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+*
+* arr = copyWithin( arr, 0, 2, 4 );
+* // returns [ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+*
+* @example
+* var Float64Array = require( `@stdlib/array/float64` );
+*
+* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+* // returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]
+*
+* arr = copyWithin( arr, 1 );
+* // returns <Float64Array>[ 1.0, 1.0, 2.0, 3.0, 4.0 ]
+*/
+declare function copyWithin( collection: Collection, target: number, start?: number, end?: number ): Collection; // tslint-disable-line max-line-length
+
+
+// EXPORTS //
+
+export = copyWithin;
diff --git a/lib/node_modules/@stdlib/utils/copy-within/docs/types/test.ts b/lib/node_modules/@stdlib/utils/copy-within/docs/types/test.ts
new file mode 100644
index 000000000000..7a03240847bd
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/docs/types/test.ts
@@ -0,0 +1,42 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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.
+*/
+
+import copyWithin = require( './index' );
+
+
+// TESTS //
+
+// The function returns the updated input collection ...
+{
+ copyWithin( [ 2, 3 ], 1 ); // $ExpectType Collection
+ copyWithin( [ 'a', 'b', 'c' ], 0, 1 ); // $ExpectType Collection
+ copyWithin( [ true, false ], 1 ); // $ExpectType Collection
+ copyWithin( [ true, true, 1, 2, 3 ], 1, 2, 4 ); // $ExpectType Collection
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a collection...
+{
+ copyWithin( true ); // $ExpectError
+ copyWithin( false ); // $ExpectError
+ copyWithin( 5 ); // $ExpectError
+}
+
+// The compiler throws an error if the function is not provided at least one argument...
+{
+ copyWithin(); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/utils/copy-within/examples/index.js b/lib/node_modules/@stdlib/utils/copy-within/examples/index.js
new file mode 100644
index 000000000000..84ef4c7975b6
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/examples/index.js
@@ -0,0 +1,41 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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';
+
+var Float64Array = require( '@stdlib/array/float64' );
+var copyWithin = require( './../lib' );
+
+var arr;
+var out;
+
+arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+out = copyWithin( arr, 1 );
+console.log( out );
+// => <Float64Array>[ 1.0, 1.0, 2.0, 3.0, 4.0 ]
+
+console.log( out === arr );
+// => true
+
+arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+out = copyWithin( arr, 0, 2, 4 );
+console.log( out );
+// => [ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+
+console.log( out === arr );
+// => true
diff --git a/lib/node_modules/@stdlib/utils/copy-within/lib/index.js b/lib/node_modules/@stdlib/utils/copy-within/lib/index.js
new file mode 100644
index 000000000000..a87a8a1ce34f
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/lib/index.js
@@ -0,0 +1,49 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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';
+
+/**
+* Copy a part of a collection to another location in the same collection.
+*
+* @module @stdlib/utils/copy-within
+*
+* @example
+* var copyWithin = require( '@stdlib/utils/copy-within' );
+* var Float64Array = require( '@stdlib/array/float64' );
+*
+* var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+*
+* arr = copyWithin( arr, 0, 2, 4 );
+* // returns [ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+*
+* arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+* // returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]
+*
+* arr = copyWithin( arr, 1 );
+* // returns <Float64Array>[ 1.0, 1.0, 2.0, 3.0, 4.0 ]
+*/
+
+// MODULES //
+
+var copyWithin = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = copyWithin;
diff --git a/lib/node_modules/@stdlib/utils/copy-within/lib/main.js b/lib/node_modules/@stdlib/utils/copy-within/lib/main.js
new file mode 100644
index 000000000000..89c0685914a4
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/lib/main.js
@@ -0,0 +1,132 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 isCollection = require( '@stdlib/assert/is-collection' );
+var isInteger = require( '@stdlib/assert/is-integer' );
+var max = require( '@stdlib/math/base/special/max' );
+var min = require( '@stdlib/math/base/special/min' );
+
+
+// MAIN //
+
+/**
+* Copies a part of a collection to another location in the same collection.
+*
+* @param {Collection} collection - input collection
+* @param {integer} target - target index
+* @param {integer} [start=0] - source start index
+* @param {integer} [end=collection.length] - source end index
+* @throws {TypeError} first argument must be a collection
+* @throws {TypeError} second argument must be an integer
+* @throws {TypeError} third argument must be an integer
+* @throws {TypeError} fourth argument must be an integer
+* @returns {Collection} modified input collection
+*
+* @example
+* var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+*
+* arr = copyWithin( arr, 0, 2, 4 );
+* // returns [ 3.0, 4.0, 3.0, 4.0, 5.0 ]
+*
+* @example
+* var Float64Array = require( '@stdlib/array/float64' );
+*
+* var arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+* // returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]
+*
+* arr = copyWithin( arr, 0, 3, 4 );
+* // returns <Float64Array>[ 4.0, 2.0, 3.0, 4.0, 5.0 ]
+*/
+function copyWithin( collection, target, start, end ) {
+ var direction;
+ var count;
+ var final;
+ var from;
+ var len;
+ var to;
+ if ( !isCollection( collection ) ) {
+ throw new TypeError( 'invalid argument. First argument must be a collection. Value: `'+collection+'`.' );
+ }
+ if ( !isInteger( target ) ) {
+ throw new TypeError( 'invalid argument. Second argument must be an integer. Value: `'+target+'`.' );
+ }
+
+ len = collection.length;
+ from = 0;
+ final = len;
+ if ( arguments.length > 2 ) {
+ if ( !isInteger( start ) ) {
+ throw new TypeError( 'invalid argument. Third argument must be an integer. Value: `'+start+'`.' );
+ }
+ from = start;
+
+ if ( arguments.length === 4 ) {
+ if ( !isInteger( end ) ) {
+ throw new TypeError( 'invalid argument. Fourth argument must be an integer. Value: `'+end+'`.' );
+ }
+ final = end;
+ }
+ }
+
+ to = target;
+ if ( to < 0 ) {
+ to = max( 0, to + len );
+ } else {
+ to = min( to, len );
+ }
+ if ( from < 0 ) {
+ from = max( 0, from + len );
+ } else {
+ from = min( from, len );
+ }
+ if ( final < 0 ) {
+ final = max( 0, final + len );
+ } else {
+ final = min( final, len );
+ }
+
+ count = min( final-from, len-to );
+ direction = 1;
+ if ( from < to && to < ( from+count ) ) {
+ direction = -1;
+ from += count - 1;
+ to += count - 1;
+ }
+
+ while ( count > 0 ) {
+ if ( from in collection ) {
+ collection[ to ] = collection[ from ];
+ } else {
+ delete collection[ to ];
+ }
+ from += direction;
+ to += direction;
+ count -= 1;
+ }
+
+ return collection;
+}
+
+
+// EXPORTS //
+
+module.exports = copyWithin;
diff --git a/lib/node_modules/@stdlib/utils/copy-within/package.json b/lib/node_modules/@stdlib/utils/copy-within/package.json
new file mode 100644
index 000000000000..a32a6b4e3f2c
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/package.json
@@ -0,0 +1,78 @@
+{
+ "name": "@stdlib/utils/copy-within",
+ "version": "0.0.0",
+ "description": "Copy a part of a collection to another location in the same collection.",
+ "license": "Apache-2.0",
+ "author": {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ },
+ "contributors": [
+ {
+ "name": "The Stdlib Authors",
+ "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+ }
+ ],
+ "main": "./lib",
+ "directories": {
+ "benchmark": "./benchmark",
+ "doc": "./docs",
+ "example": "./examples",
+ "lib": "./lib",
+ "test": "./test"
+ },
+ "types": "./docs/types",
+ "scripts": {},
+ "homepage": "https://github.com/stdlib-js/stdlib",
+ "repository": {
+ "type": "git",
+ "url": "git://github.com/stdlib-js/stdlib.git"
+ },
+ "bugs": {
+ "url": "https://github.com/stdlib-js/stdlib/issues"
+ },
+ "dependencies": {},
+ "devDependencies": {},
+ "engines": {
+ "node": ">=0.10.0",
+ "npm": ">2.7.0"
+ },
+ "os": [
+ "aix",
+ "darwin",
+ "freebsd",
+ "linux",
+ "macos",
+ "openbsd",
+ "sunos",
+ "win32",
+ "windows"
+ ],
+ "keywords": [
+ "stdlib",
+ "stdutils",
+ "stdutil",
+ "utilities",
+ "utility",
+ "utils",
+ "util",
+ "array",
+ "typed array",
+ "typed-array",
+ "float64array",
+ "float32array",
+ "int32array",
+ "uint32array",
+ "int16array",
+ "uint16array",
+ "int8array",
+ "uint8array",
+ "uint8clampedarray",
+ "array-like",
+ "object",
+ "obj",
+ "copywithin",
+ "copy within",
+ "memmove"
+ ]
+}
diff --git a/lib/node_modules/@stdlib/utils/copy-within/test/test.js b/lib/node_modules/@stdlib/utils/copy-within/test/test.js
new file mode 100644
index 000000000000..a3f97e1fcb6b
--- /dev/null
+++ b/lib/node_modules/@stdlib/utils/copy-within/test/test.js
@@ -0,0 +1,152 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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.
+*/
+
+/* eslint-disable object-curly-newline */
+
+'use strict';
+
+// MODULES //
+
+var tape = require( 'tape' );
+var Float64Array = require( '@stdlib/array/float64' );
+var copyWithin = require( './../lib' );
+
+
+// TESTS //
+
+tape( 'main export is a function', function test( t ) {
+ t.ok( true, __filename );
+ t.strictEqual( typeof copyWithin, 'function', 'main export is a function' );
+ t.end();
+});
+
+tape( 'the function throws an error if not provided either an array, typed array, or an array-like object', function test( t ) {
+ var values;
+ var i;
+
+ values = [
+ '5',
+ 5,
+ NaN,
+ true,
+ false,
+ null,
+ undefined,
+ function noop() {},
+ new Date(),
+ {},
+ { 'length': null },
+ { 'length': -1 },
+ { 'length': 3.14 }
+ ];
+
+ for ( i = 0; i < values.length; i++ ) {
+ t.throws( badValue( values[ i ] ), TypeError, 'throws a type error when provided '+values[i] );
+ }
+ t.end();
+
+ function badValue( value ) {
+ return function badValue() {
+ copyWithin( value, 0 );
+ };
+ }
+});
+
+tape( 'the function copies a part of an array to another location in the same array', function test( t ) {
+ var expected;
+ var arr;
+ var out;
+
+ arr = [ 1.0, 2.0, 3.0, 4.0, 5.0 ];
+ out = copyWithin( arr, 0, 2, 4 );
+
+ t.strictEqual( out, arr, 'returns expected value' );
+
+ expected = [ 3.0, 4.0, 3.0, 4.0, 5.0 ];
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ out = copyWithin( arr, 2, 1, 5 ); // target is after start
+
+ expected = [ 3.0, 4.0, 4.0, 3.0, 4.0 ];
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function copies a part of an array-like object to another location in the same array-like object', function test( t ) {
+ var expected;
+ var arr;
+ var out;
+
+ arr = {
+ 'length': 5,
+ '0': 1.0,
+ '1': 2.0,
+ '2': 3.0,
+ '3': 4.0,
+ '4': 5.0
+ };
+ out = copyWithin( arr, 0, 2, 4 );
+
+ t.strictEqual( out, arr, 'returns expected value' );
+
+ expected = {
+ 'length': 5,
+ '0': 3.0,
+ '1': 4.0,
+ '2': 3.0,
+ '3': 4.0,
+ '4': 5.0
+ };
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ out = copyWithin( arr, 2, 1, 5 ); // target is after start
+
+ expected = {
+ 'length': 5,
+ '0': 3.0,
+ '1': 4.0,
+ '2': 4.0,
+ '3': 3.0,
+ '4': 4.0
+ };
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ t.end();
+});
+
+tape( 'the function copies a part of a typed array to another location in the same typed array', function test( t ) {
+ var expected;
+ var arr;
+ var out;
+
+ arr = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
+ out = copyWithin( arr, 0, 2, 4 );
+
+ t.strictEqual( out, arr, 'returns expected value' );
+
+ expected = new Float64Array( [ 3.0, 4.0, 3.0, 4.0, 5.0 ] );
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ out = copyWithin( arr, 2, 1, 5 ); // target is after start
+
+ expected = new Float64Array( [ 3.0, 4.0, 4.0, 3.0, 4.0 ] );
+ t.deepEqual( arr, expected, 'returns expected value' );
+
+ t.end();
+});