feat: add boolean dtype support to ndarray/from-scalar

PR-URL: #2589
Ref: #2547
Co-authored-by: Athan Reines <kgryte@gmail.com>
Reviewed-by: Athan Reines <kgryte@gmail.com>

Author: Jaysukh-409

lib/node_modules/@stdlib/ndarray/from-scalar/README.md

@@ -2,7 +2,7 @@
 
 @license Apache-2.0
 
-Copyright (c) 2022 The Stdlib Authors.
+Copyright (c) 2024 The Stdlib Authors.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -66,7 +66,8 @@ The function accepts the following `options`:
 
 If a `dtype` option is not provided and `value`
 
--   is a `number`, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] real-valued floating-point data type.
+-   is a number, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] real-valued floating-point data type.
+-   is a boolean, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] boolean data type.
 -   is a complex number object of a known data type, the data type is the same as the provided value.
 -   is a complex number object of an unknown data type, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] complex-valued floating-point data type.
 -   is any other value type, the default [data type][@stdlib/ndarray/dtypes] is `'generic'`.
@@ -100,6 +101,7 @@ var v = x.get();
 ## Notes
 
 -   If `value` is a number and `options.dtype` is a complex [data type][@stdlib/ndarray/dtypes], the function returns a zero-dimensional [`ndarray`][@stdlib/ndarray/ctor] containing a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
+-   The function does not guard against precision loss when `value` is a number and the `dtype` argument is an integer [data type][@stdlib/ndarray/dtypes].
 
 </section>
 

lib/node_modules/@stdlib/ndarray/from-scalar/benchmark/benchmark.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2022 The Stdlib Authors.
+* Copyright (c) 2024 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -120,6 +120,30 @@ bench( pkg+':dtype=complex64', function benchmark( b ) {
 	b.end();
 });
 
