diff --git a/CHANGELOG.md b/CHANGELOG.md index ccaf2876..44d843b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,28 @@ ### Packages +
+ +#### [@stdlib/array/base](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base) + +
+ +
+ +##### Features + +- [`42664da`](https://github.com/stdlib-js/stdlib/commit/42664dafb94e72a8b8eca80ede6669caaaf57e68) - add `nulls` to namespace + +
+ + + +
+ +
+ + +
#### [@stdlib/array/base/assert](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/assert) @@ -153,6 +175,28 @@ +
+ +#### [@stdlib/array/base/nulls](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/nulls) + +
+ +
+ +##### Features + +- [`6d91993`](https://github.com/stdlib-js/stdlib/commit/6d9199381c3e949420349ba3506ecd59c692be44) - add `array/base/nulls` + +
+ + + +
+ +
+ + +
#### [@stdlib/array/bool](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/bool) @@ -289,6 +333,8 @@ A total of 5 people contributed to this release. Thank you to the following cont
+- [`42664da`](https://github.com/stdlib-js/stdlib/commit/42664dafb94e72a8b8eca80ede6669caaaf57e68) - **feat:** add `nulls` to namespace _(by Athan Reines)_ +- [`6d91993`](https://github.com/stdlib-js/stdlib/commit/6d9199381c3e949420349ba3506ecd59c692be44) - **feat:** add `array/base/nulls` _(by Athan Reines)_ - [`b723a6e`](https://github.com/stdlib-js/stdlib/commit/b723a6eaec97adad2da4ffbecb532a3d1ae1e0ba) - **docs:** fix errors in comments and clean-up _(by Philipp Burckhardt)_ - [`eb82943`](https://github.com/stdlib-js/stdlib/commit/eb82943ec2ac2b3023377cbc320486d333f47e48) - **chore:** minor clean-up _(by Philipp Burckhardt)_ - [`3c8bcb9`](https://github.com/stdlib-js/stdlib/commit/3c8bcb938befe35d784ba3fe0dea124dd4b20b36) - **chore:** minor clean-up _(by Philipp Burckhardt)_ diff --git a/base/lib/index.js b/base/lib/index.js index ecc37636..d0dd57d3 100644 --- a/base/lib/index.js +++ b/base/lib/index.js @@ -1116,6 +1116,15 @@ setReadOnly( ns, 'noneBy', require( './../../base/none-by' ) ); */ setReadOnly( ns, 'noneByRight', require( './../../base/none-by-right' ) ); +/** +* @name nulls +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/nulls} +*/ +setReadOnly( ns, 'nulls', require( './../../base/nulls' ) ); + /** * @name oneTo * @memberof ns diff --git a/base/nulls/README.md b/base/nulls/README.md new file mode 100644 index 00000000..0659f9c0 --- /dev/null +++ b/base/nulls/README.md @@ -0,0 +1,108 @@ + + +# nulls + +> Create a "generic" array filled with null values. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var nulls = require( '@stdlib/array/base/nulls' ); +``` + +#### nulls( len ) + +Returns a "generic" array filled with `null` values. + +```javascript +var out = nulls( 3 ); +// returns [ null, null, null ] +``` + +
+ + + + + +
+ +
+ + + + + +
+ +## Examples + + + +```javascript +var nulls = require( '@stdlib/array/base/nulls' ); + +// Create a null value array: +var arr = nulls( 10 ); + +console.log( arr ); +// => [ null, null, null, null, null, null, null, null, null, null ] +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/base/nulls/benchmark/benchmark.length.js b/base/nulls/benchmark/benchmark.length.js new file mode 100644 index 00000000..2b8c6850 --- /dev/null +++ b/base/nulls/benchmark/benchmark.length.js @@ -0,0 +1,94 @@ +/** +* @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 isArray = require( '@stdlib/assert/is-array' ); +var pkg = require( './../package.json' ).name; +var nulls = 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 out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = nulls( len ); + if ( out.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isArray( out ) ) { + 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+':len='+len, f ); + } +} + +main(); diff --git a/base/nulls/docs/repl.txt b/base/nulls/docs/repl.txt new file mode 100644 index 00000000..fdaf39cb --- /dev/null +++ b/base/nulls/docs/repl.txt @@ -0,0 +1,22 @@ + +{{alias}}( len ) + Returns a "generic" array filled with null values. + + Parameters + ---------- + len: integer + Array length. + + Returns + ------- + out: Array + Output array. + + Examples + -------- + > var out = {{alias}}( 3 ) + [ null, null, null ] + + See Also + -------- + diff --git a/base/nulls/docs/types/index.d.ts b/base/nulls/docs/types/index.d.ts new file mode 100644 index 00000000..487ab3cc --- /dev/null +++ b/base/nulls/docs/types/index.d.ts @@ -0,0 +1,36 @@ +/* +* @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. +*/ + +// TypeScript Version: 4.1 + +/** +* Returns a "generic" array filled with nulls. +* +* @param len - array length +* @returns output array +* +* @example +* var out = nulls( 3 ); +* // returns [ null, null, null ] +*/ +declare function nulls( len: number ): Array; + + +// EXPORTS // + +export = nulls; diff --git a/base/nulls/docs/types/test.ts b/base/nulls/docs/types/test.ts new file mode 100644 index 00000000..34fbde48 --- /dev/null +++ b/base/nulls/docs/types/test.ts @@ -0,0 +1,44 @@ +/* +* @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. +*/ + +import nulls = require( './index' ); + + +// TESTS // + +// The function returns an array... +{ + nulls( 3 ); // $ExpectType null[] +} + +// The compiler throws an error if the function is provided an argument which is not a number... +{ + nulls( 'abc' ); // $ExpectError + nulls( true ); // $ExpectError + nulls( false ); // $ExpectError + nulls( null ); // $ExpectError + nulls( [] ); // $ExpectError + nulls( {} ); // $ExpectError + nulls( ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + nulls(); // $ExpectError + nulls( 3, 2 ); // $ExpectError +} diff --git a/base/nulls/examples/index.js b/base/nulls/examples/index.js new file mode 100644 index 00000000..cc7ba529 --- /dev/null +++ b/base/nulls/examples/index.js @@ -0,0 +1,27 @@ +/** +* @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'; + +var nulls = require( './../lib' ); + +// Create a null value array: +var arr = nulls( 10 ); + +console.log( arr ); +// => [ null, null, null, null, null, null, null, null, null, null ] diff --git a/base/nulls/lib/index.js b/base/nulls/lib/index.js new file mode 100644 index 00000000..e30573f6 --- /dev/null +++ b/base/nulls/lib/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +/** +* Create a "generic" array filled with null values. +* +* @module @stdlib/array/base/nulls +* +* @example +* var nulls = require( '@stdlib/array/base/nulls' ); +* +* var out = nulls( 3 ); +* // returns [ null, null, null ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/base/nulls/lib/main.js b/base/nulls/lib/main.js new file mode 100644 index 00000000..3737a202 --- /dev/null +++ b/base/nulls/lib/main.js @@ -0,0 +1,45 @@ +/** +* @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 filled = require( './../../../base/filled' ); + + +// MAIN // + +/** +* Returns a "generic" array filled with null values. +* +* @param {NonNegativeInteger} len - array length +* @returns {Array} output array +* +* @example +* var out = nulls( 3 ); +* // returns [ null, null, null ] +*/ +function nulls( len ) { + return filled( null, len ); +} + + +// EXPORTS // + +module.exports = nulls; diff --git a/base/nulls/package.json b/base/nulls/package.json new file mode 100644 index 00000000..41b9d684 --- /dev/null +++ b/base/nulls/package.json @@ -0,0 +1,65 @@ +{ + "name": "@stdlib/array/base/nulls", + "version": "0.0.0", + "description": "Create a generic array filled with null values.", + "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", + "array", + "generic", + "allocate", + "alloc", + "fill", + "filled", + "null" + ] +} diff --git a/base/nulls/test/test.js b/base/nulls/test/test.js new file mode 100644 index 00000000..e67dc002 --- /dev/null +++ b/base/nulls/test/test.js @@ -0,0 +1,55 @@ +/** +* @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 tape = require( 'tape' ); +var nulls = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof nulls, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns a "generic" array filled with null values', function test( t ) { + var expected; + var actual; + + expected = [ null, null, null ]; + actual = nulls( 3 ); + + t.deepEqual( actual, expected, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns an empty array if provided a length of `0`', function test( t ) { + var expected; + var actual; + + expected = []; + actual = nulls( 0 ); + + t.deepEqual( actual, expected, 'returns expected value' ); + t.end(); +});