Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2025-03-22)
+## Unreleased (2025-03-23)
 
 <section class="features">
 
@@ -32,6 +32,7 @@
 
 <details>
 
+-   [`5cab853`](https://github.com/stdlib-js/stdlib/commit/5cab853c4f710e60d7dc1639e0cb5e9f00ad2134) - **refactor:** update to enforce mostly safe casts _(by Athan Reines)_
 -   [`40fc3a2`](https://github.com/stdlib-js/stdlib/commit/40fc3a218445c34a667237cadb74ae9417cc0392) - **chore:** add TODO _(by Athan Reines)_
 -   [`1aca9d3`](https://github.com/stdlib-js/stdlib/commit/1aca9d37e47e33c03b94bb5b128647c7387172e2) - **fix:** update type defn _(by Athan Reines)_
 -   [`266a064`](https://github.com/stdlib-js/stdlib/commit/266a064a8cc55b100a00d2ad98c84820d8f17653) - **style:** fix spacing _(by Athan Reines)_

CONTRIBUTORS

@@ -3,6 +3,7 @@
 # Contributors listed in alphabetical order.
 
 Aadish Jain <[email protected]>
+Aarya Balwadkar <[email protected]>
 Aayush Khanna <[email protected]>
 Abdelrahman Samir <[email protected]>
 Abdul Kaium <[email protected]>
@@ -104,6 +105,7 @@ Ognjen Jevremović <[email protected]>
 Oneday12323 <[email protected]>
 Ori Miles <[email protected]>
 Philipp Burckhardt <[email protected]>
+Prajjwal Bajpai <[email protected]>
 Prajwal Kulkarni <[email protected]>
 Pranav Goswami <[email protected]>
 Pranjal Jha <[email protected]>

README.md

@@ -129,6 +129,7 @@ A provided ndarray should be an object with the following properties:
 ## Notes
 
 -   If `value` is a number and `x` has a complex [data type][@stdlib/ndarray/dtypes], the function fills an input ndarray with a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
+-   A `value` must be able to safely cast to the input ndarray [data type][@stdlib/ndarray/dtypes]. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a 'float32' input ndarray).
 -   The function **mutates** the input ndarray.
 
 </section>

dist/index.js

@@ -14,7 +14,11 @@
         Input ndarray-like object.
 
     value: any
-        Scalar value.
+        Scalar value. Must be able to safely cast to the input ndarray data
+        type. Scalar values having floating-point data types (both real and
+        complex) are allowed to downcast to a lower precision data type of the
+        same kind (e.g., a scalar double-precision floating-point number can be
+        used to fill a 'float32' input ndarray).
 
     Examples
     --------

dist/index.js.map

@@ -29,6 +29,7 @@ import { ComplexLike } from '@stdlib/types/complex';
 * ## Notes
 *
 * -   If `value` is a number, the function fills an input ndarray with a complex number whose real component equals the provided scalar value and whose imaginary component is zero.
+* -   A `value` must be able to safely cast to the input ndarray data type. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a 'float32' input ndarray).
 *
 * @param x - input ndarray
 * @param value - scalar value
@@ -68,6 +69,10 @@ declare function fill( x: complexndarray, value: number | ComplexLike ): void;
 /**
 * Fills an input ndarray with a specified value.
 *
+* ## Notes
+*
+* -   A `value` must be able to safely cast to the input ndarray data type. Scalar values having floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the same kind (e.g., a scalar double-precision floating-point number can be used to fill a 'float32' input ndarray).
+*
 * @param x - input ndarray
 * @param value - scalar value
 *

docs/repl.txt

@@ -20,11 +20,13 @@
 
 // MODULES //
 
+var isScalarMostlySafeCompatible = require( '@stdlib/ndarray-base-assert-is-scalar-mostly-safe-compatible' ); // eslint-disable-line id-length
 var broadcastScalar = require( '@stdlib/ndarray-base-broadcast-scalar' );
 var getDtype = require( '@stdlib/ndarray-base-dtype' );
 var getShape = require( '@stdlib/ndarray-base-shape' );
 var getOrder = require( '@stdlib/ndarray-base-order' );
 var assign = require( '@stdlib/ndarray-base-assign' );
+var format = require( '@stdlib/string-format' );
 
 
 // MAIN //
@@ -40,6 +42,7 @@ var assign = require( '@stdlib/ndarray-base-assign' );
 * @param {NonNegativeInteger} x.offset - index offset
 * @param {string} x.order - specifies whether `x` is row-major (C-style) or column-major (Fortran-style)
 * @param {*} value - scalar value
+* @throws {TypeError} second argument cannot be safely cast to the input array data type
 * @returns {void}
 *
 * @example
@@ -73,10 +76,17 @@ var assign = require( '@stdlib/ndarray-base-assign' );
 * // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
 */
 function fill( x, value ) {
+	var dt;
 	var v;
 
+	dt = getDtype( x );
+
+	// Safe casts are always allowed and allow same kind casts (i.e., downcasts) only when the output data type is floating-point...
+	if ( !isScalarMostlySafeCompatible( value, dt ) ) {
+		throw new TypeError( format( 'invalid argument. The second argument cannot be safely cast to the input array data type. Data type: %s. Value: `%s`.', dt, value ) );
+	}
 	// Broadcast the fill value to an ndarray of same shape and data type as the input ndarray:
-	v = broadcastScalar( value, getDtype( x ), getShape( x ), getOrder( x ) );
+	v = broadcastScalar( value, dt, getShape( x ), getOrder( x ) );
 
 	// Assign the fill value to each element of the input ndarray:
 	assign( [ v, x ] ); // TODO: consider replacing with ndarray/base/assign-scalar in order to avoid zero-dimensional ndarray creation and subsequent broadcasting

docs/types/index.d.ts

@@ -37,12 +37,15 @@
     "url": "https://github.com/stdlib-js/stdlib/issues"
   },
   "dependencies": {
+    "@stdlib/ndarray-base-assert-is-scalar-mostly-safe-compatible": "github:stdlib-js/ndarray-base-assert-is-scalar-mostly-safe-compatible#main",
     "@stdlib/ndarray-base-assign": "^0.1.1",
     "@stdlib/ndarray-base-broadcast-scalar": "^0.2.2",
     "@stdlib/ndarray-base-dtype": "^0.2.2",
     "@stdlib/ndarray-base-order": "^0.2.2",
     "@stdlib/ndarray-base-shape": "^0.2.2",
-    "@stdlib/types": "^0.4.3"
+    "@stdlib/string-format": "^0.2.2",
+    "@stdlib/types": "^0.4.3",
+    "@stdlib/error-tools-fmtprodmsg": "^0.2.2"
   },
   "devDependencies": {
     "@stdlib/array-complex128": "^0.3.0",

lib/main.js

@@ -43,6 +43,39 @@ tape( 'main export is a function', function test( t ) {
 	t.end();
 });
 
+tape( 'the function throws an error if provided a second argument which cannot be safely cast to the input ndarray data type', function test( t ) {
+	var values;
+	var x;
+	var i;
+
+	x = scalar2ndarray( 0.0, {
+		'dtype': 'int32'
+	});
+
+	values = [
+		'5',
+		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() {
+			fill( x, value );
+		};
+	}
+});
+
 tape( 'the function fills a 0-dimensional input ndarray with a specified value', function test( t ) {
 	var expected;
 	var x;