Description
This RFC proposes refactoring the @stdlib/complex namespace into separate sub-namespaces for float32 and float64.
Currently, the @stdlib/complex is a flat(ish) namespace, containing top-level packages which are tailored to specific data types.
$ make list-pkgs-tree LIST_PKGS_TREE_DIR="$PWD/lib/node_modules/@stdlib/complex"
@stdlib
└── complex
├── base
│ ├── assert
│ │ ├── is-equal
│ │ ├── is-equalf
│ │ ├── is-not-equal
│ │ ├── is-not-equalf
│ │ ├── is-same-value-zero
│ │ ├── is-same-value-zerof
│ │ ├── is-same-value
│ │ └── is-same-valuef
│ ├── cast-return
│ ├── parse
│ └── wrap-function
├── cmplx
├── conj
├── conjf
├── ctors
├── dtype
├── dtypes
├── float32
├── float64
├── imag
├── imagf
├── parse-float32
├── parse-float64
├── promotion-rules
├── real
├── realf
├── reim
├── reimf
├── reviver-float32
├── reviver-float64
└── reviver
For example, for double-precision complex floating-point numbers, we have
@stdlib/complex/conj@stdlib/complex/float64@stdlib/complex/imag@stdlib/complex/parse-float64@stdlib/complex/real@stdlib/complex/reim@stdlib/complex/reviver-float64
Similarly, we have equivalent packages for single-precision complex floating-point numbers.
Accordingly, in order to distinguish double- and single-precision variants, we resort to suffixes (e.g., *f or -floatXX). This has worked fine and mirrors @stdlib/math/base/special/*.
However, this structure departs from the structure of @stdlib/number/*, where number dtypes and their associated functionality is broken down into sub-namespaces. This has the advantage in that we can avoid suffix name pollution and have similarly named packages across each of the different numeric data types. This will be especially useful when we add base operations (e.g., @stdlib/number/int32/base/add), where for many numeric dtypes (e.g., int8, uint8, etc), we don't have suffix conventions (i.e., we have no int8 equivalent of f and are unlikely to ever have such an equivalent).
Accordingly, what this RFC proposes is a refactoring of the @stdlib/complex/* namespace to match the @stdlib/number/* namespace. E.g.,
@stdlib/complex/float64/ctor
@stdlib/complex/float64/real@stdlib/complex/float64/imag@stdlib/complex/float64/add- ...
@stdlib/complex/float32/ctor
@stdlib/complex/float32/real (no suffix!)@stdlib/complex/float32/imag (no suffix!)@stdlib/complex/float32/add (no suffix!)- ...
@stdlib/complex/ctors@stdlib/complex/cmplx@stdlib/complex/reviver- ...
where we keep the APIs which operate on or return either complex dtype at the top-level.
A consequence of this refactoring is that it should help make things a bit cleaner in the top-level @stdlib/complex namespace when adding support for half-precision complex floating-point numbers (as needed based on future inclusion of Float16Array in ECMAScript) and allow us to avoid needing to use a new suffix to differentiate the associated APIs.
As it is, that @stdlib/number and @stdlib/complex are organized differently has been a source of friction for me and having organizational parity seems more intuitive.
Related Issues
No.
Questions
No.
Other
The migration path would be as follows:
- Rename
@stdlib/complex/float32 and @stdlib/complex/float64 to @stdlib/complex/float32/ctor and @stdlib/complex/float64/ctor, respectively.
- Update all
require paths using those packages.
- Copy dtype-specific complex packages to their respective sub-namespaces.
- Update all
require paths using the dtype-specific complex packages.
- Remove all dtype-specific complex packages from the top-level
@stdlib/complex namespace.
cc @Planeshifter
Checklist
Description
This RFC proposes refactoring the
@stdlib/complexnamespace into separate sub-namespaces forfloat32andfloat64.Currently, the
@stdlib/complexis a flat(ish) namespace, containing top-level packages which are tailored to specific data types.For example, for double-precision complex floating-point numbers, we have
@stdlib/complex/conj@stdlib/complex/float64@stdlib/complex/imag@stdlib/complex/parse-float64@stdlib/complex/real@stdlib/complex/reim@stdlib/complex/reviver-float64Similarly, we have equivalent packages for single-precision complex floating-point numbers.
Accordingly, in order to distinguish double- and single-precision variants, we resort to suffixes (e.g.,
*for-floatXX). This has worked fine and mirrors@stdlib/math/base/special/*.However, this structure departs from the structure of
@stdlib/number/*, where number dtypes and their associated functionality is broken down into sub-namespaces. This has the advantage in that we can avoid suffix name pollution and have similarly named packages across each of the different numeric data types. This will be especially useful when we add base operations (e.g.,@stdlib/number/int32/base/add), where for many numeric dtypes (e.g.,int8,uint8, etc), we don't have suffix conventions (i.e., we have noint8equivalent offand are unlikely to ever have such an equivalent).Accordingly, what this RFC proposes is a refactoring of the
@stdlib/complex/*namespace to match the@stdlib/number/*namespace. E.g.,@stdlib/complex/float64/ctor@stdlib/complex/float64/real@stdlib/complex/float64/imag@stdlib/complex/float64/add@stdlib/complex/float32/ctor@stdlib/complex/float32/real(no suffix!)@stdlib/complex/float32/imag(no suffix!)@stdlib/complex/float32/add(no suffix!)@stdlib/complex/ctors@stdlib/complex/cmplx@stdlib/complex/reviverwhere we keep the APIs which operate on or return either complex dtype at the top-level.
A consequence of this refactoring is that it should help make things a bit cleaner in the top-level
@stdlib/complexnamespace when adding support for half-precision complex floating-point numbers (as needed based on future inclusion ofFloat16Arrayin ECMAScript) and allow us to avoid needing to use a new suffix to differentiate the associated APIs.As it is, that
@stdlib/numberand@stdlib/complexare organized differently has been a source of friction for me and having organizational parity seems more intuitive.Related Issues
No.
Questions
No.
Other
The migration path would be as follows:
@stdlib/complex/float32and@stdlib/complex/float64to@stdlib/complex/float32/ctorand@stdlib/complex/float64/ctor, respectively.requirepaths using those packages.requirepaths using the dtype-specific complex packages.@stdlib/complexnamespace.cc @Planeshifter
Checklist
RFC:.