refactor: update examples and return the input ndarray

kgryte · kgryte · commit 16ce439eb07c · 2025-12-29T17:18:11.000-08:00
---
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: passed
  - 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: passed
  - task: lint_license_headers
    status: passed
---
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/README.md b/lib/node_modules/@stdlib/ndarray/base/fill/README.md
@@ -43,39 +43,21 @@ Fills an input ndarray with a specified value.
 <!-- eslint-disable max-len -->
 
 ```javascript
-var Float64Array = require( '@stdlib/array/float64' );
+var array = require( '@stdlib/ndarray/array' );
 
-// Create a data buffer:
-var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
+// returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ]
 
-// Define the shape of the input array:
-var shape = [ 3, 1, 2 ];
+var out = fill( x, 10.0 );
+// returns <ndarray>[ [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ] ]
 
-// Define the array strides:
-var sx = [ 2, 2, 1 ];
-
-// Define the index offset:
-var ox = 0;
-
-// Create the input ndarray-like object:
-var x = {
-    'dtype': 'float64',
-    'data': xbuf,
-    'shape': shape,
-    'strides': sx,
-    'offset': ox,
-    'order': 'row-major'
-};
-
-fill( x, 10.0 );
-
-console.log( x.data );
-// => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+var bool = ( out === x );
+// returns true
 ```
 
 The function accepts the following arguments:
 
--   **x**: array-like object containing an input ndarray.
+-   **x**: input ndarray.
 -   **value**: scalar value.
 
 A provided ndarray should be an object with the following properties:
@@ -110,22 +92,17 @@ A provided ndarray should be an object with the following properties:
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
-var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var fill = require( '@stdlib/ndarray/base/fill' );
 
-var x = {
-    'dtype': 'generic',
-    'data': filledarrayBy( 10, 'generic', discreteUniform( -100, 100 ) ),
-    'shape': [ 5, 2 ],
-    'strides': [ 2, 1 ],
-    'offset': 0,
-    'order': 'row-major'
-};
+var x = discreteUniform( [ 5, 2 ], -100, 100, {
+    'dtype': 'generic'
+});
+console.log( ndarray2array( x ) );
 
 fill( x, 10.0 );
