RFC: add functional equivalent of `Array.prototype.copyWithin`

[kgryte]

Checklist

Please ensure the following tasks are completed before submitting a feature request.

• Read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

Description

Description of the feature request.

This RFC proposes to add a "functional" equivalent of Array.prototype.copyWithin and TypedArray.prototype.copyWithin.

Package: @stdlib/utils/copy-within
Alias: copyWithin

The interface would be as follows:

/**
* @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
* @returns {Collection} modified input collection
*/
function copyWithin( collection, target ) {
    if ( !isCollection( collection ) ) {
        throw new TypeError( '...' );
    }
    // implementation...
}

If a provided collection has a built-in copyWithin method, the implementation would defer to that method. Otherwise, the implementation would provide a "polyfill", thus extending copyWithin support to environments lacking the built-in API for Array and TypedArray.

Related Issues

Does this feature request have any related issues?

No.

Questions

Any questions for reviewers?

No.

Other

Any other information relevant to this feature request? This may include screenshots, references, sample output, and/or implementation notes.

No.