feat!: update ndarray/base TypeScript declarations

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

@@ -95,6 +95,7 @@ import loopOrder = require( '@stdlib/ndarray/base/loop-interchange-order' );
 import map = require( '@stdlib/ndarray/base/map' );
 import maxViewBufferIndex = require( '@stdlib/ndarray/base/max-view-buffer-index' );
 import maybeBroadcastArray = require( '@stdlib/ndarray/base/maybe-broadcast-array' );
+import maybeBroadcastArrayExceptDimensions = require( '@stdlib/ndarray/base/maybe-broadcast-array-except-dimensions' );
 import maybeBroadcastArrays = require( '@stdlib/ndarray/base/maybe-broadcast-arrays' );
 import metaDataProps = require( '@stdlib/ndarray/base/meta-data-props' );
 import minSignedIntegerDataType = require( '@stdlib/ndarray/base/min-signed-integer-dtype' );
@@ -2447,6 +2448,38 @@ interface Namespace {
 	*/
 	maybeBroadcastArray: typeof maybeBroadcastArray;
 
+	/**
+	* Broadcasts an ndarray to a specified shape if and only if the specified shape differs from the provided ndarray's shape.
+	*
+	* ## Notes
+	*
+	* -   If a provided ndarray has the same shape as the specified shape (excluding the list of specified dimensions), the function returns the provided ndarray unchanged.
+	* -   The function expects that each index in the list of dimensions is negative in order to ensure that indices correspond to the same relative position in the output ndarray shape. For example, given an input ndarray shape `[2,X1,X2]` and a desired shape `[6,7,2,Y1,Y2]`, a list of negative dimensions `[-2,-1]` correctly maps the unchanged dimensions `X` in the input ndarray to ignored dimensions `Y` in the provided target shape. Nonnegative indices, however, afford no such mapping. For example, the list of dimensions `[1,2]` corresponds to `[X1,X2]` in the input ndarray shape, but to `[7,2]` in the target shape, which is not desired. By expecting negative indices, we avoid confusion and ensure that users always refer to dimensions relative to the last broadcasted dimension.
+	* -   The function throws an error if a provided ndarray is incompatible with a provided shape.
+	* -   If a provided ndarray does not have the same shape as the specified shape, the returned array is a view on the input array data buffer. The view is typically **not** contiguous. As more than one element of a returned view may refer to the same memory location, writing to the view may affect multiple elements. If you need to write to the returned array, copy the array before performing operations which may mutate elements.
+	* -   If a provided ndarray does not have the same shape as the specified shape, the returned array is a "base" ndarray, and, thus, the returned array does not perform bounds checking or afford any of the guarantees of the non-base ndarray constructor. The primary intent of this function is to broadcast an ndarray-like object within internal implementations and to do so with minimal overhead.
+	*
+	* @param arr - input array
+	* @param shape - desired shape
+	* @param dims - list of dimensions to exclude from broadcasting
+	* @throws input array cannot have more dimensions than the desired shape
+	* @throws broadcasted dimensions in the input array and desired shape must be broadcast compatible
+	* @throws dimension indices must not exceed desired shape bounds
+	* @throws must provide unique dimension indices
+	* @returns broadcasted array
+	*
+	* @example
+	* var array = require( '@stdlib/ndarray/array' );
+	* var getShape = require( '@stdlib/ndarray/shape' );
+	*
+	* var x = array( [ [ 1, 2, 3 ] ] );
+	* // returns <ndarray>[ [ 1, 2, 3 ] ]
+	*
+	* var y = ns.maybeBroadcastArrayExceptDimensions( x, [ 2, 2, 3 ], [ -2 ] );
+	* // returns <ndarray>[ [ [ 1, 2, 3 ] ], [ [ 1, 2, 3 ] ] ]
+	*/
+	maybeBroadcastArrayExceptDimensions: typeof maybeBroadcastArrayExceptDimensions;
+
 	/**
 	* Broadcasts ndarrays to a common shape.
 	*
@@ -4645,29 +4678,22 @@ interface Namespace {
 	* Transposes a matrix (or a stack of matrices).
 	*
 	* @param x - input array
+	* @param writable - boolean indicating whether the returned ndarray should be writable
 	* @returns ndarray view
 	*
 	* @example
+	* var getData = require( '@stdlib/ndarray/data-buffer' );
 	* var array = require( '@stdlib/ndarray/array' );
 	*
 	* var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], {
 	*     'dtype': 'generic'
 	* });
-	* // returns <ndarray>
-	*
-	* var sh = x.shape;
-	* // returns [ 2, 3 ]
-	*
-	* var y = ns.transpose( x );
-	* // returns <ndarray>
-	*
-	* sh = y.shape;
-	* // returns [ 3, 2 ]
+	* // returns <ndarray>[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
 	*
-	* var bool = ( x.get( 0, 1 ) === y.get( 1, 0 ) );
-	* // returns true
+	* var y = ns.transpose( x, false );
+	* // returns <ndarray>[ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
 	*
-	* bool = ( x.data === y.data );
+	* var bool = ( getData( x ) === getData( y ) );
 	* // returns true
 	*/
 	transpose: typeof transpose;