+bench( pkg+':dtype=bool', function benchmark( b ) {
+	var x;
+	var v;
+	var i;
+
+	v = [ true, false ];
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		x = scalar2ndarray( v[ i%2 ], {
+			'dtype': 'bool'
+		});
+		if ( x.length !== 1 ) {
+			b.fail( 'should have length 1' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( x ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
 bench( pkg+':dtype=int32', function benchmark( b ) {
 	var x;
 	var i;

lib/node_modules/@stdlib/ndarray/from-scalar/docs/repl.txt

@@ -20,6 +20,7 @@
 
         - is a number, the default data type is the default real-valued
           floating-point data type.
+        - is a boolean, the default data type is the default boolean data type.
         - is a complex number object of a known complex data type, the data type
           is the same as the provided value.
         - is a complex number object of an unknown data type, the default data

lib/node_modules/@stdlib/ndarray/from-scalar/docs/types/index.d.ts

@@ -1,7 +1,7 @@
 /*
 * @license Apache-2.0
 *
-* Copyright (c) 2022 The Stdlib Authors.
+* Copyright (c) 2024 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@
 /// <reference types="@stdlib/types"/>
 
 import { ComplexLike } from '@stdlib/types/complex';
-import { ndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, DataType, Order } from '@stdlib/types/ndarray';
+import { ndarray, float64ndarray, float32ndarray, int32ndarray, int16ndarray, int8ndarray, uint32ndarray, uint16ndarray, uint8ndarray, uint8cndarray, complex128ndarray, complex64ndarray, boolndarray, DataType, Order } from '@stdlib/types/ndarray';
 
 /**
 * Interface defining common options.
@@ -88,6 +88,16 @@ interface Complex64Options extends BaseOptions {
 	dtype: 'complex64';
 }
 
+/**
+* Interface defining options when `dtype` is `'bool'`.
+*/
+interface BoolOptions extends BaseOptions {
+	/**
+	* Output array data type.
+	*/
+	dtype: 'bool';
+}
+
 /**
 * Interface defining options when `dtype` is `'int32'`.
 */
@@ -286,6 +296,30 @@ declare function scalar2ndarray( value: number | ComplexLike, options: Complex12
 */
 declare function scalar2ndarray( value: number | ComplexLike, options: Complex64Options ): complex64ndarray;
 
+/**
+* Returns a zero-dimensional ndarray containing a provided scalar value.
+*
+* @param value - scalar value
+* @param options - options
+* @returns zero-dimensional ndarray
+*
+* @example
+* var x = scalar2ndarray( true, {
+*     'dtype': bool'
+* };
+* // returns <ndarray>
+*
+* var sh = x.shape;
+* // returns []
+*
+* var dt = x.dtype;
+* // returns 'bool'
+*
+* var v = x.get();
+* // returns true
+*/
+declare function scalar2ndarray( value: boolean, options: BoolOptions ): boolndarray;
+
 /**
 * Returns a zero-dimensional ndarray containing a provided scalar value.
 *
@@ -461,7 +495,8 @@ declare function scalar2ndarray( value: number, options: Uint8cOptions ): uint8c
 *
 * -   If a `dtype` option is not provided and `value`
 *
-*     -   is a `number`, the default data type is the default real-valued floating-point data type.
+*     -   is a number, the default data type is the default real-valued floating-point data type.
+*     -   is a boolean, the default data type is the default boolean data type.
 *     -   is a complex number object of a known complex data type, the data type is the same as the provided value.
 *     -   is a complex number object of an unknown complex data type, the default data type is the default complex-valued floating-point data type.
 *     -   is any other value type, the default data type is `'generic'`.

lib/node_modules/@stdlib/ndarray/from-scalar/docs/types/test.ts

@@ -1,7 +1,7 @@
 /*
 * @license Apache-2.0
 *
-* Copyright (c) 2022 The Stdlib Authors.
+* Copyright (c) 2024 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -29,6 +29,7 @@ import scalar2ndarray = require( './index' );
 	scalar2ndarray( 1.0, { 'dtype': 'float32' } ); // $ExpectType float32ndarray
 	scalar2ndarray( 1.0, { 'dtype': 'complex128' } ); // $ExpectType complex128ndarray
 	scalar2ndarray( 1.0, { 'dtype': 'complex64' } ); // $ExpectType complex64ndarray
+	scalar2ndarray( true, { 'dtype': 'bool' } ); // $ExpectType boolndarray
 	scalar2ndarray( 1.0, { 'dtype': 'int32' } ); // $ExpectType int32ndarray
 	scalar2ndarray( 1.0, { 'dtype': 'int16' } ); // $ExpectType int16ndarray
 	scalar2ndarray( 1.0, { 'dtype': 'int8' } ); // $ExpectType int8ndarray

lib/node_modules/@stdlib/ndarray/from-scalar/lib/main.js

@@ -23,7 +23,9 @@
 var hasOwnProp = require( '@stdlib/assert/has-own-property' );
 var isPlainObject = require( '@stdlib/assert/is-plain-object' );
 var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
+var isComplexDataType = require( '@stdlib/array/base/assert/is-complex-floating-point-data-type' );
 var isComplexLike = require( '@stdlib/assert/is-complex-like' );
+var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
 var isAccessorArray = require( '@stdlib/array/base/assert/is-accessor-array' );
 var accessorSetter = require( '@stdlib/array/base/accessor-setter' );
 var setter = require( '@stdlib/array/base/setter' );
@@ -39,6 +41,7 @@ var format = require( '@stdlib/string/format' );
 var ORDER = defaults.get( 'order' );
 var DEFAULT_REAL = defaults.get( 'dtypes.real_floating_point' );
 var DEFAULT_CMPLX = defaults.get( 'dtypes.complex_floating_point' );
+var DEFAULT_BOOL = defaults.get( 'dtypes.boolean' );
 
 
 // MAIN //
@@ -50,7 +53,8 @@ var DEFAULT_CMPLX = defaults.get( 'dtypes.complex_floating_point' );
 *
 * -   If a `dtype` option is not provided and `value`
 *
-*     -   is a `number`, the default data type is the default real-valued floating-point data type.
+*     -   is a number, the default data type is the default real-valued floating-point data type.
+*     -   is a boolean, the default data type is the default boolean data type.
 *     -   is a complex number object of a known complex data type, the data type is the same as the provided value.
 *     -   is a complex number object of an unknown complex data type, the default data type is the default complex-valued floating-point data type.
 *     -   is any other value type, the default data type is `'generic'`.
@@ -125,6 +129,8 @@ function scalar2ndarray( value ) {
 	if ( opts.dtype === '' ) {
 		if ( flg ) {
 			dt = DEFAULT_REAL;
+		} else if ( isBoolean( value ) ) {
+			dt = DEFAULT_BOOL;
 		} else if ( isComplexLike( value ) ) {
 			dt = dtype( value );
 			if ( dt === null ) {
@@ -140,7 +146,7 @@ function scalar2ndarray( value ) {
 	if ( buf === null ) {
 		throw new TypeError( format( 'invalid option. `%s` option must be a recognized data type. Option: `%s`.', 'dtype', dt ) );
 	}
-	if ( /^complex/.test( dt ) && flg ) {
+	if ( isComplexDataType( dt ) && flg ) {
 		v = [ value, 0.0 ]; // note: we're assuming that the ComplexXXArray setter accepts an array of interleaved real and imaginary components
 	} else {
 		v = value;

lib/node_modules/@stdlib/ndarray/from-scalar/test/test.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2022 The Stdlib Authors.
+* Copyright (c) 2024 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -32,8 +32,10 @@ var Uint8Array = require( '@stdlib/array/uint8' );
 var Uint8ClampedArray = require( '@stdlib/array/uint8c' );
 var Complex64Array = require( '@stdlib/array/complex64' );
 var Complex128Array = require( '@stdlib/array/complex128' );
+var BooleanArray = require( '@stdlib/array/bool' );
 var reinterpret64 = require( '@stdlib/strided/base/reinterpret-complex64' );
 var reinterpret128 = require( '@stdlib/strided/base/reinterpret-complex128' );
+var reinterpretBoolean = require( '@stdlib/strided/base/reinterpret-boolean' );
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 var Complex64 = require( '@stdlib/complex/float32/ctor' );
 var instanceOf = require( '@stdlib/assert/instance-of' );
@@ -230,6 +232,37 @@ tape( 'the function returns a zero-dimensional ndarray (default, complex64)', fu
 	t.end();
 });
 
+tape( 'the function returns a zero-dimensional ndarray (default, bool)', function test( t ) {
+	var expected;
+	var arr;
+
+	expected = new Uint8Array( [ 1 ] );
+
+	arr = scalar2ndarray( true );
+
+	t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' );
+	t.strictEqual( arr.dtype, 'bool', 'returns expected value' );
+	t.deepEqual( arr.shape, [], 'returns expected value' );
+	t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' );
+	t.deepEqual( reinterpretBoolean( arr.data, 0 ), expected, 'returns expected value' );
+	t.strictEqual( arr.order, 'row-major', 'returns expected value' );
+	t.strictEqual( arr.length, 1, 'returns expected value' );
+
+	expected = new Uint8Array( [ 0 ] );
+
+	arr = scalar2ndarray( false );
+
+	t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' );
+	t.strictEqual( arr.dtype, 'bool', 'returns expected value' );
+	t.deepEqual( arr.shape, [], 'returns expected value' );
+	t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' );
+	t.deepEqual( reinterpretBoolean( arr.data, 0 ), expected, 'returns expected value' );
+	t.strictEqual( arr.order, 'row-major', 'returns expected value' );
+	t.strictEqual( arr.length, 1, 'returns expected value' );
+
+	t.end();
+});
+
 tape( 'the function returns a zero-dimensional ndarray (default, other)', function test( t ) {
 	var expected;
 	var arr;
@@ -428,6 +461,39 @@ tape( 'the function returns a zero-dimensional ndarray (dtype=uint8c)', function
 	t.end();
 });
 
+tape( 'the function returns a zero-dimensional ndarray (dtype=bool)', function test( t ) {
+	var expected;
+	var arr;
+
+	expected = new Uint8Array( [ 1 ] );
+	arr = scalar2ndarray( true, {
+		'dtype': 'bool'
+	});
+
+	t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' );
+	t.strictEqual( arr.dtype, 'bool', 'returns expected value' );
+	t.deepEqual( arr.shape, [], 'returns expected value' );
+	t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' );
+	t.deepEqual( reinterpretBoolean( arr.data, 0 ), expected, 'returns expected value' );
+	t.strictEqual( arr.order, 'row-major', 'returns expected value' );
+	t.strictEqual( arr.length, 1, 'returns expected value' );
+
+	expected = new Uint8Array( [ 0 ] );
+	arr = scalar2ndarray( false, {
+		'dtype': 'bool'
+	});
+
+	t.strictEqual( instanceOf( arr, ndarray ), true, 'returns expected value' );
+	t.strictEqual( arr.dtype, 'bool', 'returns expected value' );
+	t.deepEqual( arr.shape, [], 'returns expected value' );
+	t.strictEqual( instanceOf( arr.data, BooleanArray ), true, 'returns expected value' );
+	t.deepEqual( reinterpretBoolean( arr.data, 0 ), expected, 'returns expected value' );
+	t.strictEqual( arr.order, 'row-major', 'returns expected value' );
+	t.strictEqual( arr.length, 1, 'returns expected value' );
+
+	t.end();
+});
+
 tape( 'the function returns a zero-dimensional ndarray (dtype=complex128, complex)', function test( t ) {
 	var expected;
 	var arr;