From f88a0df399fa9eed476bf7c935f199d34a4dc612 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 13 Jul 2024 23:32:03 +0000 Subject: [PATCH] Auto-generated commit --- CHANGELOG.md | 177 +++++++++++++++++ base/empty-like/README.md | 4 +- base/empty-like/benchmark/benchmark.js | 23 +++ .../benchmark/benchmark.size.bool.js | 95 +++++++++ base/empty-like/docs/types/index.d.ts | 33 +++- base/empty-like/docs/types/test.ts | 2 + base/empty-like/examples/index.js | 4 +- base/empty-like/test/test.js | 40 +++- base/empty/benchmark/benchmark.js | 18 ++ base/empty/benchmark/benchmark.size.bool.js | 93 +++++++++ base/empty/docs/types/index.d.ts | 26 ++- base/empty/docs/types/test.ts | 6 +- base/empty/test/test.js | 29 ++- base/zeros-like/README.md | 2 +- base/zeros-like/docs/types/index.d.ts | 4 +- base/zeros-like/examples/index.js | 2 +- base/zeros-like/test/test.js | 2 +- base/zeros/README.md | 6 +- base/zeros/docs/repl.txt | 2 +- base/zeros/docs/types/index.d.ts | 10 +- base/zeros/docs/types/test.ts | 4 +- base/zeros/examples/index.js | 2 +- base/zeros/lib/main.js | 2 +- base/zeros/test/test.js | 2 +- empty-like/README.md | 4 +- empty-like/benchmark/benchmark.js | 23 +++ empty-like/benchmark/benchmark.size.bool.js | 95 +++++++++ empty-like/docs/types/index.d.ts | 180 +++++++++++++++++- empty-like/docs/types/test.ts | 16 +- empty-like/examples/index.js | 4 +- empty-like/test/test.js | 40 +++- empty/benchmark/benchmark.js | 20 ++ empty/benchmark/benchmark.size.bool.js | 98 ++++++++++ empty/docs/types/index.d.ts | 82 +++++++- empty/docs/types/test.ts | 2 +- empty/test/test.js | 39 +++- zeros-like/README.md | 4 +- zeros-like/docs/types/index.d.ts | 95 ++++++++- zeros-like/docs/types/test.ts | 10 +- zeros-like/examples/index.js | 2 +- zeros-like/test/test.js | 2 +- zeros/README.md | 4 +- zeros/docs/repl.txt | 3 +- zeros/docs/types/index.d.ts | 58 +++++- zeros/docs/types/test.ts | 2 +- zeros/examples/index.js | 2 +- zeros/test/test.js | 2 +- 47 files changed, 1309 insertions(+), 66 deletions(-) create mode 100644 base/empty-like/benchmark/benchmark.size.bool.js create mode 100644 base/empty/benchmark/benchmark.size.bool.js create mode 100644 empty-like/benchmark/benchmark.size.bool.js create mode 100644 empty/benchmark/benchmark.size.bool.js diff --git a/CHANGELOG.md b/CHANGELOG.md index a0aeb223..f2169ed7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -165,6 +165,50 @@ +
+ +#### [@stdlib/ndarray/base/empty](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/empty) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + + +
+ +#### [@stdlib/ndarray/base/empty-like](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/empty-like) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + +
#### [@stdlib/ndarray/base/nullary](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/nullary) @@ -229,6 +273,50 @@ +
+ +#### [@stdlib/ndarray/base/zeros](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/zeros) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + + +
+ +#### [@stdlib/ndarray/base/zeros-like](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/zeros-like) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + +
#### [@stdlib/ndarray/ctor](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor) @@ -296,6 +384,50 @@ +
+ +#### [@stdlib/ndarray/empty](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/empty) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + + +
+ +#### [@stdlib/ndarray/empty-like](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/empty-like) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + +
#### [@stdlib/ndarray/from-scalar](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/from-scalar) @@ -471,6 +603,50 @@ +
+ +#### [@stdlib/ndarray/zeros](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/zeros) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + + +
+ +#### [@stdlib/ndarray/zeros-like](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/zeros-like) + +
+ +
+ +##### Features + +- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) + +
+ + + +
+ +
+ + +
@@ -528,6 +704,7 @@ A total of 3 people contributed to this release. Thank you to the following cont
+- [`71cf5a0`](https://github.com/stdlib-js/stdlib/commit/71cf5a05a13d12aed627d332147642adc4694ab9) - **feat:** add boolean dtype support to `ndarray/empty*` and `ndarray/base/empty*` packages [(#2588)](https://github.com/stdlib-js/stdlib/pull/2588) _(by Jaysukh Makvana, Athan Reines)_ - [`f766a56`](https://github.com/stdlib-js/stdlib/commit/f766a563e112098dc229991c0eedb5f5b7417811) - **feat:** add boolean dtype support to `ndarray/from-scalar` [(#2589)](https://github.com/stdlib-js/stdlib/pull/2589) _(by Jaysukh Makvana, Athan Reines)_ - [`a360f04`](https://github.com/stdlib-js/stdlib/commit/a360f048dde8429a3ffcc60d36abe9ad33038c73) - **feat:** add boolean dtype support to `ndarray/base/unary` [(#2587)](https://github.com/stdlib-js/stdlib/pull/2587) _(by Jaysukh Makvana)_ - [`19d4a8d`](https://github.com/stdlib-js/stdlib/commit/19d4a8da27facd0cc72b6162dc7e6b0d66d7a63c) - **feat:** add boolean dtype support to `ndarray/base/nullary` [(#2586)](https://github.com/stdlib-js/stdlib/pull/2586) _(by Jaysukh Makvana)_ diff --git a/base/empty-like/README.md b/base/empty-like/README.md index 6856fcb1..9dd83e20 100644 --- a/base/empty-like/README.md +++ b/base/empty-like/README.md @@ -85,7 +85,7 @@ var sh = y.shape; ```javascript var dtypes = require( '@stdlib/ndarray/dtypes' ); -var zeros = require( '@stdlib/ndarray/base/zeros' ); +var empty = require( '@stdlib/ndarray/base/empty' ); var emptyLike = require( '@stdlib/ndarray/base/empty-like' ); // Get a list of data types: @@ -96,7 +96,7 @@ var x; var y; var i; for ( i = 0; i < dt.length; i++ ) { - x = zeros( dt[ i ], [ 2, 2 ], 'row-major' ); + x = empty( dt[ i ], [ 2, 2 ], 'row-major' ); y = emptyLike( x ); console.log( y.data ); } diff --git a/base/empty-like/benchmark/benchmark.js b/base/empty-like/benchmark/benchmark.js index c7bb54e1..bd4f821c 100644 --- a/base/empty-like/benchmark/benchmark.js +++ b/base/empty-like/benchmark/benchmark.js @@ -23,6 +23,7 @@ var bench = require( '@stdlib/bench' ); var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); var zeros = require( './../../../base/zeros' ); +var empty = require( './../../../base/empty' ); var pkg = require( './../package.json' ).name; var emptyLike = require( './../lib' ); @@ -271,6 +272,28 @@ bench( pkg+'::base:dtype=uint8c', function benchmark( b ) { b.end(); }); +bench( pkg+'::base:dtype=bool', function benchmark( b ) { + var x; + var y; + var i; + + x = empty( 'bool', [ 0 ], 'row-major' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + y = emptyLike( x ); + if ( y.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isndarrayLike( y ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + bench( pkg+'::base:dtype=generic', function benchmark( b ) { var x; var y; diff --git a/base/empty-like/benchmark/benchmark.size.bool.js b/base/empty-like/benchmark/benchmark.size.bool.js new file mode 100644 index 00000000..b7e11bba --- /dev/null +++ b/base/empty-like/benchmark/benchmark.size.bool.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var empty = require( './../../../base/empty' ); +var pkg = require( './../package.json' ).name; +var emptyLike = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = empty( 'bool', [ len ], 'row-major' ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var arr; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+'::base:dtype=bool,size='+len, f ); + } +} + +main(); diff --git a/base/empty-like/docs/types/index.d.ts b/base/empty-like/docs/types/index.d.ts index 86c7a36f..deccc47c 100644 --- a/base/empty-like/docs/types/index.d.ts +++ b/base/empty-like/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType } from '@stdlib/types/ndarray'; +import { typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, boolndarray, complex128ndarray, complex64ndarray } from '@stdlib/types/ndarray'; /** * Creates an uninitialized array having the same shape and data type as a provided input ndarray. @@ -341,6 +341,35 @@ declare function emptyLike( x: uint8ndarray ): uint8ndarray; */ declare function emptyLike( x: uint8cndarray ): uint8cndarray; +/** +* Creates an uninitialized array having the same shape and data type as a provided input ndarray. +* +* @param x - input array +* @returns output array +* +* @example +* var empty = require( '@stdlib/ndarray/base/empty' ); +* +* var x = empty( 'bool', [ 2, 2 ], 'row-major' ); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'bool' +* +* var y = emptyLike( x ); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'bool' +*/ +declare function emptyLike( x: boolndarray ): boolndarray; + /** * Creates an uninitialized array having the same shape and data type as a provided input ndarray. * @@ -368,7 +397,7 @@ declare function emptyLike( x: uint8cndarray ): uint8cndarray; * dt = y.dtype; * // returns 'generic' */ -declare function emptyLike( x: ndarray ): typedndarray; +declare function emptyLike( x: typedndarray ): typedndarray; // EXPORTS // diff --git a/base/empty-like/docs/types/test.ts b/base/empty-like/docs/types/test.ts index a87a66f9..94f9e723 100644 --- a/base/empty-like/docs/types/test.ts +++ b/base/empty-like/docs/types/test.ts @@ -17,6 +17,7 @@ */ import zeros = require( './../../../../base/zeros' ); +import empty = require( './../../../../base/empty' ); import emptyLike = require( './index' ); @@ -38,6 +39,7 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'uint16', sh, ord ) ); // $ExpectType uint16ndarray emptyLike( zeros( 'uint8', sh, ord ) ); // $ExpectType uint8ndarray emptyLike( zeros( 'uint8c', sh, ord ) ); // $ExpectType uint8cndarray + emptyLike( empty( 'bool', sh, ord ) ); // $ExpectType boolndarray emptyLike( zeros( 'generic', sh, ord ) ); // $ExpectType typedndarray } diff --git a/base/empty-like/examples/index.js b/base/empty-like/examples/index.js index 969d4865..35d84048 100644 --- a/base/empty-like/examples/index.js +++ b/base/empty-like/examples/index.js @@ -19,7 +19,7 @@ 'use strict'; var dtypes = require( './../../../dtypes' ); -var zeros = require( './../../../base/zeros' ); +var empty = require( './../../../base/empty' ); var emptyLike = require( './../lib' ); // Get a list of data types: @@ -30,7 +30,7 @@ var x; var y; var i; for ( i = 0; i < dt.length; i++ ) { - x = zeros( dt[ i ], [ 2, 2 ], 'row-major' ); + x = empty( dt[ i ], [ 2, 2 ], 'row-major' ); y = emptyLike( x ); console.log( y.data ); } diff --git a/base/empty-like/test/test.js b/base/empty-like/test/test.js index 67ebcd65..5b043aa8 100644 --- a/base/empty-like/test/test.js +++ b/base/empty-like/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2023 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,6 +32,7 @@ var Uint8Array = require( '@stdlib/array/uint8' ); var Uint8ClampedArray = require( '@stdlib/array/uint8c' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); var Buffer = require( '@stdlib/buffer/ctor' ); var allocUnsafe = require( '@stdlib/buffer/alloc-unsafe' ); var instanceOf = require( '@stdlib/assert/instance-of' ); @@ -39,6 +40,7 @@ var base = require( './../../../base/ctor' ); var ndarray = require( './../../../ctor' ); var array = require( './../../../array' ); var zeros = require( './../../../base/zeros' ); +var empty = require( './../../../base/empty' ); var emptyLike = require( './../lib' ); @@ -518,6 +520,42 @@ tape( 'the function returns an uninitialized array (dtype=complex64, non-base)', t.end(); }); +tape( 'the function returns an uninitialized array (dtype=bool, base)', function test( t ) { + var arr; + var x; + + x = empty( 'bool', [ 2, 2 ], 'row-major' ); + arr = emptyLike( x ); + + t.strictEqual( instanceOf( arr, base ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'row-major', 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an uninitialized array (dtype=bool, non-base)', function test( t ) { + var arr; + var x; + + x = array( new BooleanArray( 4 ), { + 'shape': [ 2, 2 ], + 'dtype': 'bool', + 'order': 'column-major' + }); + arr = emptyLike( x ); + + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'column-major', 'returns expected value' ); + + t.end(); +}); + tape( 'the function returns an uninitialized array (dtype=generic, base)', function test( t ) { var expected; var arr; diff --git a/base/empty/benchmark/benchmark.js b/base/empty/benchmark/benchmark.js index 422fe27b..dab2732e 100644 --- a/base/empty/benchmark/benchmark.js +++ b/base/empty/benchmark/benchmark.js @@ -226,6 +226,24 @@ bench( pkg+':dtype=uint8c', function benchmark( b ) { b.end(); }); +bench( pkg+':dtype=bool', function benchmark( b ) { + var arr; + var i; + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = empty( 'bool', [ 0 ], 'row-major' ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + bench( pkg+':dtype=generic', function benchmark( b ) { var arr; var i; diff --git a/base/empty/benchmark/benchmark.size.bool.js b/base/empty/benchmark/benchmark.size.bool.js new file mode 100644 index 00000000..980695c6 --- /dev/null +++ b/base/empty/benchmark/benchmark.size.bool.js @@ -0,0 +1,93 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var pkg = require( './../package.json' ).name; +var empty = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var arr; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = empty( 'bool', [ len ], 'row-major' ); + if ( arr.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':dtype=bool,size='+len, f ); + } +} + +main(); diff --git a/base/empty/docs/types/index.d.ts b/base/empty/docs/types/index.d.ts index e54c503a..5a6b0f4a 100644 --- a/base/empty/docs/types/index.d.ts +++ b/base/empty/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType } from '@stdlib/types/ndarray'; +import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, boolndarray, complex128ndarray, complex64ndarray, genericndarray, DataType } from '@stdlib/types/ndarray'; /** * Creates an uninitialized array having a specified shape and data type. @@ -242,6 +242,26 @@ declare function empty( dtype: 'uint8', shape: Shape, order: Order ): uint8ndarr */ declare function empty( dtype: 'uint8c', shape: Shape, order: Order ): uint8cndarray; +/** +* Creates an uninitialized array having a specified shape and data type. +* +* @param dtype - underlying data type +* @param shape - array shape +* @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) +* @returns output array +* +* @example +* var arr = empty( 'bool', [ 2, 2 ], 'row-major' ); +* // returns +* +* var sh = arr.shape; +* // returns [ 2, 2 ] +* +* var dt = arr.dtype; +* // returns 'bool' +*/ +declare function empty( dtype: 'bool', shape: Shape, order: Order ): boolndarray; + /** * Creates a zero-filled array having a specified shape and data type. * @@ -260,7 +280,7 @@ declare function empty( dtype: 'uint8c', shape: Shape, order: Order ): uint8cnda * var dt = arr.dtype; * // returns 'generic' */ -declare function empty( dtype: 'generic', shape: Shape, order: Order ): typedndarray; +declare function empty( dtype: 'generic', shape: Shape, order: Order ): genericndarray; /** * Creates an uninitialized array having a specified shape and data type. @@ -280,7 +300,7 @@ declare function empty( dtype: 'generic', shape: Shape, order: Order ): typednda * var dt = arr.dtype; * // returns 'float32' */ -declare function empty( dtype: DataType, shape: Shape, order: Order ): typedndarray; +declare function empty( dtype: DataType, shape: Shape, order: Order ): typedndarray; // EXPORTS // diff --git a/base/empty/docs/types/test.ts b/base/empty/docs/types/test.ts index 5df0948d..85473a96 100644 --- a/base/empty/docs/types/test.ts +++ b/base/empty/docs/types/test.ts @@ -34,7 +34,8 @@ import empty = require( './index' ); empty( 'uint16', [ 2, 2 ], 'row-major' ); // $ExpectType uint16ndarray empty( 'uint8', [ 2, 2 ], 'row-major' ); // $ExpectType uint8ndarray empty( 'uint8c', [ 2, 2 ], 'row-major' ); // $ExpectType uint8cndarray - empty( 'generic', [ 2, 2 ], 'row-major' ); // $ExpectType typedndarray + empty( 'bool', [ 2, 2 ], 'row-major' ); // $ExpectType boolndarray + empty( 'generic', [ 2, 2 ], 'row-major' ); // $ExpectType genericndarray empty( 'float64', [ 2, 2 ], 'column-major' ); // $ExpectType float64ndarray empty( 'float32', [ 2, 2 ], 'column-major' ); // $ExpectType float32ndarray @@ -47,7 +48,8 @@ import empty = require( './index' ); empty( 'uint16', [ 2, 2 ], 'column-major' ); // $ExpectType uint16ndarray empty( 'uint8', [ 2, 2 ], 'column-major' ); // $ExpectType uint8ndarray empty( 'uint8c', [ 2, 2 ], 'column-major' ); // $ExpectType uint8cndarray - empty( 'generic', [ 2, 2 ], 'column-major' ); // $ExpectType typedndarray + empty( 'bool', [ 2, 2 ], 'column-major' ); // $ExpectType boolndarray + empty( 'generic', [ 2, 2 ], 'column-major' ); // $ExpectType genericndarray } // The compiler throws an error if the function is provided a first argument which is an unrecognized/unsupported data type... diff --git a/base/empty/test/test.js b/base/empty/test/test.js index 10bc97fc..829a5e0b 100644 --- a/base/empty/test/test.js +++ b/base/empty/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2023 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,6 +32,7 @@ var Uint8Array = require( '@stdlib/array/uint8' ); var Uint8ClampedArray = require( '@stdlib/array/uint8c' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); var Buffer = require( '@stdlib/buffer/ctor' ); var instanceOf = require( '@stdlib/assert/instance-of' ); var ndarray = require( './../../../base/ctor' ); @@ -393,6 +394,32 @@ tape( 'the function returns an uninitialized array (dtype=complex64, order=colum t.end(); }); +tape( 'the function returns an uninitialized array (dtype=bool, order=row-major)', function test( t ) { + var arr; + + arr = empty( 'bool', [ 2, 2 ], 'row-major' ); + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'row-major', 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an uninitialized array (dtype=bool, order=column-major)', function test( t ) { + var arr; + + arr = empty( 'bool', [ 2, 2 ], 'column-major' ); + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'column-major', 'returns expected value' ); + + t.end(); +}); + tape( 'the function returns a zero-filled array (dtype=generic, order=row-major)', function test( t ) { var expected; var arr; diff --git a/base/zeros-like/README.md b/base/zeros-like/README.md index d2758ca8..698012f2 100644 --- a/base/zeros-like/README.md +++ b/base/zeros-like/README.md @@ -87,7 +87,7 @@ var zeros = require( '@stdlib/ndarray/base/zeros' ); var zerosLike = require( '@stdlib/ndarray/base/zeros-like' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var x; diff --git a/base/zeros-like/docs/types/index.d.ts b/base/zeros-like/docs/types/index.d.ts index 6400f751..597f9d85 100644 --- a/base/zeros-like/docs/types/index.d.ts +++ b/base/zeros-like/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType } from '@stdlib/types/ndarray'; +import { typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, genericndarray, complex128ndarray, complex64ndarray } from '@stdlib/types/ndarray'; /** * Creates a zero-filled array having the same shape and data type as a provided input ndarray. @@ -368,7 +368,7 @@ declare function zerosLike( x: uint8cndarray ): uint8cndarray; * dt = y.dtype; * // returns 'generic' */ -declare function zerosLike( x: ndarray ): typedndarray; +declare function zerosLike( x: typedndarray | genericndarray ): typedndarray; // EXPORTS // diff --git a/base/zeros-like/examples/index.js b/base/zeros-like/examples/index.js index e81a8e18..e3429093 100644 --- a/base/zeros-like/examples/index.js +++ b/base/zeros-like/examples/index.js @@ -23,7 +23,7 @@ var zeros = require( './../../../base/zeros' ); var zerosLike = require( './../lib' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var x; diff --git a/base/zeros-like/test/test.js b/base/zeros-like/test/test.js index 7b8b89a0..f159916a 100644 --- a/base/zeros-like/test/test.js +++ b/base/zeros-like/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2022 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/base/zeros/README.md b/base/zeros/README.md index 0d56889b..4dceb3e3 100644 --- a/base/zeros/README.md +++ b/base/zeros/README.md @@ -42,7 +42,7 @@ var zeros = require( '@stdlib/ndarray/base/zeros' ); #### zeros( dtype, shape, order ) -Creates a zero-filled [ndarray][@stdlib/ndarray/base/ctor] having a specified shape and [data type][@stdlib/ndarray/dtypes]. +Creates a zero-filled [ndarray][@stdlib/ndarray/base/ctor] having a specified shape and numeric [data type][@stdlib/ndarray/dtypes]. ```javascript var arr = zeros( 'float64', [ 2, 2 ], 'row-major' ); @@ -57,7 +57,7 @@ var dt = arr.dtype; The function accepts the following arguments: -- **dtype**: underlying [data type][@stdlib/ndarray/dtypes]. +- **dtype**: underlying [data type][@stdlib/ndarray/dtypes]. Must be a numeric [data type][@stdlib/ndarray/dtypes] or "generic". - **shape**: array shape. - **order**: specifies whether an [ndarray][@stdlib/ndarray/base/ctor] is `'row-major'` (C-style) or `'column-major'` (Fortran-style). @@ -86,7 +86,7 @@ var dtypes = require( '@stdlib/ndarray/dtypes' ); var zeros = require( '@stdlib/ndarray/base/zeros' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var arr; diff --git a/base/zeros/docs/repl.txt b/base/zeros/docs/repl.txt index 76365752..86caf36b 100644 --- a/base/zeros/docs/repl.txt +++ b/base/zeros/docs/repl.txt @@ -5,7 +5,7 @@ Parameters ---------- dtype: string - Underlying data type. + Underlying data type. Must be a numeric data type or "generic". shape: ArrayLikeObject Array shape. diff --git a/base/zeros/docs/types/index.d.ts b/base/zeros/docs/types/index.d.ts index 99689518..0831527b 100644 --- a/base/zeros/docs/types/index.d.ts +++ b/base/zeros/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType } from '@stdlib/types/ndarray'; +import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, genericndarray, complex128ndarray, complex64ndarray, NumericAndGenericDataType } from '@stdlib/types/ndarray'; /** * Creates a zero-filled array having a specified shape and data type. @@ -260,7 +260,7 @@ declare function zeros( dtype: 'uint8c', shape: Shape, order: Order ): uint8cnda * var dt = arr.dtype; * // returns 'generic' */ -declare function zeros( dtype: 'generic', shape: Shape, order: Order ): typedndarray; +declare function zeros( dtype: 'generic', shape: Shape, order: Order ): genericndarray; /** * Creates a zero-filled array having a specified shape and data type. @@ -271,16 +271,16 @@ declare function zeros( dtype: 'generic', shape: Shape, order: Order ): typednda * @returns zero-filled array * * @example -* var arr = zeros( 'float32', [ 2, 2 ], 'row-major' ); +* var arr = zeros( 'float64', [ 2, 2 ], 'row-major' ); * // returns * * var sh = arr.shape; * // returns [ 2, 2 ] * * var dt = arr.dtype; -* // returns 'float32' +* // returns 'float64' */ -declare function zeros( dtype: DataType, shape: Shape, order: Order ): typedndarray; +declare function zeros( dtype: NumericAndGenericDataType, shape: Shape, order: Order ): typedndarray; // EXPORTS // diff --git a/base/zeros/docs/types/test.ts b/base/zeros/docs/types/test.ts index f2148581..704bc51a 100644 --- a/base/zeros/docs/types/test.ts +++ b/base/zeros/docs/types/test.ts @@ -34,7 +34,7 @@ import zeros = require( './index' ); zeros( 'uint16', [ 2, 2 ], 'row-major' ); // $ExpectType uint16ndarray zeros( 'uint8', [ 2, 2 ], 'row-major' ); // $ExpectType uint8ndarray zeros( 'uint8c', [ 2, 2 ], 'row-major' ); // $ExpectType uint8cndarray - zeros( 'generic', [ 2, 2 ], 'row-major' ); // $ExpectType typedndarray + zeros( 'generic', [ 2, 2 ], 'row-major' ); // $ExpectType genericndarray zeros( 'float64', [ 2, 2 ], 'column-major' ); // $ExpectType float64ndarray zeros( 'float32', [ 2, 2 ], 'column-major' ); // $ExpectType float32ndarray @@ -47,7 +47,7 @@ import zeros = require( './index' ); zeros( 'uint16', [ 2, 2 ], 'column-major' ); // $ExpectType uint16ndarray zeros( 'uint8', [ 2, 2 ], 'column-major' ); // $ExpectType uint8ndarray zeros( 'uint8c', [ 2, 2 ], 'column-major' ); // $ExpectType uint8cndarray - zeros( 'generic', [ 2, 2 ], 'column-major' ); // $ExpectType typedndarray + zeros( 'generic', [ 2, 2 ], 'column-major' ); // $ExpectType genericndarray } // The compiler throws an error if the function is provided a first argument which is an unrecognized/unsupported data type... diff --git a/base/zeros/examples/index.js b/base/zeros/examples/index.js index 107acb6e..60c0b6dd 100644 --- a/base/zeros/examples/index.js +++ b/base/zeros/examples/index.js @@ -22,7 +22,7 @@ var dtypes = require( './../../../dtypes' ); var zeros = require( './../lib' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var arr; diff --git a/base/zeros/lib/main.js b/base/zeros/lib/main.js index 996d83e2..0b2939a8 100644 --- a/base/zeros/lib/main.js +++ b/base/zeros/lib/main.js @@ -33,7 +33,7 @@ var numel = require( './../../../base/numel' ); /** * Creates a zero-filled ndarray having a specified shape and data type. * -* @param {string} dtype - data type +* @param {string} dtype - numeric data type * @param {NonNegativeIntegerArray} shape - array shape * @param {string} order - array order * @throws {TypeError} first argument must be a recognized data type diff --git a/base/zeros/test/test.js b/base/zeros/test/test.js index 8f862d2f..ad6f15df 100644 --- a/base/zeros/test/test.js +++ b/base/zeros/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2022 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/empty-like/README.md b/empty-like/README.md index 5feae901..deef81f2 100644 --- a/empty-like/README.md +++ b/empty-like/README.md @@ -118,7 +118,7 @@ dt = y.dtype; ```javascript var dtypes = require( '@stdlib/ndarray/dtypes' ); -var zeros = require( '@stdlib/ndarray/zeros' ); +var empty = require( '@stdlib/ndarray/empty' ); var emptyLike = require( '@stdlib/ndarray/empty-like' ); // Get a list of data types: @@ -129,7 +129,7 @@ var x; var y; var i; for ( i = 0; i < dt.length; i++ ) { - x = zeros( [ 2, 2 ], { + x = empty( [ 2, 2 ], { 'dtype': dt[ i ] }); y = emptyLike( x ); diff --git a/empty-like/benchmark/benchmark.js b/empty-like/benchmark/benchmark.js index 6cd87e18..68479437 100644 --- a/empty-like/benchmark/benchmark.js +++ b/empty-like/benchmark/benchmark.js @@ -23,6 +23,7 @@ var bench = require( '@stdlib/bench' ); var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); var zeros = require( './../../base/zeros' ); +var empty = require( './../../base/empty' ); var pkg = require( './../package.json' ).name; var emptyLike = require( './../lib' ); @@ -271,6 +272,28 @@ bench( pkg+':dtype=uint8c', function benchmark( b ) { b.end(); }); +bench( pkg+':dtype=bool', function benchmark( b ) { + var x; + var y; + var i; + + x = empty( 'bool', [ 0 ], 'row-major' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + y = emptyLike( x ); + if ( y.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isndarrayLike( y ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + bench( pkg+':dtype=generic', function benchmark( b ) { var x; var y; diff --git a/empty-like/benchmark/benchmark.size.bool.js b/empty-like/benchmark/benchmark.size.bool.js new file mode 100644 index 00000000..f17d336f --- /dev/null +++ b/empty-like/benchmark/benchmark.size.bool.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var empty = require( './../../base/empty' ); +var pkg = require( './../package.json' ).name; +var emptyLike = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = empty( 'bool', [ len ], 'row-major' ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var arr; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':dtype=bool,size='+len, f ); + } +} + +main(); diff --git a/empty-like/docs/types/index.d.ts b/empty-like/docs/types/index.d.ts index bb8dbd3a..ee9cb4a9 100644 --- a/empty-like/docs/types/index.d.ts +++ b/empty-like/docs/types/index.d.ts @@ -22,7 +22,7 @@ /// -import { Shape, Order, ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType, Mode } from '@stdlib/types/ndarray'; +import { Shape, Order, ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, boolndarray, genericndarray, complex128ndarray, complex64ndarray, DataType, Mode } from '@stdlib/types/ndarray'; /** * Interface describing function options. @@ -211,6 +211,34 @@ interface Uint8COptions extends Options { dtype: 'uint8c'; } +/** +* Interface describing function options. +*/ +interface BoolOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'bool'; +} + +/** +* Interface describing function options. +*/ +interface GenericOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'generic'; +} + /** * Interface describing function options. */ @@ -621,6 +649,78 @@ declare function emptyLike( x: uint8ndarray, options?: Options ): uint8ndarray; */ declare function emptyLike( x: uint8cndarray, options?: Options ): uint8cndarray; +/** +* Creates an uninitialized array having the same shape and data type as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns output array +* +* @example +* var empty = require( '@stdlib/ndarray/empty' ); +* +* var x = empty( [ 2, 2 ], { +* 'dtype': 'bool' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'bool' +* +* var y = emptyLike( x ); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'bool' +*/ +declare function emptyLike( x: boolndarray, options?: Options ): boolndarray; + +/** +* Creates an uninitialized array having the same shape and data type as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns output array +* +* @example +* var empty = require( '@stdlib/ndarray/empty' ); +* +* var x = empty( [ 2, 2 ], { +* 'dtype': 'generic' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'generic' +* +* var y = emptyLike( x ); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'generic' +*/ +declare function emptyLike( x: genericndarray, options?: Options ): genericndarray; + /** * Creates an uninitialized double-precision floating-point array having the same shape as a provided input ndarray. * @@ -1050,6 +1150,84 @@ declare function emptyLike( x: ndarray, options: Uint8Options ): uint8ndarray; */ declare function emptyLike( x: ndarray, options: Uint8COptions ): uint8cndarray; +/** +* Creates an uninitialized boolean array having the same shape as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.dtype - output array data type +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns output array +* +* @example +* var zeros = require( '@stdlib/ndarray/zeros' ); +* +* var x = zeros( [ 2, 2 ], { +* 'dtype': 'float64' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'float64' +* +* var y = emptyLike( x, { +* 'dtype': 'bool' +* }); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'bool' +*/ +declare function emptyLike( x: ndarray, options: BoolOptions ): boolndarray; + +/** +* Creates an uninitialized generic array having the same shape as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.dtype - output array data type +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns output array +* +* @example +* var zeros = require( '@stdlib/ndarray/zeros' ); +* +* var x = zeros( [ 2, 2 ], { +* 'dtype': 'float64' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'float64' +* +* var y = emptyLike( x, { +* 'dtype': 'generic' +* }); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'generic' +*/ +declare function emptyLike( x: ndarray, options: GenericOptions ): genericndarray; + /** * Creates an uninitialized array having the same shape and data type as a provided input ndarray. * diff --git a/empty-like/docs/types/test.ts b/empty-like/docs/types/test.ts index 55a9df39..f35e8089 100644 --- a/empty-like/docs/types/test.ts +++ b/empty-like/docs/types/test.ts @@ -17,6 +17,7 @@ */ import zeros = require( './../../../base/zeros' ); +import empty = require( './../../../base/empty' ); import emptyLike = require( './index' ); @@ -38,7 +39,8 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'uint16', sh, ord ) ); // $ExpectType uint16ndarray emptyLike( zeros( 'uint8', sh, ord ) ); // $ExpectType uint8ndarray emptyLike( zeros( 'uint8c', sh, ord ) ); // $ExpectType uint8cndarray - emptyLike( zeros( 'generic', sh, ord ) ); // $ExpectType typedndarray + emptyLike( empty( 'bool', sh, ord ) ); // $ExpectType boolndarray + emptyLike( zeros( 'generic', sh, ord ) ); // $ExpectType genericndarray emptyLike( zeros( 'float64', sh, ord ), {} ); // $ExpectType float64ndarray @@ -52,7 +54,8 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'uint16', sh, ord ), {} ); // $ExpectType uint16ndarray emptyLike( zeros( 'uint8', sh, ord ), {} ); // $ExpectType uint8ndarray emptyLike( zeros( 'uint8c', sh, ord ), {} ); // $ExpectType uint8cndarray - emptyLike( zeros( 'generic', sh, ord ), {} ); // $ExpectType typedndarray + emptyLike( empty( 'bool', sh, ord ), {} ); // $ExpectType boolndarray + emptyLike( zeros( 'generic', sh, ord ), {} ); // $ExpectType genericndarray emptyLike( zeros( 'float64', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType float64ndarray @@ -66,7 +69,8 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'uint16', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint16ndarray emptyLike( zeros( 'uint8', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint8ndarray emptyLike( zeros( 'uint8c', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint8cndarray - emptyLike( zeros( 'generic', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType typedndarray + emptyLike( empty( 'bool', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType boolndarray + emptyLike( zeros( 'generic', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType genericndarray emptyLike( zeros( 'float64', sh, ord ), { 'order': 'column-major' } ); // $ExpectType float64ndarray @@ -80,7 +84,8 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'uint16', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint16ndarray emptyLike( zeros( 'uint8', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint8ndarray emptyLike( zeros( 'uint8c', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint8cndarray - emptyLike( zeros( 'generic', sh, ord ), { 'order': 'column-major' } ); // $ExpectType typedndarray + emptyLike( empty( 'bool', sh, ord ), { 'order': 'column-major' } ); // $ExpectType boolndarray + emptyLike( zeros( 'generic', sh, ord ), { 'order': 'column-major' } ); // $ExpectType genericndarray emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'float64' } ); // $ExpectType float64ndarray @@ -94,7 +99,8 @@ import emptyLike = require( './index' ); emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint16' } ); // $ExpectType uint16ndarray emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint8' } ); // $ExpectType uint8ndarray emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint8c' } ); // $ExpectType uint8cndarray - emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'generic' } ); // $ExpectType typedndarray + emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'bool' } ); // $ExpectType boolndarray + emptyLike( zeros( 'generic', sh, ord ), { 'dtype': 'generic' } ); // $ExpectType genericndarray } // The compiler throws an error if the function is provided a first argument is not an ndarray which has a recognized/supported data type... diff --git a/empty-like/examples/index.js b/empty-like/examples/index.js index d7d5e069..679b7b4a 100644 --- a/empty-like/examples/index.js +++ b/empty-like/examples/index.js @@ -19,7 +19,7 @@ 'use strict'; var dtypes = require( './../../dtypes' ); -var zeros = require( './../../zeros' ); +var empty = require( './../../empty' ); var emptyLike = require( './../lib' ); // Get a list of data types: @@ -30,7 +30,7 @@ var x; var y; var i; for ( i = 0; i < dt.length; i++ ) { - x = zeros( [ 2, 2 ], { + x = empty( [ 2, 2 ], { 'dtype': dt[ i ] }); y = emptyLike( x ); diff --git a/empty-like/test/test.js b/empty-like/test/test.js index 12ebfbf0..5f2b4f53 100644 --- a/empty-like/test/test.js +++ b/empty-like/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2023 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,10 +32,12 @@ var Uint8Array = require( '@stdlib/array/uint8' ); var Uint8ClampedArray = require( '@stdlib/array/uint8c' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); var Buffer = require( '@stdlib/buffer/ctor' ); var instanceOf = require( '@stdlib/assert/instance-of' ); var ndarray = require( './../../ctor' ); var zeros = require( './../../base/zeros' ); +var empty = require( './../../base/empty' ); var emptyLike = require( './../lib' ); @@ -739,6 +741,42 @@ tape( 'the function returns an uninitialized array (dtype=complex64, options)', t.end(); }); +tape( 'the function returns an uninitialized array (dtype=bool, inferred)', function test( t ) { + var arr; + var x; + + x = empty( 'bool', [ 2, 2 ], 'row-major' ); + arr = emptyLike( x ); + + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'row-major', 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an uninitialized array (dtype=bool, options)', function test( t ) { + var arr; + var x; + + x = empty( 'generic', [ 4 ], 'row-major' ); + arr = emptyLike( x, { + 'shape': [ 2, 2 ], + 'dtype': 'bool', + 'order': 'column-major' + }); + + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, 'bool', 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, 'column-major', 'returns expected value' ); + + t.end(); +}); + tape( 'the function returns a zero-filled array (dtype=generic, inferred)', function test( t ) { var expected; var arr; diff --git a/empty/benchmark/benchmark.js b/empty/benchmark/benchmark.js index 6b985c3b..9fef205c 100644 --- a/empty/benchmark/benchmark.js +++ b/empty/benchmark/benchmark.js @@ -266,6 +266,26 @@ bench( pkg+':dtype=uint8c', function benchmark( b ) { b.end(); }); +bench( pkg+':dtype=bool', function benchmark( b ) { + var arr; + var i; + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = empty( [ 0 ], { + 'dtype': 'bool' + }); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + bench( pkg+':dtype=generic', function benchmark( b ) { var arr; var i; diff --git a/empty/benchmark/benchmark.size.bool.js b/empty/benchmark/benchmark.size.bool.js new file mode 100644 index 00000000..34770365 --- /dev/null +++ b/empty/benchmark/benchmark.size.bool.js @@ -0,0 +1,98 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var pkg = require( './../package.json' ).name; +var empty = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var opts; + var arr; + var i; + + opts = { + 'dtype': 'bool' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = empty( [ len ], opts ); + if ( arr.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isndarrayLike( arr ) ) { + b.fail( 'should return an ndarray' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':dtype=bool,size='+len, f ); + } +} + +main(); diff --git a/empty/docs/types/index.d.ts b/empty/docs/types/index.d.ts index 5709f4ab..7371145e 100644 --- a/empty/docs/types/index.d.ts +++ b/empty/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType, Mode } from '@stdlib/types/ndarray'; +import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, boolndarray, complex128ndarray, complex64ndarray, genericndarray, DataType, Mode } from '@stdlib/types/ndarray'; /** * Interface describing function options. @@ -200,6 +200,34 @@ interface Uint8COptions extends Options { dtype: 'uint8c'; } +/** +* Interface describing function options. +*/ +interface BoolOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'bool'; +} + +/** +* Interface describing function options. +*/ +interface GenericOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'generic'; +} + /** * Interface describing function options. */ @@ -489,6 +517,56 @@ declare function empty( shape: Shape | number, options: Uint8Options ): uint8nda */ declare function empty( shape: Shape | number, options: Uint8COptions ): uint8cndarray; +/** +* Creates an uninitialized array having a specified shape and data type. +* +* @param shape - array shape +* @param options - options +* @param options.dtype - underlying data type +* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major') +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns zero-filled array +* +* @example +* var arr = empty( [ 2, 2 ], { +* 'dtype': bool' +* }); +* // returns +* +* var sh = arr.shape; +* // returns [ 2, 2 ] +* +* var dt = arr.dtype; +* // returns 'bool' +*/ +declare function empty( shape: Shape | number, options: BoolOptions ): boolndarray; + +/** +* Creates an uninitialized array having a specified shape and data type. +* +* @param shape - array shape +* @param options - options +* @param options.dtype - underlying data type +* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major') +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @returns zero-filled array +* +* @example +* var arr = empty( [ 2, 2 ], { +* 'dtype': generic' +* }); +* // returns +* +* var sh = arr.shape; +* // returns [ 2, 2 ] +* +* var dt = arr.dtype; +* // returns 'generic' +*/ +declare function empty( shape: Shape | number, options: GenericOptions ): genericndarray; + /** * Creates an uninitialized array having a specified shape and data type. * @@ -533,7 +611,7 @@ declare function empty( shape: Shape | number, options?: Options ): float64ndarr * var dt = arr.dtype; * // returns 'float64' */ -declare function empty( shape: Shape | number, options?: OptionsWithDType ): typedndarray; +declare function empty( shape: Shape | number, options?: OptionsWithDType ): typedndarray; // EXPORTS // diff --git a/empty/docs/types/test.ts b/empty/docs/types/test.ts index 9c722a2b..9f4cb371 100644 --- a/empty/docs/types/test.ts +++ b/empty/docs/types/test.ts @@ -36,7 +36,7 @@ import empty = require( './index' ); empty( [ 2, 2 ], { 'dtype': 'uint16' } ); // $ExpectType uint16ndarray empty( [ 2, 2 ], { 'dtype': 'uint8' } ); // $ExpectType uint8ndarray empty( [ 2, 2 ], { 'dtype': 'uint8c' } ); // $ExpectType uint8cndarray - empty( [ 2, 2 ], { 'dtype': 'generic' } ); // $ExpectType typedndarray + empty( [ 2, 2 ], { 'dtype': 'generic' } ); // $ExpectType genericndarray } // The compiler throws an error if the function is not provided a valid shape for the first argument... diff --git a/empty/test/test.js b/empty/test/test.js index e144288c..b303a825 100644 --- a/empty/test/test.js +++ b/empty/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2023 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -32,6 +32,7 @@ var Uint8Array = require( '@stdlib/array/uint8' ); var Uint8ClampedArray = require( '@stdlib/array/uint8c' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); var Buffer = require( '@stdlib/buffer/ctor' ); var instanceOf = require( '@stdlib/assert/instance-of' ); var ndarray = require( './../../ctor' ); @@ -730,6 +731,42 @@ tape( 'the function returns an uninitialized array (dtype=complex64, order=colum t.end(); }); +tape( 'the function returns an uninitialized array (dtype=bool, order=row-major)', function test( t ) { + var opts; + var arr; + + opts = { + 'dtype': 'bool', + 'order': 'row-major' + }; + arr = empty( [ 2, 2 ], opts ); + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, opts.dtype, 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, opts.order, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an uninitialized array (dtype=bool, order=column-major)', function test( t ) { + var opts; + var arr; + + opts = { + 'dtype': 'bool', + 'order': 'column-major' + }; + arr = empty( [ 2, 2 ], opts ); + t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' ); + t.strictEqual( arr.dtype, opts.dtype, 'returns expected value' ); + t.deepEqual( arr.shape, [ 2, 2 ], 'returns expected value' ); + t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' ); + t.strictEqual( arr.order, opts.order, 'returns expected value' ); + + t.end(); +}); + tape( 'the function returns an uninitialized array (dtype=binary, order=row-major)', function test( t ) { var opts; var arr; diff --git a/zeros-like/README.md b/zeros-like/README.md index 763e271c..c221298a 100644 --- a/zeros-like/README.md +++ b/zeros-like/README.md @@ -62,7 +62,7 @@ var dt = y.dtype; The function supports the following `options`: -- **dtype**: output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes]. Overrides the input ndarray's inferred [data type][@stdlib/ndarray/dtypes]. +- **dtype**: output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes]. Must be a numeric [data type][@stdlib/ndarray/dtypes] or "generic". Overrides the input ndarray's inferred [data type][@stdlib/ndarray/dtypes]. - **shape**: output [ndarray][@stdlib/ndarray/ctor] shape. Overrides the input ndarray's inferred shape. - **order**: specifies whether the output [ndarray][@stdlib/ndarray/ctor] should be `'row-major'` (C-style) or `'column-major'` (Fortran-style). Overrides the input ndarray's inferred order. - **mode**: specifies how to handle indices which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). Default: `'throw'`. @@ -118,7 +118,7 @@ var zeros = require( '@stdlib/ndarray/zeros' ); var zerosLike = require( '@stdlib/ndarray/zeros-like' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var x; diff --git a/zeros-like/docs/types/index.d.ts b/zeros-like/docs/types/index.d.ts index e3bc0053..1b85c720 100644 --- a/zeros-like/docs/types/index.d.ts +++ b/zeros-like/docs/types/index.d.ts @@ -22,7 +22,7 @@ /// -import { Shape, Order, ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType, Mode } from '@stdlib/types/ndarray'; +import { Shape, Order, ndarray, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, genericndarray, complex128ndarray, complex64ndarray, NumericAndGenericDataType, Mode } from '@stdlib/types/ndarray'; /** * Interface describing function options. @@ -216,6 +216,20 @@ interface Uint8COptions extends Options { dtype: 'uint8c'; } +/** +* Interface describing function options. +*/ +interface GenericOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'generic'; +} + /** * Interface describing function options. */ @@ -227,7 +241,7 @@ interface OptionsWithDType extends Options { * * - This option overrides the input array's inferred data type. */ - dtype: DataType; + dtype: NumericAndGenericDataType; } /** @@ -637,6 +651,43 @@ declare function zerosLike( x: uint8ndarray, options?: Options ): uint8ndarray; */ declare function zerosLike( x: uint8cndarray, options?: Options ): uint8cndarray; +/** +* Creates a zero-filled array having the same shape and data type as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @param options.readonly - boolean indicating whether an array should be read-only +* @returns zero-filled array +* +* @example +* var zeros = require( '@stdlib/ndarray/zeros' ); +* +* var x = zeros( [ 2, 2 ], { +* 'dtype': 'generic' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'generic' +* +* var y = zerosLike( x ); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'generic' +*/ +declare function zerosLike( x: genericndarray, options?: Options ): genericndarray; + /** * Creates a zero-filled double-precision floating-point array having the same shape as a provided input ndarray. * @@ -1077,6 +1128,46 @@ declare function zerosLike( x: ndarray, options: Uint8Options ): uint8ndarray; */ declare function zerosLike( x: ndarray, options: Uint8COptions ): uint8cndarray; +/** +* Creates a zero-filled generic array having the same shape as a provided input ndarray. +* +* @param x - input array +* @param options - options +* @param options.dtype - output array data type +* @param options.order - specifies whether the output array is 'row-major' (C-style) or 'column-major' (Fortran-style) +* @param options.shape - output array shape +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @param options.readonly - boolean indicating whether an array should be read-only +* @returns zero-filled array +* +* @example +* var zeros = require( '@stdlib/ndarray/zeros' ); +* +* var x = zeros( [ 2, 2 ], { +* 'dtype': 'float64' +* }); +* // returns +* +* var sh = x.shape; +* // returns [ 2, 2 ] +* +* var dt = x.dtype; +* // returns 'float64' +* +* var y = zerosLike( x, { +* 'dtype': 'generic' +* }); +* // returns +* +* sh = y.shape; +* // returns [ 2, 2 ] +* +* dt = y.dtype; +* // returns 'generic' +*/ +declare function zerosLike( x: ndarray, options: GenericOptions ): genericndarray; + /** * Creates a zero-filled array having the same shape and data type as a provided input ndarray. * diff --git a/zeros-like/docs/types/test.ts b/zeros-like/docs/types/test.ts index b1bfb160..28ab7023 100644 --- a/zeros-like/docs/types/test.ts +++ b/zeros-like/docs/types/test.ts @@ -38,7 +38,7 @@ import zerosLike = require( './index' ); zerosLike( zeros( 'uint16', sh, ord ) ); // $ExpectType uint16ndarray zerosLike( zeros( 'uint8', sh, ord ) ); // $ExpectType uint8ndarray zerosLike( zeros( 'uint8c', sh, ord ) ); // $ExpectType uint8cndarray - zerosLike( zeros( 'generic', sh, ord ) ); // $ExpectType typedndarray + zerosLike( zeros( 'generic', sh, ord ) ); // $ExpectType genericndarray zerosLike( zeros( 'float64', sh, ord ), {} ); // $ExpectType float64ndarray @@ -52,7 +52,7 @@ import zerosLike = require( './index' ); zerosLike( zeros( 'uint16', sh, ord ), {} ); // $ExpectType uint16ndarray zerosLike( zeros( 'uint8', sh, ord ), {} ); // $ExpectType uint8ndarray zerosLike( zeros( 'uint8c', sh, ord ), {} ); // $ExpectType uint8cndarray - zerosLike( zeros( 'generic', sh, ord ), {} ); // $ExpectType typedndarray + zerosLike( zeros( 'generic', sh, ord ), {} ); // $ExpectType genericndarray zerosLike( zeros( 'float64', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType float64ndarray @@ -66,7 +66,7 @@ import zerosLike = require( './index' ); zerosLike( zeros( 'uint16', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint16ndarray zerosLike( zeros( 'uint8', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint8ndarray zerosLike( zeros( 'uint8c', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType uint8cndarray - zerosLike( zeros( 'generic', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType typedndarray + zerosLike( zeros( 'generic', sh, ord ), { 'shape': [ 2, 2, 2 ] } ); // $ExpectType genericndarray zerosLike( zeros( 'float64', sh, ord ), { 'order': 'column-major' } ); // $ExpectType float64ndarray @@ -80,7 +80,7 @@ import zerosLike = require( './index' ); zerosLike( zeros( 'uint16', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint16ndarray zerosLike( zeros( 'uint8', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint8ndarray zerosLike( zeros( 'uint8c', sh, ord ), { 'order': 'column-major' } ); // $ExpectType uint8cndarray - zerosLike( zeros( 'generic', sh, ord ), { 'order': 'column-major' } ); // $ExpectType typedndarray + zerosLike( zeros( 'generic', sh, ord ), { 'order': 'column-major' } ); // $ExpectType genericndarray zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'float64' } ); // $ExpectType float64ndarray @@ -94,7 +94,7 @@ import zerosLike = require( './index' ); zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint16' } ); // $ExpectType uint16ndarray zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint8' } ); // $ExpectType uint8ndarray zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'uint8c' } ); // $ExpectType uint8cndarray - zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'generic' } ); // $ExpectType typedndarray + zerosLike( zeros( 'generic', sh, ord ), { 'dtype': 'generic' } ); // $ExpectType genericndarray } // The compiler throws an error if the function is provided a first argument is not an ndarray which has a recognized/supported data type... diff --git a/zeros-like/examples/index.js b/zeros-like/examples/index.js index 42170561..5150fe69 100644 --- a/zeros-like/examples/index.js +++ b/zeros-like/examples/index.js @@ -23,7 +23,7 @@ var zeros = require( './../../zeros' ); var zerosLike = require( './../lib' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var x; diff --git a/zeros-like/test/test.js b/zeros-like/test/test.js index 7309116c..1d4f0dd2 100644 --- a/zeros-like/test/test.js +++ b/zeros-like/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2022 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/zeros/README.md b/zeros/README.md index 906c373f..380cf360 100644 --- a/zeros/README.md +++ b/zeros/README.md @@ -70,7 +70,7 @@ var dt = arr.dtype; The function accepts the following `options`: -- **dtype**: underlying [data type][@stdlib/ndarray/dtypes]. Default: `'float64'`. +- **dtype**: underlying [data type][@stdlib/ndarray/dtypes]. Must be a numeric [data type][@stdlib/ndarray/dtypes] or "generic". Default: `'float64'`. - **order**: specifies whether an [ndarray][@stdlib/ndarray/ctor] is `'row-major'` (C-style) or `'column-major'` (Fortran-style). Default: `'row-major'`. - **mode**: specifies how to handle indices which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). Default: `'throw'`. - **submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). If provided fewer modes than dimensions, the constructor recycles modes using modulo arithmetic. Default: `[ options.mode ]`. @@ -116,7 +116,7 @@ var dtypes = require( '@stdlib/ndarray/dtypes' ); var zeros = require( '@stdlib/ndarray/zeros' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var arr; diff --git a/zeros/docs/repl.txt b/zeros/docs/repl.txt index 99ed33da..4f367c86 100644 --- a/zeros/docs/repl.txt +++ b/zeros/docs/repl.txt @@ -11,7 +11,8 @@ Options. options.dtype: string (optional) - Underlying data type. Default: 'float64'. + Underlying data type. Must be a numeric data type or "generic". Default: + 'float64'. options.order: string (optional) Specifies whether an array is row-major (C-style) or column-major diff --git a/zeros/docs/types/index.d.ts b/zeros/docs/types/index.d.ts index 38e22619..b356f1ac 100644 --- a/zeros/docs/types/index.d.ts +++ b/zeros/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType, Mode } from '@stdlib/types/ndarray'; +import { Shape, Order, typedndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, genericndarray, complex128ndarray, complex64ndarray, NumericAndGenericDataType, Mode } from '@stdlib/types/ndarray'; /** * Interface describing function options. @@ -205,6 +205,34 @@ interface Uint8COptions extends Options { dtype: 'uint8c'; } +/** +* Interface describing function options. +*/ +interface Uint8COptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'uint8c'; +} + +/** +* Interface describing function options. +*/ +interface GenericOptions extends Options { + /** + * Underlying data type. + * + * ## Notes + * + * - This option overrides the input array's inferred data type. + */ + dtype: 'generic'; +} + /** * Interface describing function options. */ @@ -216,7 +244,7 @@ interface OptionsWithDType extends Options { * * - This option overrides the input array's inferred data type. */ - dtype: DataType; + dtype: NumericAndGenericDataType; } /** @@ -505,6 +533,32 @@ declare function zeros( shape: Shape | number, options: Uint8Options ): uint8nda */ declare function zeros( shape: Shape | number, options: Uint8COptions ): uint8cndarray; +/** +* Creates a zero-filled array having a specified shape and data type. +* +* @param shape - array shape +* @param options - options +* @param options.dtype - underlying data type +* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major') +* @param options.mode - specifies how to handle a linear index which exceeds array dimensions +* @param options.submode - specifies how to handle subscripts which exceed array dimensions on a per dimension basis +* @param options.readonly - boolean indicating whether an array should be read-only +* @returns zero-filled array +* +* @example +* var arr = zeros( [ 2, 2 ], { +* 'dtype': generic' +* }); +* // returns +* +* var sh = arr.shape; +* // returns [ 2, 2 ] +* +* var dt = arr.dtype; +* // returns 'generic' +*/ +declare function zeros( shape: Shape | number, options: GenericOptions ): genericndarray; + /** * Creates a zero-filled array having a specified shape and data type. * diff --git a/zeros/docs/types/test.ts b/zeros/docs/types/test.ts index 7123d6e8..de749bf7 100644 --- a/zeros/docs/types/test.ts +++ b/zeros/docs/types/test.ts @@ -36,7 +36,7 @@ import zeros = require( './index' ); zeros( [ 2, 2 ], { 'dtype': 'uint16' } ); // $ExpectType uint16ndarray zeros( [ 2, 2 ], { 'dtype': 'uint8' } ); // $ExpectType uint8ndarray zeros( [ 2, 2 ], { 'dtype': 'uint8c' } ); // $ExpectType uint8cndarray - zeros( [ 2, 2 ], { 'dtype': 'generic' } ); // $ExpectType typedndarray + zeros( [ 2, 2 ], { 'dtype': 'generic' } ); // $ExpectType genericndarray } // The compiler throws an error if the function is not provided a valid shape for the first argument... diff --git a/zeros/examples/index.js b/zeros/examples/index.js index a99e113b..f354b998 100644 --- a/zeros/examples/index.js +++ b/zeros/examples/index.js @@ -22,7 +22,7 @@ var dtypes = require( './../../dtypes' ); var zeros = require( './../lib' ); // Get a list of data types: -var dt = dtypes(); +var dt = dtypes( 'numeric' ); // Generate zero-filled arrays... var arr; diff --git a/zeros/test/test.js b/zeros/test/test.js index 196d7775..45058155 100644 --- a/zeros/test/test.js +++ b/zeros/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2022 The Stdlib Authors. +* Copyright (c) 2024 The Stdlib Authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License.