stdlib-js / stdlib-js/stdlib

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

Ouverte
#14,959 0 commentaires 0 réactions 1 personne assignée Réclamée par @0PrashantYadav0 Voir sur GitHub
Accepted Feature RFC
Langage dominant
JavaScript
Étoiles
6k
Forks
1.3k
Merge moyen
1 j 3 h
PR mergées (30 j)
611

Description

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

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.