Description
Description
This RFC proposes achieving ndarray API parity with built-in JavaScript arrays. Built-in JavaScript Array and TypedArray objects have a number of methods for searching, manipulating, sorting, and transforming array data.
The goal of this RFC is to add functional APIs providing equivalent functionality for ndarrays. By providing these APIs, stdlib can offer a powerful toolset using a similar vocabulary and interface design as existing art for working with ndarrays. This should help reduce the barrier to ndarray adoption and encourage their more widespread use.
Note, however, that ndarrays have considerable additional complexity due to their multi-dimensional nature, and, in particular, element-wise iteration requires specialized kernels for handling non-contiguous underlying data.
There does exist precedent in stdlib for such kernels (e.g., ndarray/base/assign, ndarray/base/nullary, and ndarray/base/unary). Those packages also provide C APIs which may or may not be relevant to the functional APIs proposed in this RFC.
What follows is an initial list of Array.prototype.* methods and notes regarding whether an equivalent already exists or what constraints we need to consider when designing ndarray equivalent packages.
Top-level: ndarray/*
-
Array.prototype.atndarray/at
-
Array.prototype.concat -
Array.prototype.copyWithin- specify axis
- how would this work for strided arrays?
- for ideal case, would prefer delegating to array prototype method, as likely faster; for non-ideal case, would need to take special care to avoid overwriting accessed values.
-
Array.prototype.entriesndarray/iter/entries
-
Array.prototype.everyndarray/every(element truthiness) (TODO: unit tests)
-
Array.prototype.fillndarray/fillandndarray/fill-by- will also want
ndarray/slice-fillto provide a slice equivalent tofill( x, start, end ) - potential improvement: an native add-on to allow for acceleration in Node.js
-
Array.prototype.filterndarray/filter
-
Array.prototype.find- reduction; specify one or more axes
-
Array.prototype.findIndex- reduction; specify one or more axes
-
Array.prototype.findLast- reduction; specify one or more axes
-
Array.prototype.findLastIndex- reduction; specify one or more axes
-
Array.prototype.flat- reshape
- likely name
flatten - would we support a depth argument?
- could potentially flatten subarrays (i.e., flatten "stacks")
-
Array.prototype.flatMap- likely name
flatten-by - would we support a depth argument?
- likely name
-
Array.prototype.forEach- wrap "base" implementation
-
Array.prototype.includesndarray/includes- TODO: unit tests
-
Array.prototype.indexOf- reduction; specify one or more axes
-
Array.prototype.join- needs R&D
- how would dimension separators work? a different separator for each dimension? configurable?
-
Array.prototype.keysndarray/iter/indices
-
Array.prototype.lastIndexOf- reduction; specify one or more axes
-
Array.prototype.mapndarray/map
-
Array.prototype.pop- specify the axis along which to remove?
- this would essentially be
slice(0,axis.length-1) - would we return the removed slice?
- not clear. In theory, you'd want to return the new view, but could also return a two-element array (tuple) with the first element being the view and the second element the "popped" view.
-
Array.prototype.push (???)- this would essentially be concat along an axis
- support for broadcasting?
- would require a data copy, no mutation
-
Array.prototype.reduce- reduction; specify one or more axes
-
Array.prototype.reduceRight- reduction; specify one or more axes
- iterate in reverse direction
-
Array.prototype.reverse- create view
- can potentially wrap "base"
-
Array.prototype.shift- specify the axis to remove?
- this would essentially be
slice(1) - would we return the removed slice?
- not clear. In theory, you'd want to return the new view, but could also return a two-element array (tuple) with the first element being the view and the second element the "popped" view.
-
Array.prototype.slicendarray/slice
-
Array.prototype.somendarray/some-by- TODO: unit tests
-
Array.prototype.sort- specify one or more axes
- mutate?
- yes, IMO, as can have
to-sortedby the copy version.
- yes, IMO, as can have
-
Array.prototype.splice- needs R&D
- would involving slicing, concatenation, and data copy
-
Array.prototype.toLocaleString- needs R&D
-
Array.prototype.toReversed- data copy
- can potentially wrap "base"
-
Array.prototype.toSorted- specify one or more axes
- data copy
-
Array.prototype.toSpliced- needs R&D
-
Array.prototype.toString- just call
ndarray.toString()?
- just call
-
Array.prototype.unshift- this would essentially be concat along an axis
- support for broadcasting?
- would require a data copy, no mutation
-
Array.prototype.valuesndarray/iter/values
-
Array.prototype.with- requires data copy
- should be a straightforward application of allocation, call
assignin order to copy, and then set the individual element - ideally, would also include a native add-on which calls to
ndarray/base/assignfor acceleration in Node.js
Base: ndarray/base/*
-
Array.prototype.fillndarray/base/fill
-
Array.prototype.forEachndarray/base/for-each
-
Array.prototype.mapndarray/base/map
-
Array.prototype.reversendarray/base/reverse
-
Array.prototype.slicendarray/base/slice
-
Array.prototype.toReversedndarray/base/to-reversed
-
Array.prototype.somendarray/base/some-by
-
Array.prototype.everyndarray/base/every-by
Related Issues
None.
Questions
No.
Other
No.
Checklist
- I have read and understood the Code of Conduct.
- Searched for existing issues and pull requests.
- The issue name begins with
RFC:.