refactor: enforce mostly safe casts

This commit updates documentation and tests to match the "base"
implementation `ndarray/base/fill`.

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/ndarray/fill/README.md

@@ -73,6 +73,7 @@ The function accepts the following arguments:
 
 -   An input [`ndarray`][@stdlib/ndarray/ctor] **must** be writable. If provided a **read-only** [`ndarray`][@stdlib/ndarray/ctor], the function throws an error.
 -   If `value` is a number and `x` has a complex [data type][@stdlib/ndarray/dtypes], the function fills an input [`ndarray`][@stdlib/ndarray/ctor] 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`][@stdlib/ndarray/ctor] [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`][@stdlib/ndarray/ctor]).
 -   The function **mutates** the input [`ndarray`][@stdlib/ndarray/ctor].
 
 </section>

lib/node_modules/@stdlib/ndarray/fill/docs/repl.txt

@@ -14,7 +14,11 @@
         Input ndarray.
 
     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).
 
     Returns
     -------

lib/node_modules/@stdlib/ndarray/fill/docs/types/index.d.ts

@@ -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
@@ -52,6 +53,10 @@ declare function fill<T extends complexndarray>( x: T, value: number | ComplexLi
 /**
 * 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
 * @returns input ndarray
@@ -74,6 +79,10 @@ declare function fill<T = unknown, U extends genericndarray<T> = genericndarray<
 /**
 * 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
 * @returns input ndarray

lib/node_modules/@stdlib/ndarray/fill/lib/main.js

@@ -34,6 +34,7 @@ var format = require( '@stdlib/string/format' );
 * @param {ndarray} x - input ndarray
 * @param {*} value - scalar value
 * @throws {TypeError} first argument must be an ndarray-like object
+* @throws {TypeError} second argument cannot be safely cast to the input ndarray data type
 * @throws {Error} cannot write to a read-only ndarray
 * @returns {ndarray} input ndarray
 *

lib/node_modules/@stdlib/ndarray/fill/test/test.js

@@ -86,6 +86,39 @@ tape( 'the function throws an error if provided a first argument which is a read
 	}
 });
 
+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;