stdlib-js / stdlib-js/stdlib

[RFC]: add `ndarray/tensor3d/ctor`

Abierto
#14,959 0 comentarios 0 reacciones 1 asignado Reclamado por @0PrashantYadav0 Ver en GitHub
Accepted Feature RFC
Lenguaje dominante
JavaScript
Estrellas
6k
Forks
1.3k
Merge medio
1 d 3 h
PR fusionados (30 d)
611

Descripción

### Description

This RFC proposes adding `@stdlib/ndarray/tensor3d/ctor`, the three-dimensional counterpart to the existing `@stdlib/ndarray/vector/ctor` and `@stdlib/ndarray/matrix/ctor` packages, as the next step toward providing dedicated dimensional constructors up to five dimensions.

#### Motivation

As with `ndarray/vector/*` and `ndarray/matrix/*`, these APIs provide convenient dedicated interfaces for constructing arrays of a known dimensionality from nested arrays, together with the corresponding validation. For example,

```javascript
var x = new Float64Tensor3D( [ [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], [ [ 7, 8, 9 ], [ 10, 11, 12 ] ] ] );
// returns
```

Dimensional constructors up to 5D cover more than 80% of end-user use cases for ndarray dimensionality. Arrays of six or more dimensions are markedly less common and are adequately served by the general-purpose `@stdlib/ndarray/ctor` and `@stdlib/ndarray/array` APIs.

Supported options (`readonly`, `mode`, `submode`, `order`) and their defaults are unchanged from `matrix/ctor`.

#### Future plan

This RFC covers `tensor3d/ctor` and the typed constructors. The sequence:

1. **The parent `@stdlib/ndarray/tensor3d` namespace package** — handled separately by a maintainer. Not done here.
2. **Typed 3D constructors** — **done**. The complete set matching `vector`: `bool` (`BooleanTensor3D`), `complex64`, `complex128`, `float32`, `float64`, `int8`, `int16`, `int32`, `uint8`, `uint8c` (`Uint8ClampedTensor3D`), `uint16`, `uint32`. Each is a thin wrapper over `require( '@stdlib/ndarray/tensor3d/ctor' ).factory( dtype )` accompanied by documentation, types, tests, and benchmarks.
3. **`ndarray/tensor4d`** — constructor plus typed packages, using `@stdlib/array/base/flatten4d`.
4. **`ndarray/tensor5d`** — constructor plus typed packages, using `@stdlib/array/base/flatten5d`, completing coverage through five dimensions.

Constructor names follow the `vector` convention rather than a literal data type transliteration: `bool` exports `BooleanTensor3D` and `uint8c` exports `Uint8ClampedTensor3D`. Package descriptions use the repository's dominant phrasing for integer types ("signed 32-bit integer", used by 39 packages) rather than the inverted form used by `matrix/int32` and two others.

### Related Issues

None.

### Questions

No.

Three questions were raised while drafting and have since been resolved by a maintainer:

1. *Should the thin parent `@stdlib/ndarray/tensor3d` namespace package land together with `tensor3d/ctor`?* — **No.** It will be handled separately by a maintainer.
2. *Should the typed constructors mirror the `matrix` set or the broader `vector` set?* — **The full set**, matching `vector`. Work is already in progress to bring the `matrix` namespace up to the complete set.
3. *Should the `from_arraybuffer.js` `TODO` be tackled as part of this work?* — **No.** Work on `@stdlib/ndarray/from-arraybuffer` is already in progress separately; copying the helper is acceptable for now.

### 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:`.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.