Skip to content

Commit 45ac757

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 9bf5bb1 commit 45ac757

File tree

25 files changed

+4028
-291
lines changed

25 files changed

+4028
-291
lines changed

‎CHANGELOG.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@
1010

1111
### Features
1212

13+
- [`e5ddc80`](https://github.com/stdlib-js/stdlib/commit/e5ddc80ad0e60653c61dfc8847ecc65dff6c69f2) - add `outputDataType` to namespace
14+
- [`5e7af03`](https://github.com/stdlib-js/stdlib/commit/5e7af03b8d27240b12f4fbf7bbad86ff57b64917) - add `ndarray/base/output-dtype`
15+
- [`1f3ebc8`](https://github.com/stdlib-js/stdlib/commit/1f3ebc857c1c4b98d4681867b0d738b572631bcd) - add `promoteDataTypes` to namespace
16+
- [`ec51b4f`](https://github.com/stdlib-js/stdlib/commit/ec51b4f38e6bb9a1ad1d6ee7a2d35d0516312e48) - add `ndarray/base/promote-dtypes`
1317
- [`556e832`](https://github.com/stdlib-js/stdlib/commit/556e832729f770a48692fc796fb4d5c9b4b5ae34) - add `unaryStrided1dDispatchFactory` to namespace
1418
- [`1133bce`](https://github.com/stdlib-js/stdlib/commit/1133bceaec004d01bf20932b6334529dc7a79648) - add `unaryStrided1dDispatch` to namespace
1519
- [`8905452`](https://github.com/stdlib-js/stdlib/commit/890545242b456f9e6b85d744993d4e7c97cd0ae7) - add `unaryStrided1d` to namespace
@@ -379,6 +383,12 @@ A total of 15 issues were closed in this release:
379383

380384
<details>
381385

386+
- [`26d65cd`](https://github.com/stdlib-js/stdlib/commit/26d65cd0dc57249b45b35032a3c251e715a9b8ce) - **refactor:** use generalized utility _(by Athan Reines)_
387+
- [`b51882d`](https://github.com/stdlib-js/stdlib/commit/b51882d4f8acb7af8e93109c3b76ab36fcbb3b76) - **refactor:** use generalized utility _(by Athan Reines)_
388+
- [`e5ddc80`](https://github.com/stdlib-js/stdlib/commit/e5ddc80ad0e60653c61dfc8847ecc65dff6c69f2) - **feat:** add `outputDataType` to namespace _(by Athan Reines)_
389+
- [`5e7af03`](https://github.com/stdlib-js/stdlib/commit/5e7af03b8d27240b12f4fbf7bbad86ff57b64917) - **feat:** add `ndarray/base/output-dtype` _(by Athan Reines)_
390+
- [`1f3ebc8`](https://github.com/stdlib-js/stdlib/commit/1f3ebc857c1c4b98d4681867b0d738b572631bcd) - **feat:** add `promoteDataTypes` to namespace _(by Athan Reines)_
391+
- [`ec51b4f`](https://github.com/stdlib-js/stdlib/commit/ec51b4f38e6bb9a1ad1d6ee7a2d35d0516312e48) - **feat:** add `ndarray/base/promote-dtypes` _(by Athan Reines)_
382392
- [`ad9966a`](https://github.com/stdlib-js/stdlib/commit/ad9966a5d6c560c6a4b2c785f2caafdd472b8399) - **refactor:** reuse existing logic by building on `ndarray/base/unary-output-dtype` _(by Athan Reines)_
383393
- [`d2d6c1d`](https://github.com/stdlib-js/stdlib/commit/d2d6c1daa1671c5e174e815640efffe63c7f528f) - **refactor:** reduce code complexity by reducing branching logic _(by Athan Reines)_
384394
- [`0973f6f`](https://github.com/stdlib-js/stdlib/commit/0973f6fd8117253edf90c856b82c97b4e3a9181b) - **docs:** update namespace table of contents [(#6968)](https://github.com/stdlib-js/stdlib/pull/6968) _(by stdlib-bot)_

‎base/binary-output-dtype/lib/main.js

Lines changed: 4 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,7 @@
2020

2121
// MODULES //
2222

23-
var unaryOutputDataType = require( './../../../base/unary-output-dtype' );
24-
var isDataType = require( './../../../base/assert/is-data-type' );
25-
var promotionRules = require( './../../../promotion-rules' );
26-
var format = require( '@stdlib/string/format' );
23+
var outputDataType = require( './../../../base/output-dtype' );
2724

2825

2926
// MAIN //
@@ -34,45 +31,16 @@ var format = require( '@stdlib/string/format' );
3431
* @param {string} xdtype - first input ndarray data type
3532
* @param {string} ydtype - second input ndarray data type
3633
* @param {string} policy - output ndarray data type policy
37-
* @throws {TypeError} second argument must be a recognized data type policy
38-
* @throws {Error} unexpected error
34+
* @throws {TypeError} third argument must be a recognized data type policy
35+
* @throws {Error} must provide data types amenable to type promotion
3936
* @returns {string} output ndarray data type
4037
*
4138
* @example
4239
* var dt = resolve( 'float64', 'float32', 'complex_floating_point' );
4340
* // returns <string>
4441
*/
4542
function resolve( xdtype, ydtype, policy ) {
46-
var dt;
47-
48-
// Check for a policy mandating an explicit data type...
49-
if ( isDataType( policy ) ) {
50-
// When the policy is a specific data type, the output data type should always be the specified data type without consideration for the input data types:
51-
return policy;
52-
}
53-
if ( policy === 'same' ) {
54-
// When the policy is "same", we require that all data types (both input and output) be the same...
55-
if ( xdtype !== ydtype ) {
56-
throw new Error( format( 'invalid arguments. Unable to resolve an output data type. The output data type policy is "same" and yet the input data types are not equal. Data types: [%s, %s].', xdtype, ydtype ) );
57-
}
58-
return xdtype;
59-
}
60-
if ( policy === 'default' || policy === 'default_index' ) {
61-
return unaryOutputDataType( xdtype, policy ); // note: these policies are independent of the input data type, so it doesn't matter what data type we provide as the first argument
62-
}
63-
// For all other policies, we always apply type promotion rules...
64-
dt = promotionRules( xdtype, ydtype );
65-
if ( dt === null || dt === -1 ) {
66-
throw new Error( format( 'invalid arguments. Unable to apply type promotion rules when resolving a data type to which the input data types can be safely cast. Data types: [%s, %s].', xdtype, ydtype ) );
67-
}
68-
// Resolve the output data type by treating this scenario as equivalent to passing the promoted data type as an input to a unary function...
69-
try {
70-
dt = unaryOutputDataType( dt, policy );
71-
} catch ( err ) { // eslint-disable-line no-unused-vars
72-
// We should only get here if the policy is invalid...
73-
throw new TypeError( format( 'invalid argument. Third argument must be a supported data type policy. Value: `%s`.', policy ) );
74-
}
75-
return dt;
43+
return outputDataType( [ xdtype, ydtype ], policy );
7644
}
7745

7846

‎base/lib/index.js

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -670,6 +670,15 @@ setReadOnly( ns, 'offset', require( './../../base/offset' ) );
670670
*/
671671
setReadOnly( ns, 'order', require( './../../base/order' ) );
672672

673+
/**
674+
* @name outputDataType
675+
* @memberof ns
676+
* @readonly
677+
* @type {Function}
678+
* @see {@link module:@stdlib/ndarray/base/output-dtype}
679+
*/
680+
setReadOnly( ns, 'outputDataType', require( './../../base/output-dtype' ) );
681+
673682
/**
674683
* @name outputPolicyEnum2Str
675684
* @memberof ns
@@ -715,6 +724,15 @@ setReadOnly( ns, 'outputPolicyStr2Enum', require( './../../base/output-policy-st
715724
*/
716725
setReadOnly( ns, 'prependSingletonDimensions', require( './../../base/prepend-singleton-dimensions' ) );
717726

727+
/**
728+
* @name promoteDataTypes
729+
* @memberof ns
730+
* @readonly
731+
* @type {Function}
732+
* @see {@link module:@stdlib/ndarray/base/promote-dtypes}
733+
*/
734+
setReadOnly( ns, 'promoteDataTypes', require( './../../base/promote-dtypes' ) );
735+
718736
/**
719737
* @name removeSingletonDimensions
720738
* @memberof ns

‎base/output-dtype/README.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# outputDataType
22+
23+
> Resolve the output ndarray [data type][@stdlib/ndarray/dtypes] from a list of input ndarray [data types][@stdlib/ndarray/dtypes].
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var outputDataType = require( '@stdlib/ndarray/base/output-dtype' );
41+
```
42+
43+
#### outputDataType( dtypes, policy )
44+
45+
Resolves the output ndarray [data type][@stdlib/ndarray/dtypes] from a list of input ndarray [data types][@stdlib/ndarray/dtypes] according to a [data type policy][@stdlib/ndarray/output-dtype-policies].
46+
47+
```javascript
48+
var dt = outputDataType( [ 'int32', 'uint32' ], 'floating_point' );
49+
// returns 'float64'
50+
```
51+
52+
The function supports the following parameters:
53+
54+
- **dtypes**: list of input ndarray [data types][@stdlib/ndarray/dtypes].
55+
- **policy**: output [data type policy][@stdlib/ndarray/output-dtype-policies].
56+
57+
If `policy` is a [data type][@stdlib/ndarray/dtypes], the function always returns the `policy` value (i.e., the second argument).
58+
59+
```javascript
60+
var dt = outputDataType( [ 'float32', 'float32' ], 'float64' );
61+
// returns 'float64'
62+
63+
dt = outputDataType( [ 'int32', 'complex128' ], 'float64' );
64+
// returns 'float64'
65+
66+
// ...
67+
```
68+
69+
</section>
70+
71+
<!-- /.usage -->
72+
73+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
74+
75+
<section class="notes">
76+
77+
## Notes
78+
79+
- When provided more than [data type][@stdlib/ndarray/dtypes], the function **always** applies [type promotion][@stdlib/ndarray/promotion-rules] to the provided data types, except for the following [data type policies][@stdlib/ndarray/output-dtype-policies]:
80+
81+
- `default`
82+
- `default_index`
83+
- `same`
84+
- `<dtype>`
85+
86+
</section>
87+
88+
<!-- /.notes -->
89+
90+
<!-- Package usage examples. -->
91+
92+
<section class="examples">
93+
94+
## Examples
95+
96+
<!-- eslint no-undef: "error" -->
97+
98+
```javascript
99+
var naryFunction = require( '@stdlib/utils/nary-function' );
100+
var unzip = require( '@stdlib/utils/unzip' );
101+
var cartesianProduct = require( '@stdlib/array/base/cartesian-product' );
102+
var dtypes = require( '@stdlib/ndarray/dtypes' );
103+
var logEachMap = require( '@stdlib/console/log-each-map' );
104+
var outputDataType = require( '@stdlib/ndarray/base/output-dtype' );
105+
106+
// Get the list of real-valued data types:
107+
var dt = dtypes( 'real' );
108+
109+
// Define a list of output data type policies:
110+
var policies = [
111+
'default',
112+
'real',
113+
'floating_point',
114+
'complex_floating_point',
115+
'promoted'
116+
];
117+
118+
// Generate data type pairs:
119+
var pairs = cartesianProduct( dt, dt );
120+
121+
// Generate argument pairs:
122+
var args = cartesianProduct( pairs, policies );
123+
124+
// Unzip the argument pair array:
125+
args = unzip( args );
126+
127+
// Resolve output data types:
128+
logEachMap( 'dtypes: (%15s). policy: %-24s. output dtype: %s.', args[ 0 ], args[ 1 ], naryFunction( outputDataType, 2 ) );
129+
```
130+
131+
</section>
132+
133+
<!-- /.examples -->
134+
135+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
136+
137+
<section class="references">
138+
139+
</section>
140+
141+
<!-- /.references -->
142+
143+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
144+
145+
<section class="related">
146+
147+
</section>
148+
149+
<!-- /.related -->
150+
151+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
152+
153+
<section class="links">
154+
155+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray/tree/main/dtypes
156+
157+
[@stdlib/ndarray/output-dtype-policies]: https://github.com/stdlib-js/ndarray/tree/main/output-dtype-policies
158+
159+
[@stdlib/ndarray/promotion-rules]: https://github.com/stdlib-js/ndarray/tree/main/promotion-rules
160+
161+
</section>
162+
163+
<!-- /.links -->

0 commit comments

Comments
 (0)