From 7cbf63260f74123b8cf06609235bfa548202259c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 7 Jul 2023 07:05:05 +0000 Subject: [PATCH] Auto-generated commit --- empty-like/README.md | 150 ++++ empty-like/benchmark/benchmark.js | 317 +++++++ .../benchmark/benchmark.length.complex128.js | 95 +++ .../benchmark/benchmark.length.complex64.js | 95 +++ .../benchmark/benchmark.length.float32.js | 95 +++ .../benchmark/benchmark.length.float64.js | 95 +++ .../benchmark/benchmark.length.generic.js | 95 +++ .../benchmark/benchmark.length.int16.js | 95 +++ .../benchmark/benchmark.length.int32.js | 95 +++ empty-like/benchmark/benchmark.length.int8.js | 95 +++ .../benchmark/benchmark.length.uint16.js | 95 +++ .../benchmark/benchmark.length.uint32.js | 95 +++ .../benchmark/benchmark.length.uint8.js | 95 +++ .../benchmark/benchmark.length.uint8c.js | 95 +++ empty-like/docs/repl.txt | 53 ++ empty-like/docs/types/index.d.ts | 798 ++++++++++++++++++ empty-like/docs/types/test.ts | 93 ++ empty-like/examples/index.js | 37 + empty-like/lib/index.js | 46 + empty-like/lib/main.js | 61 ++ empty-like/package.json | 105 +++ empty-like/test/test.js | 450 ++++++++++ 22 files changed, 3250 insertions(+) create mode 100644 empty-like/README.md create mode 100644 empty-like/benchmark/benchmark.js create mode 100644 empty-like/benchmark/benchmark.length.complex128.js create mode 100644 empty-like/benchmark/benchmark.length.complex64.js create mode 100644 empty-like/benchmark/benchmark.length.float32.js create mode 100644 empty-like/benchmark/benchmark.length.float64.js create mode 100644 empty-like/benchmark/benchmark.length.generic.js create mode 100644 empty-like/benchmark/benchmark.length.int16.js create mode 100644 empty-like/benchmark/benchmark.length.int32.js create mode 100644 empty-like/benchmark/benchmark.length.int8.js create mode 100644 empty-like/benchmark/benchmark.length.uint16.js create mode 100644 empty-like/benchmark/benchmark.length.uint32.js create mode 100644 empty-like/benchmark/benchmark.length.uint8.js create mode 100644 empty-like/benchmark/benchmark.length.uint8c.js create mode 100644 empty-like/docs/repl.txt create mode 100644 empty-like/docs/types/index.d.ts create mode 100644 empty-like/docs/types/test.ts create mode 100644 empty-like/examples/index.js create mode 100644 empty-like/lib/index.js create mode 100644 empty-like/lib/main.js create mode 100644 empty-like/package.json create mode 100644 empty-like/test/test.js diff --git a/empty-like/README.md b/empty-like/README.md new file mode 100644 index 00000000..41436d38 --- /dev/null +++ b/empty-like/README.md @@ -0,0 +1,150 @@ + + +# emptyLike + +> Create an uninitialized array having the same length and data type as a provided array. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var emptyLike = require( '@stdlib/array/empty-like' ); +``` + +#### emptyLike( x\[, dtype] ) + +Creates an uninitialized array having the same length and data type as a provided array `x`. + +```javascript +var x = [ 1, 2, 3, 4, 5 ]; + +var arr = emptyLike( x ); +// returns [ 0, 0, 0, 0, 0 ]; +``` + +The function recognizes the following data types: + +- `float64`: double-precision floating-point numbers (IEEE 754) +- `float32`: single-precision floating-point numbers (IEEE 754) +- `complex128`: double-precision complex floating-point numbers +- `complex64`: single-precision complex floating-point numbers +- `int32`: 32-bit two's complement signed integers +- `uint32`: 32-bit unsigned integers +- `int16`: 16-bit two's complement signed integers +- `uint16`: 16-bit unsigned integers +- `int8`: 8-bit two's complement signed integers +- `uint8`: 8-bit unsigned integers +- `uint8c`: 8-bit unsigned integers clamped to `0-255` +- `generic`: generic JavaScript values + +By default, the output array data type is inferred from the provided array `x`. To return an array having a different data type, provide a `dtype` argument. + +```javascript +var x = [ 1, 1 ]; + +var arr = emptyLike( x, 'int32' ); +// returns +``` + +
+ + + + + +
+ +## Notes + +- In browser environments, the function always returns zero-filled arrays. +- If `dtype` is `'generic'`, the function always returns a zero-filled array. +- In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. + +
+ + + + + +
+ +## Examples + + + +```javascript +var dtypes = require( '@stdlib/array/dtypes' ); +var zeros = require( '@stdlib/array/zeros' ); +var emptyLike = require( '@stdlib/array/empty-like' ); + +// Create a zero-filled array: +var x = zeros( 4, 'complex128' ); + +// Get a list of array data types: +var dt = dtypes(); + +// Generate empty arrays... +var arr; +var i; +for ( i = 0; i < dt.length; i++ ) { + arr = emptyLike( x, dt[ i ] ); + console.log( arr ); +} +``` + +
+ + + + + +
+ +
+ + + + + +
+ +
+ + + + + +
+ +
+ + diff --git a/empty-like/benchmark/benchmark.js b/empty-like/benchmark/benchmark.js new file mode 100644 index 00000000..144ad73d --- /dev/null +++ b/empty-like/benchmark/benchmark.js @@ -0,0 +1,317 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' ); +var isArray = require( '@stdlib/assert/is-array' ); +var zeros = require( './../../zeros' ); +var pkg = require( './../package.json' ).name; +var emptyLike = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'float64' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=float64', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'float64' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=float32', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'float32' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=complex128', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'complex128' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=complex64', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'complex64' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=int32', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'int32' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=uint32', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'uint32' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=int16', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'int16' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=uint16', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'uint16' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=int8', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'int8' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=uint8', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'uint8' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=uint8c', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'uint8c' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+':dtype=generic', function benchmark( b ) { + var arr; + var x; + var i; + + x = zeros( 0, 'generic' ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = emptyLike( x ); + if ( arr.length !== 0 ) { + b.fail( 'should have length 0' ); + } + } + b.toc(); + if ( !isArray( arr ) ) { + b.fail( 'should return an array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/empty-like/benchmark/benchmark.length.complex128.js b/empty-like/benchmark/benchmark.length.complex128.js new file mode 100644 index 00000000..c24784c2 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.complex128.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'complex128' ); + 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 ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=complex128,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.complex64.js b/empty-like/benchmark/benchmark.length.complex64.js new file mode 100644 index 00000000..a9e06f11 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.complex64.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'complex64' ); + 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 ( !isTypedArrayLike( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=complex64,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.float32.js b/empty-like/benchmark/benchmark.length.float32.js new file mode 100644 index 00000000..4aa32195 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.float32.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'float32' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=float32,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.float64.js b/empty-like/benchmark/benchmark.length.float64.js new file mode 100644 index 00000000..8f05f52f --- /dev/null +++ b/empty-like/benchmark/benchmark.length.float64.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'float64' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=float64,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.generic.js b/empty-like/benchmark/benchmark.length.generic.js new file mode 100644 index 00000000..57d54b37 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.generic.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isArray = require( '@stdlib/assert/is-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'generic' ); + 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 ( !isArray( arr ) ) { + b.fail( 'should return an array' ); + } + 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=generic,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.int16.js b/empty-like/benchmark/benchmark.length.int16.js new file mode 100644 index 00000000..df51c358 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.int16.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'int16' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=int16,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.int32.js b/empty-like/benchmark/benchmark.length.int32.js new file mode 100644 index 00000000..22770d85 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.int32.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'int32' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=int32,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.int8.js b/empty-like/benchmark/benchmark.length.int8.js new file mode 100644 index 00000000..4ca8ac68 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.int8.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'int8' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=int8,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.uint16.js b/empty-like/benchmark/benchmark.length.uint16.js new file mode 100644 index 00000000..a2e84067 --- /dev/null +++ b/empty-like/benchmark/benchmark.length.uint16.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'uint16' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=uint16,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.uint32.js b/empty-like/benchmark/benchmark.length.uint32.js new file mode 100644 index 00000000..4d3cbf1f --- /dev/null +++ b/empty-like/benchmark/benchmark.length.uint32.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'uint32' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=uint32,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.uint8.js b/empty-like/benchmark/benchmark.length.uint8.js new file mode 100644 index 00000000..020b6c1f --- /dev/null +++ b/empty-like/benchmark/benchmark.length.uint8.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'uint8' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=uint8,len='+len, f ); + } +} + +main(); diff --git a/empty-like/benchmark/benchmark.length.uint8c.js b/empty-like/benchmark/benchmark.length.uint8c.js new file mode 100644 index 00000000..071ece7f --- /dev/null +++ b/empty-like/benchmark/benchmark.length.uint8c.js @@ -0,0 +1,95 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var zeros = require( './../../zeros' ); +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 = zeros( len, 'uint8c' ); + 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 ( !isTypedArray( arr ) ) { + b.fail( 'should return a typed array' ); + } + 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=uint8c,len='+len, f ); + } +} + +main(); diff --git a/empty-like/docs/repl.txt b/empty-like/docs/repl.txt new file mode 100644 index 00000000..baaf8855 --- /dev/null +++ b/empty-like/docs/repl.txt @@ -0,0 +1,53 @@ + +{{alias}}( x[, dtype] ) + Creates an uninitialized array having the same length and data type as a + provided input array. + + In browser environments, the function always returns zero-filled arrays. + + If `dtype` is 'generic', the function always returns a zero-filled array. + + In Node.js versions >=3.0.0, the underlying memory of returned typed arrays + is *not* initialized. Memory contents are unknown and may contain + *sensitive* data. + + The function supports the following data types: + + - float64: double-precision floating-point numbers (IEEE 754) + - float32: single-precision floating-point numbers (IEEE 754) + - complex128: double-precision complex floating-point numbers + - complex64: single-precision complex floating-point numbers + - int32: 32-bit two's complement signed integers + - uint32: 32-bit unsigned integers + - int16: 16-bit two's complement signed integers + - uint16: 16-bit unsigned integers + - int8: 8-bit two's complement signed integers + - uint8: 8-bit unsigned integers + - uint8c: 8-bit unsigned integers clamped to 0-255 + - generic: generic JavaScript values + + Parameters + ---------- + x: TypedArray|Array + Input array. + + dtype: string (optional) + Data type. If not provided, the output array data type is inferred from + the input array. + + Returns + ------- + out: TypedArray|Array + Output array. + + Examples + -------- + > var x = new {{alias:@stdlib/array/float64}}( 2 ); + > var arr = {{alias}}( x ) + + > arr = {{alias}}( x, 'float32' ) + + + See Also + -------- + diff --git a/empty-like/docs/types/index.d.ts b/empty-like/docs/types/index.d.ts new file mode 100644 index 00000000..d5bec8aa --- /dev/null +++ b/empty-like/docs/types/index.d.ts @@ -0,0 +1,798 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2023 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. +*/ + +// TypeScript Version: 2.0 + +/// + +import { AnyArray, Complex128Array, Complex64Array, DataType } from '@stdlib/types/array'; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'float64' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'float64' ): Float64Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float64' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'float32' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'float32' ): Float32Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'complex128' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'complex128' ): Complex128Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'complex64' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'complex64' ): Complex64Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'int32' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'int32' ): Int32Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'int16' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'int16' ): Int16Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'int8' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'int8' ): Int8Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'uint32' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'uint32' ): Uint32Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'uint16' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'uint16' ): Uint16Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'uint8' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'uint8' ): Uint8Array; + +/** +* Creates an uninitialized array having the same length as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'uint8c' ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype: 'uint8c' ): Uint8ClampedArray; + +/** +* Creates a zero-filled array having a specified length. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns zero-filled array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x, 'generic' ); +* // returns [ 0.0, 0.0 ] +*/ +declare function emptyLike( x: AnyArray, dtype: 'generic' ): Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float64' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Float64Array, dtype?: DataType ): Float64Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Float32Array, dtype?: DataType ): Float32Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'complex128' ); +* // returns +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Complex128Array, dtype?: DataType ): Complex128Array; // tslint:disable-line:max-line-length + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'complex64' ); +* // returns +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Complex64Array, dtype?: DataType ): Complex64Array; // tslint:disable-line:max-line-length + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'int32' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Int32Array, dtype?: DataType ): Int32Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'int16' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Int16Array, dtype?: DataType ): Int16Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'int8' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Int8Array, dtype?: DataType ): Int8Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'uint32' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Uint32Array, dtype?: DataType ): Uint32Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'uint16' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Uint16Array, dtype?: DataType ): Uint16Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'uint8' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Uint8Array, dtype?: DataType ): Uint8Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'uint8c' ); +* // returns [ 0, 0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: Uint8ClampedArray, dtype?: DataType ): Uint8ClampedArray; // tslint:disable-line:max-line-length + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* The function supports the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'generic' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x ); +* // returns [ 0.0, 0.0 ] +*/ +declare function emptyLike( x: Array, dtype?: DataType ): Array; + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* ## Notes +* +* - In browser environments, the function always returns zero-filled arrays. +* - If `dtype` is `'generic'`, the function always returns a zero-filled array. +* - In Node.js versions `>=3.0.0`, the underlying memory of returned typed arrays is **not** initialized. Memory contents are unknown and may contain **sensitive** data. +* +* The function recognizes the following data types: +* +* - `float64`: double-precision floating-point numbers (IEEE 754) +* - `float32`: single-precision floating-point numbers (IEEE 754) +* - `complex128`: double-precision complex floating-point numbers +* - `complex64`: single-precision complex floating-point numbers +* - `int32`: 32-bit two's complement signed integers +* - `uint32`: 32-bit unsigned integers +* - `int16`: 16-bit two's complement signed integers +* - `uint16`: 16-bit unsigned integers +* - `int8`: 8-bit two's complement signed integers +* - `uint8`: 8-bit unsigned integers +* - `uint8c`: 8-bit unsigned integers clamped to `0-255` +* - `generic`: generic JavaScript values +* +* @param x - input array from which to derive the output array length +* @param dtype - data type +* @returns empty array +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float32' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x ); +* // returns +* +* @example +* var zeros = require( `@stdlib/array/zeros` ); +* +* var x = zeros( 2, 'float64' ); +* // returns [ 0.0, 0.0 ] +* +* var arr = emptyLike( x ); +* // returns +*/ +declare function emptyLike( x: AnyArray, dtype?: DataType ): AnyArray; + + +// EXPORTS // + +export = emptyLike; diff --git a/empty-like/docs/types/test.ts b/empty-like/docs/types/test.ts new file mode 100644 index 00000000..2dde21fd --- /dev/null +++ b/empty-like/docs/types/test.ts @@ -0,0 +1,93 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2023 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. +*/ + +import Complex128Array = require( './../../../complex128' ); +import Complex64Array = require( './../../../complex64' ); +import emptyLike = require( './index' ); + + +// TESTS // + +// The function returns an array or typed array... +{ + emptyLike( [ 0, 0 ] ); // $ExpectType number[] + emptyLike( new Float64Array( [ 0, 0 ] ) ); // $ExpectType Float64Array + emptyLike( new Float32Array( [ 0, 0 ] ) ); // $ExpectType Float32Array + emptyLike( new Complex128Array( [ 0, 0 ] ) ); // $ExpectType Complex128Array + emptyLike( new Complex128Array( [ 0, 0 ] ) ); // $ExpectType Complex128Array + emptyLike( new Complex64Array( [ 0, 0 ] ) ); // $ExpectType Complex64Array + emptyLike( new Complex64Array( [ 0, 0 ] ) ); // $ExpectType Complex64Array + emptyLike( new Int32Array( [ 0, 0 ] ) ); // $ExpectType Int32Array + emptyLike( new Int16Array( [ 0, 0 ] ) ); // $ExpectType Int16Array + emptyLike( new Int8Array( [ 0, 0 ] ) ); // $ExpectType Int8Array + emptyLike( new Uint32Array( [ 0, 0 ] ) ); // $ExpectType Uint32Array + emptyLike( new Uint16Array( [ 0, 0 ] ) ); // $ExpectType Uint16Array + emptyLike( new Uint8Array( [ 0, 0 ] ) ); // $ExpectType Uint8Array + emptyLike( new Uint8ClampedArray( [ 0, 0 ] ) ); // $ExpectType Uint8ClampedArray + + emptyLike( [ 0, 0 ], 'float64' ); // $ExpectType Float64Array + emptyLike( [ 0, 0 ], 'float32' ); // $ExpectType Float32Array + emptyLike( [ 0, 0 ], 'complex128' ); // $ExpectType Complex128Array + emptyLike( [ 0, 0 ], 'complex128' ); // $ExpectType Complex128Array + emptyLike( [ 0, 0 ], 'complex64' ); // $ExpectType Complex64Array + emptyLike( [ 0, 0 ], 'complex64' ); // $ExpectType Complex64Array + emptyLike( [ 0, 0 ], 'int32' ); // $ExpectType Int32Array + emptyLike( [ 0, 0 ], 'int16' ); // $ExpectType Int16Array + emptyLike( [ 0, 0 ], 'int8' ); // $ExpectType Int8Array + emptyLike( [ 0, 0 ], 'uint32' ); // $ExpectType Uint32Array + emptyLike( [ 0, 0 ], 'uint16' ); // $ExpectType Uint16Array + emptyLike( [ 0, 0 ], 'uint8' ); // $ExpectType Uint8Array + emptyLike( [ 0, 0 ], 'uint8c' ); // $ExpectType Uint8ClampedArray + emptyLike( [ 0, 0 ], 'generic' ); // $ExpectType number[] +} + +// The compiler throws an error if the function is not provided an array or typed array for the first argument... +{ + emptyLike( '5' ); // $ExpectError + emptyLike( false ); // $ExpectError + emptyLike( true ); // $ExpectError + emptyLike( null ); // $ExpectError + emptyLike( undefined ); // $ExpectError + emptyLike( {} ); // $ExpectError + emptyLike( ( x: number ): number => x ); // $ExpectError + + emptyLike( '5', 'float32' ); // $ExpectError + emptyLike( false, 'float32' ); // $ExpectError + emptyLike( true, 'float32' ); // $ExpectError + emptyLike( null, 'float32' ); // $ExpectError + emptyLike( undefined, 'float32' ); // $ExpectError + emptyLike( {}, 'float32' ); // $ExpectError + emptyLike( ( x: number ): number => x, 'float32' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is an unrecognized/unsupported data type... +{ + emptyLike( [ 0, 0 ], '10' ); // $ExpectError + emptyLike( [ 0, 0 ], 10 ); // $ExpectError + emptyLike( [ 0, 0 ], false ); // $ExpectError + emptyLike( [ 0, 0 ], true ); // $ExpectError + emptyLike( [ 0, 0 ], null ); // $ExpectError + emptyLike( [ 0, 0 ], [] ); // $ExpectError + emptyLike( [ 0, 0 ], {} ); // $ExpectError + emptyLike( [ 0, 0 ], ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + emptyLike( [ 0, 0 ], 'float64', 1 ); // $ExpectError +} diff --git a/empty-like/examples/index.js b/empty-like/examples/index.js new file mode 100644 index 00000000..cd0df924 --- /dev/null +++ b/empty-like/examples/index.js @@ -0,0 +1,37 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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'; + +var dtypes = require( './../../dtypes' ); +var zeros = require( './../../zeros' ); +var emptyLike = require( './../lib' ); + +// Create a zero-filled array: +var x = zeros( 4, 'complex128' ); + +// Get a list of array data types: +var dt = dtypes(); + +// Generate empty arrays... +var arr; +var i; +for ( i = 0; i < dt.length; i++ ) { + arr = emptyLike( x, dt[ i ] ); + console.log( arr ); +} diff --git a/empty-like/lib/index.js b/empty-like/lib/index.js new file mode 100644 index 00000000..a8d8a8bd --- /dev/null +++ b/empty-like/lib/index.js @@ -0,0 +1,46 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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'; + +/** +* Create an uninitialized array having the same length and data type as a provided input array. +* +* @module @stdlib/array/empty-like +* +* @example +* var emptyLike = require( '@stdlib/array/empty-like' ); +* +* var arr = emptyLike( [ 0.0, 0.0 ] ); +* // returns [ 0.0, 0.0 ] +* +* @example +* var emptyLike = require( '@stdlib/array/empty-like' ); +* +* var arr = emptyLike( [ 0.0, 0.0 ], 'float32' ); +* // returns +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/empty-like/lib/main.js b/empty-like/lib/main.js new file mode 100644 index 00000000..3de22bda --- /dev/null +++ b/empty-like/lib/main.js @@ -0,0 +1,61 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 dtype = require( './../../dtype' ); +var empty = require( './../../empty' ); +var format = require( '@stdlib/string/format' ); + + +// MAIN // + +/** +* Creates an uninitialized array having the same length and data type as a provided input array. +* +* @param {(Array|TypedArray|ComplexArray)} x - input array +* @param {string} [dtype] - data type +* @throws {TypeError} first argument must be an array or typed array +* @throws {TypeError} second argument must be a recognized data type +* @returns {(TypedArray|Array|ComplexArray)} array or typed array +* +* @example +* var arr = emptyLike( [ 0.0, 0.0 ] ); +* // returns [ 0.0, 0.0 ] +* +* @example +* var arr = emptyLike( [ 0.0, 0.0 ], 'float32' ); +* // returns +*/ +function emptyLike( x ) { + var dt = dtype( x ); // delegate input argument validation to dtype resolution + if ( dt === null ) { + throw new TypeError( format( 'invalid argument. First argument must be either an array, typed array, or complex typed array. Value: `%s`.', x ) ); + } + if ( arguments.length > 1 ) { + dt = arguments[ 1 ]; + } + return empty( x.length, dt ); +} + + +// EXPORTS // + +module.exports = emptyLike; diff --git a/empty-like/package.json b/empty-like/package.json new file mode 100644 index 00000000..9670dbcd --- /dev/null +++ b/empty-like/package.json @@ -0,0 +1,105 @@ +{ + "name": "@stdlib/array/empty-like", + "version": "0.0.0", + "description": "Create an uninitialized array having the same length and data type as a provided array.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdtypes", + "types", + "data", + "structure", + "typed", + "array", + "typed array", + "typed-array", + "vector", + "ndarray", + "matrix", + "float64array", + "float32array", + "int32array", + "uint32array", + "int16array", + "uint16array", + "int8array", + "uint8array", + "uint8clampedarray", + "complex128array", + "complex64array", + "complex128", + "complex64", + "complex", + "cmplx", + "float64", + "double", + "precision", + "double-precision", + "single", + "float", + "single-precision", + "float32", + "ieee754", + "integer", + "int32", + "signed", + "unsigned", + "uint32", + "int16", + "uint16", + "int8", + "uint8", + "uint8c", + "clamped", + "short", + "long", + "generic", + "empty", + "empty-like" + ] +} diff --git a/empty-like/test/test.js b/empty-like/test/test.js new file mode 100644 index 00000000..275f36b4 --- /dev/null +++ b/empty-like/test/test.js @@ -0,0 +1,450 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2023 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 tape = require( 'tape' ); +var Float64Array = require( './../../float64' ); +var Float32Array = require( './../../float32' ); +var Int32Array = require( './../../int32' ); +var Uint32Array = require( './../../uint32' ); +var Int16Array = require( './../../int16' ); +var Uint16Array = require( './../../uint16' ); +var Int8Array = require( './../../int8' ); +var Uint8Array = require( './../../uint8' ); +var Uint8ClampedArray = require( './../../uint8c' ); +var Complex64Array = require( './../../complex64' ); +var Complex128Array = require( './../../complex128' ); +var instanceOf = require( '@stdlib/assert/instance-of' ); +var emptyLike = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof emptyLike, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if provided a value other than an array having a supported data type for the first argument', function test( t ) { + var values; + var i; + + values = [ + '5', + -3, + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + function noop() {} + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + emptyLike( value ); + }; + } +}); + +tape( 'the function throws an error if provided a value other than an array having a supported data type for the first argument (dtype)', function test( t ) { + var values; + var i; + + values = [ + '5', + -3, + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + function noop() {} + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + emptyLike( value, 'float32' ); + }; + } +}); + +tape( 'the function throws an error if provided an unrecognized data type', function test( t ) { + var values; + var i; + + values = [ + '5', + 'beep', + 'emptyLike', + 'Int32', + 'Uint32', + 'Int16', + 'Uint16', + 'Int8', + 'Uint8', + 'Uint8c', + 'uint8_clamped', + 'Float64', + 'Float32', + 'FLOAT64', + 'FLOAT32', + 'GENERIC' + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + emptyLike( [], value ); + }; + } +}); + +tape( 'the function returns an empty array (float64)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Float64Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=float64)', function test( t ) { + var arr; + var x; + + x = new Float32Array( 5 ); + + arr = emptyLike( x, 'float64' ); + t.strictEqual( instanceOf( arr, Float64Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (float32)', function test( t ) { + var arr; + var x; + + x = new Float32Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Float32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=float32)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'float32' ); + t.strictEqual( instanceOf( arr, Float32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (complex128)', function test( t ) { + var arr; + var x; + + x = new Complex128Array( 2 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Complex128Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=complex128)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 2 ); + + arr = emptyLike( x, 'complex128' ); + t.strictEqual( instanceOf( arr, Complex128Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (complex64)', function test( t ) { + var arr; + var x; + + x = new Complex64Array( 2 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Complex64Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=complex64)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 2 ); + + arr = emptyLike( x, 'complex64' ); + t.strictEqual( instanceOf( arr, Complex64Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (int32)', function test( t ) { + var arr; + var x; + + x = new Int32Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Int32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=int32)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'int32' ); + t.strictEqual( instanceOf( arr, Int32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (uint32)', function test( t ) { + var arr; + var x; + + x = new Uint32Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Uint32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=uint32)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'uint32' ); + t.strictEqual( instanceOf( arr, Uint32Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (int16)', function test( t ) { + var arr; + var x; + + x = new Int16Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Int16Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=int16)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'int16' ); + t.strictEqual( instanceOf( arr, Int16Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (uint16)', function test( t ) { + var arr; + var x; + + x = new Uint16Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Uint16Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=uint16)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'uint16' ); + t.strictEqual( instanceOf( arr, Uint16Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (int8)', function test( t ) { + var arr; + var x; + + x = new Int8Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Int8Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=int8)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'int8' ); + t.strictEqual( instanceOf( arr, Int8Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (uint8)', function test( t ) { + var arr; + var x; + + x = new Uint8Array( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Uint8Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=uint8)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'uint8' ); + t.strictEqual( instanceOf( arr, Uint8Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (uint8c)', function test( t ) { + var arr; + var x; + + x = new Uint8ClampedArray( 5 ); + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Uint8ClampedArray ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=uint8c)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'uint8c' ); + t.strictEqual( instanceOf( arr, Uint8ClampedArray ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (generic)', function test( t ) { + var arr; + var x; + + x = [ 1, 2, 3, 4, 5 ]; + + arr = emptyLike( x ); + t.strictEqual( instanceOf( arr, Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array (dtype=generic)', function test( t ) { + var arr; + var x; + + x = new Float64Array( 5 ); + + arr = emptyLike( x, 'generic' ); + t.strictEqual( instanceOf( arr, Array ), true, 'returns expected value' ); + t.strictEqual( arr.length, x.length, 'returns expected value' ); + + t.end(); +});