stdlib-js / stdlib-js/stdlib

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

Đang mở
#14,959 0 bình luận 0 reaction 1 người được giao Được @0PrashantYadav0 nhận Xem trên GitHub
Accepted Feature RFC
Ngôn ngữ chính
JavaScript
Star
6k
Fork
1.3k
Merge trung bình
1 ngày 3 giờ
Pull request đã merge (30 ngày)
611

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.