-console.log( ndarray2array( x.data, x.shape, x.strides, x.offset, x.order ) );
+console.log( ndarray2array( x ) );
 ```
 
 </section>
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/base/fill/docs/repl.txt
@@ -11,7 +11,7 @@
     Parameters
     ----------
     x: ndarrayLike
-        Input ndarray-like object.
+        Input ndarray.
 
     value: any
         Scalar value. Must be able to safely cast to the input ndarray data
@@ -20,15 +20,20 @@
         same kind (e.g., a scalar double-precision floating-point number can be
         used to fill a 'float32' input ndarray).
 
+
+    Returns
+    -------
+    out: ndarrayLike
+        Input ndarray.
+
     Examples
     --------
     > var opts = { 'dtype': 'float64' };
     > var x = {{alias:@stdlib/ndarray/zeros}}( [ 2, 2 ], opts );
-    > x.get( 0, 0 )
-    0.0
-    > {{alias}}( x, 10.0 );
-    > x.get( 0, 0 )
-    10.0
+    > var out = {{alias}}( x, 10.0 )
+    <ndarray>[ [ 10.0, 10.0 ], [ 10.0, 10.0 ] ]
+    > var bool = ( out === x )
+    true
 
     See Also
     --------
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/fill/docs/types/index.d.ts
@@ -23,6 +23,11 @@
 import { typedndarray, complexndarray, genericndarray } from '@stdlib/types/ndarray';
 import { ComplexLike } from '@stdlib/types/complex';
 
+/**
+* Input ndarray.
+*/
+type InputArray<T> = typedndarray<T> | genericndarray<T>;
+
 /**
 * Fills an input ndarray with a specified value.
 *
@@ -33,6 +38,7 @@ import { ComplexLike } from '@stdlib/types/complex';
 *
 * @param x - input ndarray
 * @param value - scalar value
+* @returns input ndarray
 *
 * @example
 * var Complex128Array = require( '@stdlib/array/complex128' );
@@ -51,20 +57,23 @@ import { ComplexLike } from '@stdlib/types/complex';
 *
 * // Create the input ndarray-like object:
 * var x = {
-*     'dtype': 'float64',
+*     'dtype': 'complex128',
 *     'data': xbuf,
 *     'shape': shape,
 *     'strides': sx,
 *     'offset': ox,
 *     'order': 'row-major'
 * };
 *
-* fill( x, 10.0 );
+* var out = fill( x, 10.0 );
 *
 * console.log( x.data );
 * // => <Complex128Array>[ 10.0, 0.0, 10.0, 0.0, 10.0, 0.0, 10.0, 0.0, 10.0, 0.0, 10.0, 0.0 ]
+*
+* var bool = ( out === x );
+* // returns true
 */
-declare function fill( x: complexndarray, value: number | ComplexLike ): void;
+declare function fill<T extends complexndarray = complexndarray>( x: T, value: number | ComplexLike ): T;
 
 /**
 * Fills an input ndarray with a specified value.
@@ -75,6 +84,7 @@ declare function fill( x: complexndarray, value: number | ComplexLike ): void;
 *
 * @param x - input ndarray
 * @param value - scalar value
+* @returns input ndarray
 *
 * @example
 * var Float64Array = require( '@stdlib/array/float64' );
@@ -101,12 +111,15 @@ declare function fill( x: complexndarray, value: number | ComplexLike ): void;
 *     'order': 'row-major'
 * };
 *
-* fill( x, 10.0 );
+* var out = fill( x, 10.0 );
 *
 * console.log( x.data );
 * // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+*
+* var bool = ( out === x );
+* // returns true
 */
-declare function fill<T = unknown>( x: typedndarray<T> | genericndarray<T>, value: T ): void;
+declare function fill<T = unknown, U extends InputArray<T> = InputArray<T>>( x: U, value: T ): U;
 
 
 // EXPORTS //
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/base/fill/docs/types/test.ts
@@ -22,14 +22,13 @@ import fill = require( './index' );
 
 // TESTS //
 
-// The function returns `undefined`...
+// The function returns an ndarray...
 {
-	fill( zeros( 'float64', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType void
-	fill( zeros( 'complex128', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType void
-	fill( zeros( 'complex128', [ 2, 2 ], 'row-major' ), { 're': 10.0, 'im': 10.0 } ); // $ExpectType void
+	fill( zeros( 'float64', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType float64ndarray
+	fill( zeros( 'complex128', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType complex128ndarray
+	fill( zeros( 'complex128', [ 2, 2 ], 'row-major' ), { 're': 10.0, 'im': 10.0 } ); // $ExpectType complex128ndarray
 
-	fill( zeros( 'generic', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType void
-	fill<number | string>( zeros( 'generic', [ 2, 2 ], 'row-major' ), 'beep' ); // $ExpectType void
+	fill( zeros( 'generic', [ 2, 2 ], 'row-major' ), 10.0 ); // $ExpectType genericndarray<number>
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an ndarray-like object...
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/examples/index.js b/lib/node_modules/@stdlib/ndarray/base/fill/examples/index.js
@@ -18,19 +18,14 @@
 
 'use strict';
 
-var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
-var filledarrayBy = require( '@stdlib/array/filled-by' );
-var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+var discreteUniform = require( '@stdlib/random/discrete-uniform' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var fill = require( './../lib' );
 
-var x = {
-	'dtype': 'generic',
-	'data': filledarrayBy( 10, 'generic', discreteUniform( -100, 100 ) ),
-	'shape': [ 5, 2 ],
-	'strides': [ 2, 1 ],
-	'offset': 0,
-	'order': 'row-major'
-};
+var x = discreteUniform( [ 5, 2 ], -100, 100, {
+	'dtype': 'generic'
+});
+console.log( ndarray2array( x ) );
 
 fill( x, 10.0 );
-console.log( ndarray2array( x.data, x.shape, x.strides, x.offset, x.order ) );
+console.log( ndarray2array( x ) );
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/lib/index.js b/lib/node_modules/@stdlib/ndarray/base/fill/lib/index.js
@@ -24,35 +24,17 @@
 * @module @stdlib/ndarray/base/fill
 *
 * @example
-* var Float64Array = require( '@stdlib/array/float64' );
+* var array = require( '@stdlib/ndarray/array' );
 * var fill = require( '@stdlib/ndarray/base/fill' );
 *
-* // Create a data buffer:
-* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+* var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
+* // returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ]
 *
-* // Define the shape of the input array:
-* var shape = [ 3, 1, 2 ];
+* var out = fill( x, 10.0 );
+* // returns <ndarray>[ [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ] ]
 *
-* // Define the array strides:
-* var sx = [ 2, 2, 1 ];
-*
-* // Define the index offset:
-* var ox = 0;
-*
-* // Create the input ndarray-like object:
-* var x = {
-*     'dtype': 'float64',
-*     'data': xbuf,
-*     'shape': shape,
-*     'strides': sx,
-*     'offset': ox,
-*     'order': 'row-major'
-* };
-*
-* fill( x, 10.0 );
-*
-* console.log( x.data );
-* // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+* var bool = ( out === x );
+* // returns true
 */
 
 // MODULES //
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/lib/main.js b/lib/node_modules/@stdlib/ndarray/base/fill/lib/main.js
@@ -22,7 +22,7 @@
 
 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 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' );
@@ -34,52 +34,28 @@ var format = require( '@stdlib/string/format' );
 /**
 * Fills an input ndarray with a specified value.
 *
-* @param {ndarrayLike} x - ndarray-like object
-* @param {string} x.dtype - data type
-* @param {Collection} x.data - data buffer
-* @param {NonNegativeIntegerArray} x.shape - dimensions
-* @param {IntegerArray} x.strides - stride lengths
-* @param {NonNegativeInteger} x.offset - index offset
-* @param {string} x.order - specifies whether `x` is row-major (C-style) or column-major (Fortran-style)
+* @param {ndarrayLike} x - input ndarray
 * @param {*} value - scalar value
 * @throws {TypeError} second argument cannot be safely cast to the input array data type
-* @returns {void}
+* @returns {ndarrayLike} input ndarray
 *
 * @example
-* var Float64Array = require( '@stdlib/array/float64' );
+* var array = require( '@stdlib/ndarray/array' );
 *
-* // Create a data buffer:
-* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+* var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
+* // returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ]
 *
-* // Define the shape of the input array:
-* var shape = [ 3, 1, 2 ];
+* var out = fill( x, 10.0 );
+* // returns <ndarray>[ [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ] ]
 *
-* // Define the array strides:
-* var sx = [ 2, 2, 1 ];
-*
-* // Define the index offset:
-* var ox = 0;
-*
-* // Create the input ndarray-like object:
-* var x = {
-*     'dtype': 'float64',
-*     'data': xbuf,
-*     'shape': shape,
-*     'strides': sx,
-*     'offset': ox,
-*     'order': 'row-major'
-* };
-*
-* fill( x, 10.0 );
-*
-* console.log( x.data );
-* // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+* var bool = ( out === x );
+* // returns true
 */
 function fill( x, value ) {
 	var dt;
 	var v;
 
-	dt = getDtype( x );
+	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 ) ) {
@@ -90,6 +66,8 @@ function fill( x, value ) {
 
 	// 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
+
+	return x;
 }
 
 
diff --git a/lib/node_modules/@stdlib/ndarray/base/fill/test/test.js b/lib/node_modules/@stdlib/ndarray/base/fill/test/test.js
