Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Features
 
+-   [`709563c`](https://github.com/stdlib-js/stdlib/commit/709563c0d7337b5c0632d1988fb263cf39305f86) - update `ndarray/base` TypeScript declarations [(#9716)](https://github.com/stdlib-js/stdlib/pull/9716)
 -   [`f738a37`](https://github.com/stdlib-js/stdlib/commit/f738a37c1cc32a740c7ecc4cbc7982eca26f67d2) - add `ternaryBlockSize` to namespace
 -   [`b490370`](https://github.com/stdlib-js/stdlib/commit/b49037059ac498f7e864cb83f0cf59b3feb3b459) - add `ternaryLoopOrder` to namespace
 -   [`88e4096`](https://github.com/stdlib-js/stdlib/commit/88e4096e8e5941fecc15ef2fd2d5b27e91d69233) - add `ternary` to namespace
@@ -708,6 +709,7 @@ A total of 40 issues were closed in this release:
 
 <details>
 
+-   [`709563c`](https://github.com/stdlib-js/stdlib/commit/709563c0d7337b5c0632d1988fb263cf39305f86) - **feat:** update `ndarray/base` TypeScript declarations [(#9716)](https://github.com/stdlib-js/stdlib/pull/9716) _(by stdlib-bot)_
 -   [`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)_

base/docs/types/index.d.ts

@@ -147,6 +147,10 @@ import strides = require( './../../../base/strides' );
 import strides2offset = require( './../../../base/strides2offset' );
 import strides2order = require( './../../../base/strides2order' );
 import sub2ind = require( './../../../base/sub2ind' );
+import ternary = require( './../../../base/ternary' );
+import ternaryLoopOrder = require( './../../../base/ternary-loop-interchange-order' );
+import ternaryOutputDataType = require( './../../../base/ternary-output-dtype' );
+import ternaryBlockSize = require( './../../../base/ternary-tiling-block-size' );
 import ndarray2array = require( './../../../base/to-array' );
 import toFlippedlr = require( './../../../base/to-flippedlr' );
 import toFlippedud = require( './../../../base/to-flippedud' );
@@ -1644,6 +1648,7 @@ interface Namespace {
 	* @param x - input ndarray
 	* @param fcn - callback function
 	* @param thisArg - callback function execution context
+	* @returns input ndarray
 	*
 	* @example
 	* var Float64Array = require( '@stdlib/array/float64' );
@@ -1674,10 +1679,13 @@ interface Namespace {
 	*     'order': 'row-major'
 	* };
 	*
-	* ns.fillBy( x, fcn );
+	* var out = ns.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
 	*/
 	fillBy: typeof fillBy;
 
@@ -4073,6 +4081,141 @@ interface Namespace {
 	*/
 	sub2ind: typeof sub2ind;
 
+	/**
+	* Applies a ternary callback to elements in input ndarrays and assigns results to elements in an output ndarray.
+	*
+	* @param arrays - array-like object containing three input ndarrays and one output ndarray
+	* @param fcn - ternary callback
+	* @throws arrays must have the same number of dimensions
+	* @throws arrays must have the same shape
+	*
+	* @example
+	* var Float64Array = require( '@stdlib/array/float64' );
+	* var ndarray = require( './../../../ctor' );
+	* var getData = require( './../../../data-buffer' );
+	* var add3 = require( '@stdlib/number/float64/base/add3' );
+	*
+	* // Create data buffers:
+	* var xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+	* var ybuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+	* var zbuf = new Float64Array( [ 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] );
+	* var wbuf = new Float64Array( 6 );
+	*
+	* // Define the shape of the input and output arrays:
+	* var shape = [ 3, 1, 2 ];
+	*
+	* // Define the array strides:
+	* var sx = [ 2, 2, 1 ];
+	* var sy = [ 2, 2, 1 ];
+	* var sz = [ 2, 2, 1 ];
+	* var sw = [ 2, 2, 1 ];
+	*
+	* // Define the index offsets:
+	* var ox = 0;
+	* var oy = 0;
+	* var oz = 0;
+	* var ow = 0;
+	*
+	* // Create the input and output ndarrays:
+	* var x = new ndarray( 'float64', xbuf, shape, sx, ox, 'row-major' );
+	* var y = new ndarray( 'float64', ybuf, shape, sy, oy, 'row-major' );
+	* var z = new ndarray( 'float64', zbuf, shape, sz, oz, 'row-major' );
+	* var w = new ndarray( 'float64', wbuf, shape, sw, ow, 'row-major' );
+	*
+	* // Apply the ns.ternary function:
+	* ns.ternary( [ x, y, z, w ], add3 );
+	*
+	* console.log( getData( w ) );
+	* // => <Float64Array>[ 2.5, 4.5, 6.5, 8.5, 10.5, 12.5 ]
+	*/
+	ternary: typeof ternary;
+
+	/**
+	* Reorders ndarray dimensions and associated strides for loop interchange.
+	*
+	* ## Notes
+	*
+	* -   The returned object has the following properties:
+	*
+	*     -   **sh**: dimensions sorted in loop order.
+	*     -   **sx**: first input ndarray strides sorted in loop order.
+	*     -   **sy**: second input ndarray strides sorted in loop order.
+	*     -   **sz**: third input ndarray strides sorted in loop order.
+	*     -   **sw**: output ndarray strides sorted in loop order.
+	*
+	* -   When iterating over the elements of a multi-dimensional array, accessing elements which are closer in memory can improve performance. To this end, loop interchange is a technique used in loop nest optimization to improve locality of reference and take advantage of CPU cache.
+	*
+	*     The purpose of this function is to order ndarray dimensions according to the magnitude of array strides. By using the ordered dimensions and associated strides, one can construct nested loops (one for each dimension) such that the innermost loop iterates over the dimension in which array elements are closest in memory and the outermost loop iterates over the dimension in which array elements are farthest apart in memory. As a consequence, element iteration is optimized to minimize cache misses and ensure locality of reference.
+	*
+	* -   Cache performance may be degraded if the layout order (i.e., row-major or column-major) differs for the input and output ndarrays. This function is intended to optimize cache performance for the most common layout order. Accordingly, if the output ndarray has a different layout order (e.g., if the input ndarrays are row-major and the output ndarray is column-major), cache misses are likely for the output ndarray. In general, to ensure best performance, input and output ndarrays should have the same layout order.
+	*
+	* -   The function assumes that the input and output ndarrays have the same shape. Hence, loop interchange order should only be determined **after** broadcasting.
+	*
+	* @param shape - array dimensions
+	* @param stridesX - first input array stride lengths
+	* @param stridesY - second input array stride lengths
+	* @param stridesZ - third input array stride lengths
+	* @param stridesW - output array stride lengths
+	* @returns loop interchange data
+	*
+	* @example
+	* var sh = [ 2, 3, 4 ];
+	*
+	* var sx = [ 12, 4, 1 ]; // row-major
+	* var sy = [ 24, 8, 1 ]; // row-major
+	* var sz = [ 1, 4, 12 ]; // column-major
+	* var sw = [ 1, -2, 6 ]; // column-major
+	*
+	* var o = ns.ternaryLoopOrder( sh, sx, sy, sz, sw );
+	* // returns {...}
+	*
+	* var ssh = o.sh;
+	* // returns [ 2, 3, 4 ]
+	*
+	* var ssx = o.sx;
+	* // returns [ 12, 4, 1 ]
+	*
+	* var ssy = o.sy;
+	* // returns [ 24, 8, 1 ]
+	*
+	* var ssz = o.sz;
+	* // returns [ 1, 4, 12 ]
+	*
+	* var ssw = o.sw;
+	* // returns [ 1, -2, 6 ]
+	*/
+	ternaryLoopOrder: typeof ternaryLoopOrder;
+
+	/**
+	* Resolves the output ndarray data type for a ternary function.
+	*
+	* @param xdtype - first input ndarray data type
+	* @param ydtype - second input ndarray data type
+	* @param zdtype - third input ndarray data type
+	* @param policy - output ndarray data type policy
+	* @returns output ndarray data type
+	*
+	* @example
+	* var dt = ns.ternaryOutputDataType( 'float64', 'float32', 'float32', 'complex_floating_point' );
+	* // returns <DataType>
+	*/
+	ternaryOutputDataType: typeof ternaryOutputDataType;
+
+	/**
+	* Returns a loop block size for multi-dimensional array tiled loops.
+	*
+	* @param dtypeX - first input array data type
+	* @param dtypeY - second input array data type
+	* @param dtypeZ - third input array data type
+	* @param dtypeW - output array data type
+	* @returns block size (in units of elements)
+	*
+	* @example
+	* var bsize = ns.ternaryBlockSize( 'float64', 'float64', 'float64', 'float64' );
+	* // returns <number>
+	*/
+	ternaryBlockSize: typeof ternaryBlockSize;
+
 	/**
 	* Converts an ndarray buffer to a generic array (which may include nested arrays).
 	*