Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2025-01-12)
+## Unreleased (2025-01-13)
 
 <section class="packages">
 
@@ -86,6 +86,7 @@
 
 ##### Features
 
+-   [`e661213`](https://github.com/stdlib-js/stdlib/commit/e66121352ef767cdb87d19e938b1eccf7970fa3a) - update namespace TypeScript declarations [(#4706)](https://github.com/stdlib-js/stdlib/pull/4706)
 -   [`741b6f1`](https://github.com/stdlib-js/stdlib/commit/741b6f1df8ce11e77fb22c279cee6bbae3323176) - add `spreadDimensions` to namespace
 -   [`908239e`](https://github.com/stdlib-js/stdlib/commit/908239e7cc6b4b3e260d0cc1f5aebb9af35d83c6) - add `toUniqueNormalizedIndices` to namespace
 -   [`524e854`](https://github.com/stdlib-js/stdlib/commit/524e854202862d5b37d66470d719fac1270e33c1) - add `toNormalizedIndices` to namespace
@@ -129,6 +130,7 @@
 
 ##### Features
 
+-   [`e661213`](https://github.com/stdlib-js/stdlib/commit/e66121352ef767cdb87d19e938b1eccf7970fa3a) - update namespace TypeScript declarations [(#4706)](https://github.com/stdlib-js/stdlib/pull/4706)
 -   [`a94dcea`](https://github.com/stdlib-js/stdlib/commit/a94dceaa9469c774ee4622567e4c15a15e215bcf) - add `isColumnMajorString` to namespace
 -   [`5e1be08`](https://github.com/stdlib-js/stdlib/commit/5e1be08ff661fb981dc4a91c2e9d37d7396327f5) - add `isRowMajorString` to namespace
 -   [`8b1548f`](https://github.com/stdlib-js/stdlib/commit/8b1548fb45c1ff131f5edac20cb984344a2d28ec) - update namespace TypeScript declarations [(#3190)](https://github.com/stdlib-js/stdlib/pull/3190)
@@ -754,6 +756,12 @@ A total of 3 people contributed to this release. Thank you to the following cont
 
 <details>
 
+-   [`efe1f05`](https://github.com/stdlib-js/stdlib/commit/efe1f05049247502e9b124957755ebc6d7974b4e) - **docs:** add note _(by Athan Reines)_
+-   [`fc93a7c`](https://github.com/stdlib-js/stdlib/commit/fc93a7c94279c57675c8fc695189200ec0129821) - **docs:** add note _(by Athan Reines)_
+-   [`1634973`](https://github.com/stdlib-js/stdlib/commit/16349736f27970606eda37417f4d2c868d9f1457) - **docs:** add note _(by Athan Reines)_
+-   [`2d758d2`](https://github.com/stdlib-js/stdlib/commit/2d758d2dbab56194af31b9d54988b5fb9b928860) - **docs:** add note _(by Athan Reines)_
+-   [`705dd30`](https://github.com/stdlib-js/stdlib/commit/705dd302fe6448af5addcacf9215574da5473f31) - **docs:** update examples _(by Athan Reines)_
+-   [`e661213`](https://github.com/stdlib-js/stdlib/commit/e66121352ef767cdb87d19e938b1eccf7970fa3a) - **feat:** update namespace TypeScript declarations [(#4706)](https://github.com/stdlib-js/stdlib/pull/4706) _(by stdlib-bot)_
 -   [`cff470f`](https://github.com/stdlib-js/stdlib/commit/cff470f9608165100c8c122fce70c40b1af864ec) - **docs:** update namespace table of contents (#4708) _(by stdlib-bot, Planeshifter)_
 -   [`741b6f1`](https://github.com/stdlib-js/stdlib/commit/741b6f1df8ce11e77fb22c279cee6bbae3323176) - **feat:** add `spreadDimensions` to namespace _(by Athan Reines)_
 -   [`3767255`](https://github.com/stdlib-js/stdlib/commit/3767255c7cfe85f09cea5c007e21297cd628245d) - **feat:** add `ndarray/base/spread-dimensions` _(by Athan Reines)_

base/assert/docs/types/index.d.ts

@@ -28,6 +28,7 @@ import isBufferLengthCompatibleShape = require( './../../../../base/assert/is-bu
 import isCastingMode = require( './../../../../base/assert/is-casting-mode' );
 import isColumnMajor = require( './../../../../base/assert/is-column-major' );
 import isColumnMajorContiguous = require( './../../../../base/assert/is-column-major-contiguous' );
+import isColumnMajorString = require( './../../../../base/assert/is-column-major-string' );
 import isComplexFloatingPointDataType = require( './../../../../base/assert/is-complex-floating-point-data-type' );
 import isContiguous = require( './../../../../base/assert/is-contiguous' );
 import isDataType = require( './../../../../base/assert/is-data-type' );
@@ -42,6 +43,7 @@ import isRealDataType = require( './../../../../base/assert/is-real-data-type' )
 import isRealFloatingPointDataType = require( './../../../../base/assert/is-real-floating-point-data-type' );
 import isRowMajor = require( './../../../../base/assert/is-row-major' );
 import isRowMajorContiguous = require( './../../../../base/assert/is-row-major-contiguous' );
+import isRowMajorString = require( './../../../../base/assert/is-row-major-string' );
 import isSafeDataTypeCast = require( './../../../../base/assert/is-safe-data-type-cast' );
 import isSameKindDataTypeCast = require( './../../../../base/assert/is-same-kind-data-type-cast' );
 import isSignedIntegerDataType = require( './../../../../base/assert/is-signed-integer-data-type' );
@@ -262,6 +264,24 @@ interface Namespace {
 	*/
 	isColumnMajorContiguous: typeof isColumnMajorContiguous;
 
+	/**
+	* Tests whether an input value is the string representing column-major order.
+	*
+	* @param v - value to test
+	* @returns boolean result
+	*
+	* @example
+	* var bool = ns.isColumnMajorString( 'column-major' );
+	* // returns true
+	*
+	* bool = ns.isColumnMajorString( 'row-major' );
+	* // returns false
+	*
+	* bool = ns.isColumnMajorString( 'foo' );
+	* // returns false
+	*/
+	isColumnMajorString: typeof isColumnMajorString;
+
 	/**
 	* Tests whether an input value is a supported ndarray complex-valued floating-point data type.
 	*
@@ -747,6 +767,24 @@ interface Namespace {
 	*/
 	isRowMajorContiguous: typeof isRowMajorContiguous;
 
+	/**
+	* Tests whether an input value is the string representing row-major order.
+	*
+	* @param v - value to test
+	* @returns boolean result
+	*
+	* @example
+	* var bool = ns.isRowMajorString( 'row-major' );
+	* // returns true
+	*
+	* bool = ns.isRowMajorString( 'column-major' );
+	* // returns false
+	*
+	* bool = ns.isRowMajorString( 'foo' );
+	* // returns false
+	*/
+	isRowMajorString: typeof isRowMajorString;
+
 	/**
 	* Returns a boolean indicating if a provided ndarray data type can be safely cast to another ndarray data type.
 	*

base/docs/types/index.d.ts

@@ -76,6 +76,7 @@ import ndims = require( './../../../base/ndims' );
 import nextCartesianIndex = require( './../../../base/next-cartesian-index' );
 import nonsingletonDimensions = require( './../../../base/nonsingleton-dimensions' );
 import normalizeIndex = require( './../../../base/normalize-index' );
+import normalizeIndices = require( './../../../base/normalize-indices' );
 import nullary = require( './../../../base/nullary' );
 import nullaryLoopOrder = require( './../../../base/nullary-loop-interchange-order' );
 import nullaryBlockSize = require( './../../../base/nullary-tiling-block-size' );
@@ -102,13 +103,16 @@ import sliceDimensionFrom = require( './../../../base/slice-dimension-from' );
 import sliceDimensionTo = require( './../../../base/slice-dimension-to' );
 import sliceFrom = require( './../../../base/slice-from' );
 import sliceTo = require( './../../../base/slice-to' );
+import spreadDimensions = require( './../../../base/spread-dimensions' );
 import stride = require( './../../../base/stride' );
 import strides = require( './../../../base/strides' );
 import strides2offset = require( './../../../base/strides2offset' );
 import strides2order = require( './../../../base/strides2order' );
 import sub2ind = require( './../../../base/sub2ind' );
 import ndarray2array = require( './../../../base/to-array' );
+import toNormalizedIndices = require( './../../../base/to-normalized-indices' );
 import toReversed = require( './../../../base/to-reversed' );
+import toUniqueNormalizedIndices = require( './../../../base/to-unique-normalized-indices' );
 import transpose = require( './../../../base/transpose' );
 import unary = require( './../../../base/unary' );
 import unaryBy = require( './../../../base/unary-by' );
@@ -1865,6 +1869,27 @@ interface Namespace {
 	*/
 	normalizeIndex: typeof normalizeIndex;
 
+	/**
+	* Normalizes a list of indices to the interval `[0,max]`.
+	*
+	* ## Notes
+	*
+	* -   If provided an out-of-bounds index, the function returns `null`.
+	* -   The function mutates the input array, even when provided an out-of-bounds index.
+	*
+	* @param indices - indices
+	* @param max - maximum index
+	* @returns normalized indices or null
+	*
+	* @example
+	* var indices = ns.normalizeIndices( [ -2, 5 ], 10 );
+	* // returns [ 9, 5 ]
+	*
+	* indices = ns.normalizeIndices( [ -2, 15 ], 10 );
+	* // returns null
+	*/
+	normalizeIndices: typeof normalizeIndices;
+
 	/**
 	* Applies a nullary callback and assigns results to elements in an output ndarray.
 	*
@@ -2662,6 +2687,48 @@ interface Namespace {
 	*/
 	sliceTo: typeof sliceTo;
 
+	/**
+	* Expands the shape of an array to a specified dimensionality by spreading its dimensions to specified dimension indices and inserting dimensions of size one for the remaining dimensions.
+	*
+	* ## Notes
+	*
+	* -   Each provided dimension index must reside on the interval `[-ndims, ndims-1]`. If provided a negative dimension index, the position at which to place a respective dimension is computed as `ndims + index`.
+	* -   Provided dimension indices must resolve to normalized dimension indices arranged in ascending order.
+	*
+	* @param ndims - number of dimensions in the output array
+	* @param x - input array
+	* @param dims - dimension indices
+	* @returns output array
+	*
+	* @example
+	* var array = require( './../../../array' );
+	*
+	* var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
+	* // returns <ndarray>
+	*
+	* var shx = x.shape;
+	* // returns [ 2, 2 ]
+	*
+	* var y = ns.spreadDimensions( 5, x, [ 1, 3 ] );
+	* // returns <ndarray>
+	*
+	* var shy = y.shape;
+	* // returns [ 1, 2, 1, 2, 1 ]
+	*
+	* var v = y.get( 0, 0, 0, 0, 0 );
+	* // returns 1
+	*
+	* v = y.get( 0, 0, 0, 1, 0 );
+	* // returns 2
+	*
+	* v = y.get( 0, 1, 0, 0, 0 );
+	* // returns 3
+	*
+	* v = y.get( 0, 1, 0, 1, 0 );
+	* // returns 4
+	*/
+	spreadDimensions: typeof spreadDimensions;
+
 	/**
 	* Returns the stride along a specified dimension for a provided ndarray.
 	*
@@ -2865,6 +2932,26 @@ interface Namespace {
 	*/
 	ndarray2array: typeof ndarray2array;
 
+	/**
+	* Normalizes a list of indices to the interval `[0,max]`.
+	*
+	* ## Notes
+	*
+	* -   If provided an out-of-bounds index, the function normalizes the index to `-1`.
+	*
+	* @param indices - indices
+	* @param max - maximum index
+	* @returns normalized indices
+	*
+	* @example
+	* var indices = ns.toNormalizedIndices( [ -2, 5 ], 10 );
+	* // returns [ 9, 5 ]
+	*
+	* indices = ns.toNormalizedIndices( [ -2, 15 ], 10 );
+	* // returns [ 9, -1 ]
+	*/
+	toNormalizedIndices: typeof toNormalizedIndices;
+
 	/**
 	* Returns a new ndarray where the order of elements of an input ndarray is reversed along each dimension.
 	*
@@ -2901,6 +2988,26 @@ interface Namespace {
 	*/
 	toReversed: typeof toReversed;
 
+	/**
+	* Returns a list of unique indices after normalizing to the interval `[0,max]`.
+	*
+	* ## Notes
+	*
+	* -   If provided an out-of-bounds index, the function returns `null`.
+	*
+	* @param indices - indices
+	* @param max - maximum index
+	* @returns normalized indices (or null)
+	*
+	* @example
+	* var indices = ns.toUniqueNormalizedIndices( [ -2, 5 ], 10 );
+	* // returns [ 9, 5 ]
+	*
+	* indices = ns.toUniqueNormalizedIndices( [ -2, 15 ], 10 );
+	* // returns null
+	*/
+	toUniqueNormalizedIndices: typeof toUniqueNormalizedIndices;
+
 	/**
 	* Transposes a matrix (or a stack of matrices).
 	*

base/normalize-index/README.md

@@ -70,6 +70,10 @@ idx = normalizeIndex( -15, 10 );
 
 <section class="notes">
 
+## Notes
+
+-   During normalization, a negative index is converted to a nonnegative index according to `max + idx + 1`. If, after normalization, the resolved index is still negative, the value is considered out-of-bounds.
+
 </section>
 
 <!-- /.notes -->

base/normalize-indices/README.md

@@ -67,6 +67,7 @@ var idx = normalizeIndices( [ 15, -15 ], 10 );
 ## Notes
 
 -   The function mutates the input array, even when provided an out-of-bounds index. If mutation is undesired, copy the input array before calling this function.
+-   During normalization, a negative index is converted to a nonnegative index according to `max + idx + 1`. If, after normalization, the resolved index is still negative, the value is considered out-of-bounds.
 
 </section>
 

base/spread-dimensions/README.md

@@ -45,6 +45,7 @@ var spreadDimensions = require( '@stdlib/ndarray/base/spread-dimensions' );
 Expands the shape of an array to a specified dimensionality by spreading its dimensions to specified dimension indices and inserting dimensions of size one for the remaining dimensions.
 
 ```javascript
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var array = require( '@stdlib/ndarray/array' );
 
 // Create a 2x2 ndarray:
@@ -58,19 +59,28 @@ var y = spreadDimensions( 3, x, [ 1, 2 ] );
 var sh = y.shape;
 // returns [ 1, 2, 2 ]
 
+var a = ndarray2array( y );
+// returns [ [ [ 1, 2 ], [ 3, 4 ] ] ]
+
 // Append a singleton dimension:
 y = spreadDimensions( 3, x, [ 0, 1 ] );
 // returns <ndarray>
 
 sh = y.shape;
 // returns [ 2, 2, 1 ]
 
+a = ndarray2array( y );
+// returns [ [ [ 1 ], [ 2 ] ], [ [ 3 ], [ 4 ] ] ]
+
 // Insert a singleton dimension:
 y = spreadDimensions( 3, x, [ 0, 2 ] );
 // returns <ndarray>
 
 sh = y.shape;
 // returns [ 2, 1, 2 ]
+
+a = ndarray2array( y );
+// returns [ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
 ```
 
 </section>

base/to-normalized-indices/README.md

@@ -64,6 +64,10 @@ var idx = toNormalizedIndices( [ 15, -15 ], 10 );
 
 <section class="notes">
 
+## Notes
+
+-   During normalization, a negative index is converted to a nonnegative index according to `max + idx + 1`. If, after normalization, the resolved index is still negative, the value is considered out-of-bounds.
+
 </section>
 
 <!-- /.notes -->

base/to-unique-normalized-indices/README.md

@@ -66,8 +66,9 @@ var idx = toUniqueNormalizedIndices( [ 15, -15 ], 10 );
 
 ## Notes
 
--   The function preserves provided index order.
+-   During normalization, a negative index is converted to a nonnegative index according to `max + idx + 1`. If, after normalization, the resolved index is still negative, the value is considered out-of-bounds.
 -   When provided valid indices, the function always returns a "generic" array.
+-   The function preserves provided index order.
 
 </section>