stdlib-js / stdlib-js/stdlib

[RFC]: achieve ndarray API parity with built-in JavaScript arrays

Offen
#2,656 31 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
difficulty: 4 Feature JavaScript Needs Discussion priority: High RFC
Vorherrschende Sprache
JavaScript
Sterne
6k
Forks
1.3k
Ø Merge
1 T. 3 Std.
Gemergte PRs (30 T.)
611

Beschreibung

### 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/*`

- [x] `Array.prototype.at`

- `ndarray/at`

- [x] `Array.prototype.entries`

- `ndarray/iter/entries`

- [x] `Array.prototype.every`

- `ndarray/every`

- [x] `Array.prototype.forEach`

- `ndarray/for-each`

- [x] `Array.prototype.map`

- `ndarray/map`

- [x] `Array.prototype.filter`

- `ndarray/filter`

- [x] `Array.prototype.slice`

- `ndarray/slice`

- [x] `Array.prototype.keys`

- `ndarray/iter/indices`

- [x] `Array.prototype.values`

- `ndarray/iter/values`

- [x] `Array.prototype.includes`

- `ndarray/includes`

- [x] `Array.prototype.indexOf`

- `blas/ext/index-of`

- [x] `Array.prototype.find`

- `ndarray/base/find`
- `ndarray/find`

- [x] `Array.prototype.findIndex`

- `blas/ext/find-index`

- [x] `Array.prototype.lastIndexOf`

- `blas/ext/last-index-of`

- [x] `Array.prototype.some`

- `ndarray/any`

- [x] `Array.prototype.findLast`

- `ndarray/find-last`

- [x] `Array.prototype.findLastIndex`

- `blas/ext/find-last-index`

- [x] `Array.prototype.reverse`

- `ndarray/reverse`

- [x] `Array.prototype.toReversed`

- `ndarray/base/to-reversed`
- `ndarray/reversed`

- [x] `Array.prototype.sort`

- multiple functions for different sorting algorithms.
- `blas/ext/sorthp`.

- [x] `Array.prototype.toSorted`

- multiple functions for different sorting algorithms.
- `blas/ext/to-sortedhp`

- [x] `Array.prototype.fill`

- `ndarray/fill` and `ndarray/fill-by`
- `ndarray/fill-slice`

- [x] `Array.prototype.flat`

- `ndarray/flatten`

- [ ] `Array.prototype.reduce`

- reduction; specify one or more axes

- [x] `Array.prototype.concat`

- `ndarray/concat`

- [ ] `Array.prototype.copyWithin` (WIP)

- 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.
- Slice + assign?
- Temporary buffer for when there is overlap.

- [ ] `Array.prototype.reduceRight`

- reduction; specify one or more axes
- iterate in reverse direction

- [x] `Array.prototype.flatMap`

- `ndarray/flatten-by`

- [x] `Array.prototype.join`

- `blas/ext/join`

- [x] `Array.prototype.pop`

- `ndarray/pop`

- [x] `Array.prototype.push`

- `ndarray/concat1d`

- [x] `Array.prototype.shift`

- `ndarray/shift`

- [ ] `Array.prototype.splice` (WIP)

- needs R&D
- would involving slicing, concatenation, and data copy

- [x] `Array.prototype.toLocaleString` (WIP)

- needs R&D

- [ ] `Array.prototype.toSpliced` (WIP)

- needs R&D

- [x] `Array.prototype.toString` (WIP)

- just call `ndarray.toString()`?

- [x] `Array.prototype.unshift`

- `ndarray/unshift`

- [x] `Array.prototype.with`

- `ndarray/with`

### Base: `ndarray/base/*`

- [x] `Array.prototype.fill`

- `ndarray/base/fill`

- [x] `Array.prototype.forEach`

- `ndarray/base/for-each`

- [x] `Array.prototype.map`

- `ndarray/base/map`

- [x] `Array.prototype.reverse`

- `ndarray/base/reverse`

- [x] `Array.prototype.slice`

- `ndarray/base/slice`

- [x] `Array.prototype.toReversed`

- `ndarray/base/to-reversed`

- [x] `Array.prototype.every`

- `ndarray/base/every-by`

- [x] `Array.prototype.some`
- `ndarray/base/any`

- [x] `Array.prototype.find`
- `ndarray/base/find`

- [x] `Array.prototype.pop`
- `ndarray/base/pop`

- [x] `Array.prototype.shift`
- `ndarray/base/shift`

### Related Issues

None.

### Questions

No.

### Other

No.

### Checklist

- [X] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [X] Searched for existing issues and pull requests.
- [X] The issue name begins with `RFC:`.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Start by reviewing the RFC checklist and the existing ndarray packages it names, including ndarray/base/assign, ndarray/base/nullary, ndarray/base/unary, and the completed APIs under ndarray/*. Compare the remaining reduction, copyWithin, splice, and related proposals with current ndarray behavior and tests. Done requires an agreed scope and design, not just a single implementation.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript
Bereich
data
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
20/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.