Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2026-01-12)
+## Unreleased (2026-01-13)
 
 <section class="features">
 
@@ -708,6 +708,9 @@ A total of 40 issues were closed in this release:
 
 <details>
 
+-   [`6aee8e2`](https://github.com/stdlib-js/stdlib/commit/6aee8e232a2cebd57d5246d76ffe08e67941c0a4) - **docs:** move content to notes _(by Athan Reines)_
+-   [`93e0c79`](https://github.com/stdlib-js/stdlib/commit/93e0c79faa246da751b6d7a640b5133fefad00f2) - **refactor:** return the input ndarray and update examples _(by Athan Reines)_
+-   [`d5ddfc7`](https://github.com/stdlib-js/stdlib/commit/d5ddfc76b9363a57791e018c8435c33dd18a9bee) - **style:** remove empty line _(by Athan Reines)_
 -   [`afa33d2`](https://github.com/stdlib-js/stdlib/commit/afa33d21dadcaf449b9950ea9ec30a12f4596738) - **docs:** update examples [(#9700)](https://github.com/stdlib-js/stdlib/pull/9700) _(by stdlib-bot)_
 -   [`fdfdf13`](https://github.com/stdlib-js/stdlib/commit/fdfdf139a4f787dd67d5cdcf94130bf6469c92a2) - **docs:** fix example to ensure valid type promotion _(by Athan Reines)_
 -   [`f738a37`](https://github.com/stdlib-js/stdlib/commit/f738a37c1cc32a740c7ecc4cbc7982eca26f67d2) - **feat:** add `ternaryBlockSize` to namespace _(by Athan Reines)_

base/fill-by/README.md

@@ -41,38 +41,20 @@ var fillBy = require( '@stdlib/ndarray/base/fill-by' );
 Fills an input ndarray according to a callback function.
 
 ```javascript
-var Float64Array = require( '@stdlib/array/float64' );
+var array = require( '@stdlib/ndarray/array' );
 
-function fcn( value ) {
-    return value * 10.0;
+function fcn() {
+    return 10.0;
 }
 
-// Create a data buffer:
-var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
-
-// Define the shape of the input array:
-var shape = [ 3, 1, 2 ];
-
-// 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'
-};
+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 ] ] ]
 
-fillBy( x, fcn );
+var out = fillBy( x, fcn );
+// returns <ndarray>[ [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ], [ [ 10.0, 10.0 ] ] ]
 
-console.log( x.data );
-// => <Float64Array>[ 10.0, 20.0, 30.0, 40.0, 50.0, 60.0 ]
+var bool = ( out === x );
+// returns true
 ```
 
 The function accepts the following arguments:
@@ -86,57 +68,25 @@ To set the callback function execution context, provide a `thisArg`.
 <!-- eslint-disable no-invalid-this -->
 
 ```javascript
-var Float64Array = require( '@stdlib/array/float64' );
+var array = require( '@stdlib/ndarray/array' );
 
 function fcn( value ) {
-    return value * this.factor;
+    return value * 10.0;
 }
 
-// Create a data buffer:
-var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
-
-// Define the shape of the input array:
-var shape = [ 3, 1, 2 ];
-
-// 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'
-};
+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 ] ] ]
 
 var ctx = {
     'factor': 10.0
 };
-fillBy( x, fcn, ctx );
-
-console.log( x.data );
-// => <Float64Array>[ 10.0, 20.0, 30.0, 40.0, 50.0, 60.0 ]
-```
 
-A provided ndarray should be an object with the following properties:
+var out = fillBy( x, fcn, ctx );
+// returns <ndarray>[ [ [ 10.0, 20.0 ] ], [ [ 30.0, 40.0 ] ], [ [ 50.0, 60.0 ] ] ]
 
--   **dtype**: data type.
--   **data**: data buffer.
--   **shape**: dimensions.
--   **strides**: stride lengths.
--   **offset**: index offset.
--   **order**: specifies whether an ndarray is row-major (C-style) or column major (Fortran-style).
-
-The callback function is provided the following arguments:
-
--   **value**: current array element.
--   **indices**: current array element indices.
--   **arr**: the input ndarray.
+var bool = ( out === x );
+// returns true
+```
 
 </section>
 
@@ -146,7 +96,23 @@ The callback function is provided the following arguments:
 
 ## Notes
 
+-   A provided ndarray should be an object with the following properties:
+
+    -   **dtype**: data type.
+    -   **data**: data buffer.
+    -   **shape**: dimensions.
+    -   **strides**: stride lengths.
+    -   **offset**: index offset.
+    -   **order**: specifies whether an ndarray is row-major (C-style) or column major (Fortran-style).
+
+-   The callback function is provided the following arguments:
+
+    -   **value**: current array element.
+    -   **indices**: current array element indices.
+    -   **arr**: the input ndarray.
+
 -   The function **mutates** the input ndarray.
+
 -   The function assumes that each element in the underlying input ndarray data buffer has one, and only one, corresponding element in input ndarray view (i.e., a provided ndarray is not a broadcasted ndarray view).
 
 </section>

base/fill-by/docs/repl.txt

@@ -17,30 +17,28 @@
     Parameters
     ----------
     x: ndarrayLike
-        Input ndarray-like object.
+        Input ndarray.
 
     fcn: Function
         Callback function.
 
     thisArg: any (optional)
         Callback function execution context.
 
+    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
     > function fcn() { return 10.0; };
-    > {{alias}}( x, fcn );
-    > x.get( 0, 0 )
-    10.0
-    > x.get( 0, 1 )
-    10.0
-    > x.get( 1, 0 )
-    10.0
-    > x.get( 1, 1 )
-    10.0
+    > var out = {{alias}}( x, fcn )
+    <ndarray>[ [ 10.0, 10.0 ], [ 10.0, 10.0 ] ]
+    > var bool = ( out === x )
+    true
 
     See Also
     --------

base/fill-by/docs/types/index.d.ts

@@ -72,6 +72,7 @@ type Callback<T, U, V, ThisArg> = Nullary<U, ThisArg> | Unary<T, U, ThisArg> | B
 * @param x - input ndarray
 * @param fcn - callback function
 * @param thisArg - callback function execution context
+* @returns input ndarray
 *
 * @example
 * var Complex128Array = require( '@stdlib/array/complex128' );
@@ -103,19 +104,23 @@ type Callback<T, U, V, ThisArg> = Nullary<U, ThisArg> | Unary<T, U, ThisArg> | B
 *     'order': 'row-major'
 * };
 *
-* fillBy( x, fcn );
+* var out = fillBy( x, fcn );
 *
 * 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 fillBy<T = unknown, U = unknown, V extends complexndarray = complexndarray, ThisArg = unknown>( x: V, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): void;
+declare function fillBy<T = unknown, U = unknown, V extends complexndarray = complexndarray, ThisArg = unknown>( x: V, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): V;
 
 /**
 * Fills an input ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
 * @param thisArg - callback function execution context
+* @returns input ndarray
 *
 * @example
 * var Float64Array = require( '@stdlib/array/float64' );
@@ -146,12 +151,15 @@ declare function fillBy<T = unknown, U = unknown, V extends complexndarray = com
 *     'order': 'row-major'
 * };
 *
-* fillBy( x, fcn );
+* var out = fillBy( x, fcn );
 *
 * 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 fillBy<T = unknown, U = unknown, V extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( x: V, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): void;
+declare function fillBy<T = unknown, U = unknown, V extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( x: V, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): V;
 
 
 // EXPORTS //

base/fill-by/docs/types/test.ts

@@ -46,13 +46,13 @@ function fcn2(): ComplexLike {
 
 // The function returns `undefined`...
 {
-	fillBy( zeros( 'float64', [ 2, 2 ], 'row-major' ), fcn1 ); // $ExpectType void
-	fillBy( zeros( 'complex128', [ 2, 2 ], 'row-major' ), fcn2 ); // $ExpectType void
-	fillBy( zeros( 'generic', [ 2, 2 ], 'row-major' ), fcn1 ); // $ExpectType void
+	fillBy( zeros( 'float64', [ 2, 2 ], 'row-major' ), fcn1 ); // $ExpectType float64ndarray
+	fillBy( zeros( 'complex128', [ 2, 2 ], 'row-major' ), fcn2 ); // $ExpectType complex128ndarray
+	fillBy( zeros( 'generic', [ 2, 2 ], 'row-major' ), fcn1 ); // $ExpectType genericndarray<number>
 
-	fillBy( zeros( 'float64', [ 2, 2 ], 'row-major' ), fcn1, {} ); // $ExpectType void
-	fillBy( zeros( 'complex128', [ 2, 2 ], 'row-major' ), fcn2, {} ); // $ExpectType void
-	fillBy( zeros( 'generic', [ 2, 2 ], 'row-major' ), fcn1, {} ); // $ExpectType void
+	fillBy( zeros( 'float64', [ 2, 2 ], 'row-major' ), fcn1, {} ); // $ExpectType float64ndarray
+	fillBy( zeros( 'complex128', [ 2, 2 ], 'row-major' ), fcn2, {} ); // $ExpectType complex128ndarray
+	fillBy( zeros( 'generic', [ 2, 2 ], 'row-major' ), fcn1, {} ); // $ExpectType genericndarray<number>
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an ndarray-like object...

base/fill-by/lib/index.js

@@ -24,39 +24,21 @@
 * @module @stdlib/ndarray/base/fill-by
 *
 * @example
-* var Float64Array = require( '@stdlib/array/float64' );
+* var array = require( '@stdlib/ndarray/array' );
 * var fillBy = require( '@stdlib/ndarray/base/fill-by' );
 *
 * function fcn() {
 *     return 10.0;
 * }
 *
-* // 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 = fillBy( x, fcn );
+* // 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'
-* };
-*
-* fillBy( x, fcn );
-*
-* console.log( x.data );
-* // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+* var bool = ( out === x );
+* // returns true
 */
 
 // MODULES //

base/fill-by/lib/main.js

@@ -28,53 +28,30 @@ var map = require( './../../../base/map' );
 /**
 * Fills an input ndarray according to a callback function.
 *
-* @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 {Function} fcn - callback function
 * @param {*} [thisArg] - callback function execution context
-* @returns {void}
+* @returns {ndarrayLike} input ndarray
 *
 * @example
-* var Float64Array = require( '@stdlib/array/float64' );
+* var array = require( '@stdlib/ndarray/array' );
 *
 * function fcn() {
 *     return 10.0;
 * }
 *
-* // 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 = fillBy( x, fcn );
+* // 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'
-* };
-*
-* fillBy( x, fcn );
-*
-* console.log( x.data );
-* // => <Float64Array>[ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ]
+* var bool = ( out === x );
+* // returns true
 */
 function fillBy( x, fcn, thisArg ) {
 	map( [ x, x ], fcn, thisArg );
+	return x;
 }