feat: add boolean dtype support to array/convert

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

Author: Jaysukh-409

lib/node_modules/@stdlib/array/convert/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # convert
 
-> Convert an array to an array of a different data type.
+> Convert an array to an array of a different [data type][@stdlib/array/dtypes].
 
 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
 
@@ -42,29 +42,14 @@ var convert = require( '@stdlib/array/convert' );
 
 #### convert( arr, dtype )
 
-Converts an array to an array of a different data type.
+Converts an array to an array of a different [data type][@stdlib/array/dtypes].
 
 ```javascript
 var arr = [ 1.0, 2.0, 3.0 ];
 var out = convert( arr, 'float32' );
 // returns <Float32Array>[ 1.0, 2.0, 3.0 ]
 ```
 
-The function supports the following data types:
-
--   `float32`: single-precision floating-point numbers.
--   `float64`: double-precision floating-point numbers.
--   `complex64`: single-precision complex floating-point numbers.
--   `complex128`: double-precision complex floating-point numbers.
--   `generic`: values of any type.
--   `int16`: signed 16-bit integers.
--   `int32`: signed 32-bit integers.
--   `int8`: signed 8-bit integers.
--   `uint16`: unsigned 16-bit integers.
--   `uint32`: unsigned 32-bit integers.
--   `uint8`: unsigned 8-bit integers.
--   `uint8c`: unsigned clamped 8-bit integers.
-
 </section>
 
 <!-- /.usage -->
