Skip to content

Commit d605190

Browse files
G4URAV001G4URAV001
committed
feat(@stdlib/utils/copy-within): add functional equivalent of Array.prototype.copyWithin
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---
1 parent 07f3085 commit d605190

File tree

11 files changed

+1810
-0
lines changed

11 files changed

+1810
-0
lines changed

‎lib/node_modules/@stdlib/utils/copy-within/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# copyWithin
22+
23+
> Copy a sequence of elements within a collection to another location in the same collection.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var copyWithin = require( '@stdlib/utils/copy-within' );
41+
```
42+
43+
#### copyWithin( collection, target\[, start\[, end]] )
44+
45+
Copies a sequence of elements within a collection to another location in the same collection.
46+
47+
```javascript
48+
var arr = [ 1, 2, 3, 4, 5 ];
49+
50+
var out = copyWithin( arr, 0, 3 );
51+
// returns [ 4, 5, 3, 4, 5 ]
52+
```
53+
54+
The function accepts the following arguments:
55+
56+
- **collection**: the input collection.
57+
- **target**: target index (zero-based).
58+
- **start**: source start index (zero-based). Default: 0.
59+
- **end**: source end index (zero-based, non-inclusive). Default: collection.length.
60+
61+
If a provided collection has a built-in `copyWithin` method (e.g., [Array.prototype.copyWithin][mdn-copy-within] or [TypedArray.prototype.copyWithin][mdn-typed-array-copy-within]), the function defers to that method. Otherwise, the function provides a polyfill, thus extending `copyWithin` support to environments lacking the built-in API for Array and TypedArray.
62+
63+
The function supports negative indices, which are interpreted as being relative to the end of the collection. For example, if provided `-2` for `target`, the function interprets the index as `collection.length - 2`.
64+
65+
```javascript
66+
var arr = [ 1, 2, 3, 4, 5 ];
67+
68+
var out = copyWithin( arr, -2, -3, -1 );
69+
// returns [ 1, 2, 3, 3, 4 ]
70+
```
71+
72+
If `target` is greater than or equal to the collection length, nothing is copied. If `target` is positioned after `start` after normalization, copying only happens until the end of the collection length (in other words, `copyWithin` never extends the collection).
73+
74+
```javascript
75+
var arr = [ 1, 2, 3, 4, 5 ];
76+
77+
var out = copyWithin( arr, 10, 0 );
78+
// returns [ 1, 2, 3, 4, 5 ]
79+
```
80+
81+
If `start` is greater than or equal to the collection length, nothing is copied.
82+
83+
```javascript
84+
var arr = [ 1, 2, 3, 4, 5 ];
85+
86+
var out = copyWithin( arr, 0, 10 );
87+
// returns [ 1, 2, 3, 4, 5 ]
88+
```
89+
90+
For Uint8Array inputs, the function uses an optimized implementation that copies in 4-byte increments when possible, providing better performance for large arrays.
91+
92+
</section>
93+
94+
<!-- /.usage -->
95+
96+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
97+
98+
<section class="notes">
99+
100+
## Notes
101+
102+
- The function works like the built-in `Array.prototype.copyWithin` and `TypedArray.prototype.copyWithin` methods but extends support to all collection types.
103+
104+
</section>
105+
106+
<!-- /.notes -->
107+
108+
<!-- Package usage examples. -->
109+
110+
<section class="examples">
111+
112+
## Examples
113+
114+
<!-- eslint no-undef: "error" -->
115+
116+
```javascript
117+
var copyWithin = require( '@stdlib/utils/copy-within' );
118+
119+
// Regular arrays:
120+
var arr = [ 1, 2, 3, 4, 5 ];
121+
console.log( copyWithin( arr, 0, 3 ) );
122+
// => [ 4, 5, 3, 4, 5 ]
123+
124+
arr = [ 1, 2, 3, 4, 5 ];
125+
console.log( copyWithin( arr, 0, 3, 4 ) );
126+
// => [ 4, 2, 3, 4, 5 ]
127+
128+
arr = [ 1, 2, 3, 4, 5 ];
129+
console.log( copyWithin( arr, -2, -3, -1 ) );
130+
// => [ 1, 2, 3, 3, 4 ]
131+
132+
// Typed arrays:
133+
var Uint8Array = require( '@stdlib/array/uint8' );
134+
var typed = new Uint8Array( [ 1, 2, 3, 4, 5 ] );
135+
console.log( copyWithin( typed, 0, 3 ) );
136+
// => <Uint8Array>[ 4, 5, 3, 4, 5 ]
137+
138+
// Array-like objects:
139+
var obj = {
140+
'length': 5,
141+
'0': 1,
142+
'1': 2,
143+
'2': 3,
144+
'3': 4,
145+
'4': 5
146+
};
147+
console.log( copyWithin( obj, 0, 3 ) );
148+
// => { '0': 4, '1': 5, '2': 3, '3': 4, '4': 5, 'length': 5 }
149+
```
150+
151+
</section>
152+
153+
<!-- /.examples -->
154+
155+
<section class="references">
156+
157+
</section>
158+
159+
<!-- /.references -->
160+
161+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
162+
163+
<section class="related">
164+
165+
* * *
166+
167+
## See Also
168+
169+
- <span class="package-name">[`@stdlib/utils/copy`][@stdlib/utils/copy]</span><span class="delimiter">: </span><span class="description">copy or deep clone a value to an arbitrary depth.</span>
170+
171+
</section>
172+
173+
<!-- /.related -->
174+
175+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
176+
177+
<section class="links">
178+
179+
[mdn-copy-within]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin
180+
[mdn-typed-array-copy-within]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/copyWithin
181+
182+
<!-- <related-links> -->
183+
184+
[@stdlib/utils/copy]: https://github.com/stdlib-js/utils-copy
185+
186+
<!-- </related-links> -->
187+
188+
</section>
189+
190+
<!-- /.links -->

0 commit comments

Comments
 (0)