@@ -136,6 +121,8 @@ for ( i = 0; i < DTYPES.length; i++ ) {
 
 <section class="links">
 
+[@stdlib/array/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/dtypes
+
 <!-- <related-links> -->
 
 [@stdlib/array/convert-same]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/convert-same

lib/node_modules/@stdlib/array/convert/benchmark/benchmark.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2018 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.
@@ -103,6 +103,31 @@ bench( pkg+':dtype=float32', function benchmark( b ) {
 	b.end();
 });
 
+bench( pkg+':dtype=bool', function benchmark( b ) {
+	var arr;
+	var out;
+	var i;
+
+	arr = [];
+	for ( i = 0; i < 10; i++ ) {
+		arr.push( i );
+	}
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		arr[ 0 ] += 1;
+		out = convertArray( arr, 'bool' );
+		if ( out.length !== arr.length ) {
+			b.fail( 'should have expected length' );
+		}
+	}
+	b.toc();
+	if ( !isCollection( out ) ) {
+		b.fail( 'should return an array-like object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
 bench( pkg+':dtype=complex128', function benchmark( b ) {
 	var arr;
 	var out;

lib/node_modules/@stdlib/array/convert/benchmark/benchmark.length.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2018 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.
@@ -103,6 +103,9 @@ function main() {
 		f = createBenchmark( len, 'float32' );
 		bench( pkg+':len='+len+',dtype=float32', f );
 
+		f = createBenchmark( len, 'bool' );
+		bench( pkg+':len='+len+',dtype=bool', f );
+
 		f = createBenchmark( len, 'complex128' );
 		bench( pkg+':len='+len+',dtype=complex128', f );
 

lib/node_modules/@stdlib/array/convert/docs/repl.txt

@@ -2,21 +2,6 @@
 {{alias}}( arr, dtype )
     Converts an input array to an array of a different data type.
 
-    The function supports the following data types:
-
-    - float32: single-precision floating-point numbers.
-    - float64: double-precision floating-point numbers.
-    - complex64: single-precision complex floating-point numbers.
-    - complex128: double-precision complex floating-point numbers.
-    - generic: values of any type.
-    - int16: signed 16-bit integers.
-    - int32: signed 32-bit integers.
-    - int8: signed 8-bit integers.
-    - uint16: unsigned 16-bit integers.
-    - uint32: unsigned 32-bit integers.
-    - uint8: unsigned 8-bit integers.
-    - uint8c: unsigned clamped 8-bit integers.
-
     Parameters
     ----------
     arr: ArrayLikeObject

lib/node_modules/@stdlib/array/convert/docs/types/test.ts

@@ -34,6 +34,7 @@ import convert = require( './index' );
 	convert( [ 1.0, 2.0, 3.0, 4.0 ], 'uint8c' ); // $ExpectType Uint8ClampedArray
 	convert( [ 1.0, 2.0, 3.0, 4.0 ], 'complex128' ); // $ExpectType Complex128Array
 	convert( [ 1.0, 2.0, 3.0, 4.0 ], 'complex64' ); // $ExpectType Complex64Array
+	convert( [ 1.0, 2.0, 3.0, 4.0 ], 'bool' ); // $ExpectType BooleanArray
 	convert( [ 1.0, 2.0, 3.0, 4.0 ], 'generic' ); // $ExpectType number[]
 	convert( [ 'a', 'b', 'c', 'd' ], 'generic' ); // $ExpectType string[]
 }

lib/node_modules/@stdlib/array/convert/lib/main.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2018 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.
@@ -25,9 +25,11 @@ var getType = require( '@stdlib/array/dtype' );
 var ctors = require( '@stdlib/array/ctors' );
 var reinterpret128 = require( '@stdlib/strided/base/reinterpret-complex128' );
 var reinterpret64 = require( '@stdlib/strided/base/reinterpret-complex64' );
-var format = require( '@stdlib/string/format' );
+var reinterpretBoolean = require( '@stdlib/strided/base/reinterpret-boolean' );
 var gcopy = require( '@stdlib/blas/base/gcopy' );
 var copy = require( '@stdlib/array/base/copy' );
+var resolveGetter = require( '@stdlib/array/base/resolve-getter' );
+var format = require( '@stdlib/string/format' );
 
 
 // FUNCTIONS //
@@ -70,6 +72,25 @@ function isComplex128( dtype ) {
 	return ( dtype === 'complex128' );
 }
 
+/**
+* Tests whether a data type is a boolean data type.
+*
+* @private
+* @param {string} dtype - data type
+* @returns {boolean} boolean indicating whether a provided data type is a boolean data type
+*
+* @example
+* var bool = isBool( 'bool' );
+* // returns true
+*
+* @example
+* var bool = isBool( 'complex128' );
+* // returns false
+*/
+function isBool( dtype ) {
+	return ( dtype === 'bool' );
+}
+
 
 // MAIN //
 
@@ -93,9 +114,11 @@ function convert( x, dtype ) {
 	var ctor;
 	var xbuf;
 	var obuf;
+	var get;
 	var out;
 	var len;
 	var t;
+	var i;
 
 	if ( !isCollection( x ) ) {
 		throw new TypeError( format( 'invalid argument. First argument must be an array-like object. Value: `%s`.', x ) );
@@ -136,10 +159,47 @@ function convert( x, dtype ) {
 			gcopy( len*2, xbuf, 1, obuf, 1 );
 			return out;
 		}
+		// Check whether the output data type is a boolean data type...
+		if ( isBool( dtype ) ) { // cmplx => bool
+			obuf = reinterpretBoolean( out, 0 );
+			for ( i = 0; i < len; i++ ) {
+				// A complex number is only falsy when both the real and imaginary components are zero...
+				if ( xbuf[ 2*i ] || xbuf[ (2*i)+1 ] ) {
+					obuf[ i ] = 1;
+				} else {
+					obuf[ i ] = 0;
+				}
+			}
+			return out;
+		}
 		// We assume that the output data type is a real number data type, given that we're looking to convert a provided complex number array; in which case, we'll only extract the real components from the complex number input array...
 		gcopy( len, xbuf, 2, out, 1 ); // cmplx => real
 		return out;
 	}
+	// Check whether the input array is a boolean array...
+	if ( isBool( t ) ) {
+		xbuf = reinterpretBoolean( x, 0 );
+
+		// Check whether the output data type is a boolean data type...
+		if ( isBool( dtype ) ) { // bool => bool
+			obuf = reinterpretBoolean( out, 0 );
+			gcopy( len, xbuf, 1, obuf, 1 );
+			return out;
+		}
+		// Check whether the output data type is a complex number data type...
+		if ( isComplex64( dtype ) ) { // bool => cmplx
+			obuf = reinterpret64( out, 0 );
+			gcopy( len, xbuf, 1, obuf, 2 );
+			return out;
+		}
+		if ( isComplex128( dtype ) ) { // bool => cmplx
+			obuf = reinterpret128( out, 0 );
+			gcopy( len, xbuf, 1, obuf, 2 );
+			return out;
+		}
+		gcopy( len, xbuf, 1, out, 1 ); // bool => real
+		return out;
+	}
 	// Check whether we need to explicitly handle complex number output arrays...
 	isc64 = isComplex64( dtype );
 	if ( isc64 || isComplex128( dtype ) ) {
@@ -152,7 +212,20 @@ function convert( x, dtype ) {
 		gcopy( len, x, 1, obuf, 2 ); // real => cmplx
 		return out;
 	}
-	// At this point, we're no longer handling complex number arrays, so we'll just assume that we can perform a straightforward copy...
+	// Check whether the output data type is a boolean data type...
+	if ( isBool( dtype ) ) {
+		obuf = reinterpretBoolean( out, 0 );
+		get = resolveGetter( x );
+		for ( i = 0; i < len; i++ ) {
+			if ( get( x, i ) ) {
+				obuf[ i ] = 1;
+			} else {
+				obuf[ i ] = 0;
+			}
+		}
+		return out;
+	}
+	// At this point, we're no longer handling complex number or boolean arrays, so we'll just assume that we can perform a straightforward copy...
 	gcopy( len, x, 1, out, 1 ); // note: `gcopy` is assumed to support arrays using accessors
 	return out;
 }