feat: add support for specifying an array index cache and add support for linear indexing

---
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: na
  - 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: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

---
type: pre_push_report
description: Results of running various checks prior to pushing changes.
report:
  - task: run_javascript_examples
    status: passed
  - task: run_c_examples
    status: na
  - task: run_cpp_examples
    status: na
  - task: run_javascript_readme_examples
    status: passed
  - task: run_c_benchmarks
    status: na
  - task: run_cpp_benchmarks
    status: na
  - task: run_fortran_benchmarks
    status: na
  - task: run_javascript_benchmarks
    status: passed
  - task: run_julia_benchmarks
    status: na
  - task: run_python_benchmarks
    status: na
  - task: run_r_benchmarks
    status: na
  - task: run_javascript_tests
    status: passed
---

Author: kgryte

lib/node_modules/@stdlib/ndarray/to-fancy/README.md

@@ -92,6 +92,7 @@ The function supports the following options:
 
     -   **data**: the underlying index ndarray.
     -   **type**: the index type. Must be either `'mask'`, `'bool'`, or `'int'`.
+    -   **kind**: the index kind. Must be either `''`, `'cartesian'`, or `'linear'`.
     -   **dtype**: the [data type][@stdlib/ndarray/dtypes] of the underlying ndarray.
 
     If an ndarray index is not associated with a provided identifier, the `get` method should return `null`.
@@ -132,6 +133,7 @@ The function supports the following options:
 
     -   **data**: the underlying index ndarray.
     -   **type**: the index type. Must be either `'mask'`, `'bool'`, or `'int'`.
+    -   **kind**: the index kind. Must be either `''`, `'cartesian'`, or `'linear'`.
     -   **dtype**: the [data type][@stdlib/ndarray/dtypes] of the underlying ndarray.
 
     If an ndarray index is not associated with a provided identifier, the `get` method should return `null`.
@@ -195,6 +197,10 @@ For documentation and usage, see [`ndindex`][@stdlib/ndarray/index].
 
 // TODO: see array/to-fancy
 
+### Linear Indexing
+
+// TODO: only applies to non-zero-dimensional ndarrays. In non-strict mode, out-of-bounds indices return `undefined` and fail to assign.
+
 ### Broadcasting
 
 // TODO: see array/to-fancy

lib/node_modules/@stdlib/ndarray/to-fancy/docs/repl.txt

@@ -15,9 +15,9 @@
     numeric literals and strings), Slice and MultiSlice instances, subsequence
     expressions, mask ndarrays, boolean ndarrays, and integer ndarrays.
 
-    A fancy array supports all properties and methods of the input array, and,
-    thus, a fancy array can be consumed by any API which supports array-like
-    objects.
+    A fancy ndarray supports all properties and methods of the input ndarray,
+    and, thus, a fancy ndarray can be consumed by any API which supports
+    ndarray-like objects.
 
     For operations returning a new ndarray (e.g., when slicing or invoking an
     instance method), a fancy ndarray returns a new fancy ndarray having the
@@ -72,6 +72,7 @@
 
         - data: the underlying index ndarray.
         - type: the index type. Must be either 'mask', 'bool', or 'int'.
+        - kind: the index kind. Must be either '', 'cartesian', or 'linear'.
         - dtype: the data type of the underlying ndarray.
 
         If an ndarray index is not associated with a provided identifier, the
@@ -137,6 +138,7 @@
 
         - data: the underlying index ndarray.
         - type: the index type. Must be either 'mask', 'bool', or 'int'.
+        - kind: the index kind. Must be either '', 'cartesian', or 'linear'.
         - dtype: the data type of the underlying ndarray.
 
         If an ndarray index is not associated with a provided identifier, the
@@ -183,6 +185,17 @@
         Boolean indicating whether to continue persisting an index object after
         first usage. Default: false.
 
+    options.kind: string (optional)
+        Specifies whether a provided ndarray is a specialized input ndarray
+        "kind". This option is only applicable for integer input ndarrays. Must
+        be one of the following:
+
+        - cartesian: a provided input ndarray contains Cartesian indices.
+        - linear: a provided input ndarray contains indices representing
+          locations in linear memory.
+
+        Default: ''.
+
     Returns
     -------
     out: ndarrayIndex

lib/node_modules/@stdlib/ndarray/to-fancy/lib/ctor.js

@@ -27,6 +27,7 @@
 * @param {Function} ndarray2fancy - function for creating a proxied ndarray
 * @param {Object} opts - options
 * @param {boolean} opts.strict - boolean indicating whether to perform strict bounds checking
+* @param {Function} opts.cache - cache for resolving ndarray index objects
 * @returns {Function} handler
 */
 function factory( ndarray2fancy, opts ) {

lib/node_modules/@stdlib/ndarray/to-fancy/lib/defaults.js

@@ -18,6 +18,11 @@
 
 'use strict';
 
+// MODULES //
+
+var ndindex = require( '@stdlib/ndarray/index' );
+
+
 // MAIN //
 
 /**
@@ -32,7 +37,7 @@
 */
 function defaults() {
 	return {
-		'cache': null, // FIXME: default index cache
+		'cache': ndindex,
 		'strict': false
 	};
 }

lib/node_modules/@stdlib/ndarray/to-fancy/lib/error_message.js

@@ -33,7 +33,7 @@ var replace = require( '@stdlib/string/base/replace' );
 * @returns {string} updated message
 */
 function errMessage( msg ) {
-	return replace( msg, /^invalid argument/, 'invalid operation' );
+	return replace( msg, /^invalid arguments?/, 'invalid operation' );
 }
 
 

lib/node_modules/@stdlib/ndarray/to-fancy/lib/factory.js

@@ -32,34 +32,14 @@ var getArrayWrapper = require( './get_ndarray_wrapper.js' );
 var defaults = require( './defaults.js' );
 var validate = require( './validate.js' );
 var validator = require( './validator.js' );
-var prop2slice0d = require( './prop2slice.0d.js' );
-var prop2slice1d = require( './prop2slice.1d.js' );
-var prop2slicend = require( './prop2slice.nd.js' );
+var prop2slice = require( './prop2slice.js' );
 var ctor = require( './ctor.js' );
+var getter = require( './getter.js' );
+var setter = require( './setter.js' );
 var get = require( './get.js' );
 var set = require( './set.js' );
 
 
-// FUNCTIONS //
-
-/**
-* Returns a function for converting a property string to a slice according to a specified dimensionality.
-*
-* @private
-* @param {NonNegativeInteger} ndims - number of dimensions
-* @returns {Function} function for converting a property string to a slice
-*/
-function prop2slice( ndims ) {
-	if ( ndims === 0 ) {
-		return prop2slice0d;
-	}
-	if ( ndims === 1 ) {
-		return prop2slice1d;
-	}
-	return prop2slicend;
-}
-
-
 // MAIN //
 
 /**
@@ -140,6 +120,8 @@ function factory() {
 			o = {
 				'ref': x,
 				'dtype': dt,
+				'getter': getter( x ),
+				'setter': setter( x ),
 				'preSetElement': setElementWrapper( dt ),
 				'postGetArray': getArrayWrapper( ndarray2fancy, opts ),
 				'cache': opts.cache,
@@ -149,7 +131,7 @@ function factory() {
 				'ctor': new Proxy( x.constructor || ndarray, {
 					'construct': ctor( ndarray2fancy, opts )
 				}),
-				'prop2slice': prop2slice( arr.shape.length )
+				'prop2slice': prop2slice( arr.shape.length ) // WARNING: we assume a fixed number of dimensions!
 			};
 			return new Proxy( x, {
 				'get': get( o ),

lib/node_modules/@stdlib/ndarray/to-fancy/lib/get.js

@@ -20,7 +20,13 @@
 
 // MODULES //
 
-var hasProperty = require( './has_property.js' );
+var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var hasProperty = require( '@stdlib/assert/has-property' );
+var isIntegerString = require( './is_integer_string.js' );
+var isArrayIndexString = require( './is_ndindex_string.js' );
+var isCartesianIndexString = require( './is_cartesian_index_string.js' );
+var getElement = require( './get_element.js' );
+var getCartesian = require( './get_cartesian.js' );
 var getValue = require( './get_value.js' );
 var getSlice = require( './get_slice.js' );
 
@@ -54,10 +60,20 @@ function factory( ctx ) {
 	* @returns {*} result
 	*/
 	function get( target, property, receiver ) {
-		if ( hasProperty( property ) ) {
-			return getValue( target, property, receiver );
+		if ( isIntegerString( property ) ) {
+			return getElement( target, property, ctx );
 		}
-		return getSlice( target, property, receiver, ctx.prop2slice );
+		if ( hasProperty( target, property ) || !isString( property ) ) {
+			return getValue( target, property, receiver, ctx );
+		}
+		if ( isCartesianIndexString( property ) ) {
+			return getCartesian( target, property, ctx );
+		}
+		if ( isArrayIndexString( property ) ) {
+			// FIXME
+			return;
+		}
+		return getSlice( target, property, ctx );
 	}
 }
 

lib/node_modules/@stdlib/ndarray/to-fancy/lib/get_cartesian.js

@@ -0,0 +1,63 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var scalar2ndarrayLike = require( '@stdlib/ndarray/base/from-scalar-like' );
+var getShape = require( '@stdlib/ndarray/base/shape' );
+var resolveSubscripts = require( './resolve_subscripts.js' );
+
+
+// MAIN //
+
+/**
+* Returns the element associated with a specified set of subscripts.
+*
+* @private
+* @param {ndarrayLike} target - target object
+* @param {string} property - index string
+* @param {Object} ctx - context object
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @param {Function} ctx.postGetArray - function to process a retrieved ndarray
+* @throws {RangeError} index exceeds ndarray bounds
+* @throws {RangeError} number of indices must match the number of ndarray dimensions
+* @returns {(ndarrayLike|void)} result
+*/
+function getCartesian( target, property, ctx ) {
+	var sub;
+	var v;
+
+	sub = resolveSubscripts( property, getShape( target, false ), ctx.strict );
+	if ( sub === void 0 ) {
+		return;
+	}
+	// Use the `get` method, which we expect every ndarray-like object to have, in order to resolve a single element:
+	v = target.get.apply( target, sub );
+	if ( v === void 0 ) {
+		return;
+	}
+	// Return the element as a 0-D ndarray to ensure consistency with linear indexing and slicing:
+	return ctx.postGetArray( scalar2ndarrayLike( target, v ) );
+}
+
+
+// EXPORTS //
+
+module.exports = getCartesian;

lib/node_modules/@stdlib/ndarray/to-fancy/lib/get_element.js

@@ -0,0 +1,52 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var scalar2ndarrayLike = require( '@stdlib/ndarray/base/from-scalar-like' );
+
+
+// MAIN //
+
+/**
+* Returns the element associated with a specified index.
+*
+* @private
+* @param {ndarrayLike} target - target object
+* @param {string} property - index string
+* @param {Object} ctx - context object
+* @param {Function} ctx.getter - accessor for retrieving array elements
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @param {Function} ctx.postGetArray - function to process a retrieved ndarray
+* @throws {RangeError} index exceeds ndarray bounds
+* @returns {(ndarrayLike|void)} result
+*/
+function getElement( target, property, ctx ) {
+	var v = ctx.getter( target, property, ctx.strict );
+	if ( v === void 0 ) {
+		return;
+	}
+	return ctx.postGetArray( scalar2ndarrayLike( target, v ) );
+}
+
+
+// EXPORTS //
+
+module.exports = getElement;

lib/node_modules/@stdlib/ndarray/to-fancy/lib/get_elements.js

@@ -0,0 +1,70 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+// var take = require( '@stdlib/ndarray/take' );
+
+// var mskfilter = require( '@stdlib/ndarray/mskfilter' );
+
+// var mskreject = require( '@stdlib/ndarray/mskreject' );
+
+var format = require( '@stdlib/string/format' );
+var prop2array = require( './prop2array.js' );
+
+
+// MAIN //
+
+/**
+* Returns the elements specified by an ndarray index.
+*
+* @private
+* @param {ndarrayLike} target - target object
+* @param {string} property - index string
+* @param {Object} ctx - context object
+* @param {Object} ctx.cache - cache for resolving ndarray index objects
+* @param {Function} ctx.postGetArray - function to process a retrieved ndarray
+* @throws {Error} invalid ndarray index
+* @throws {RangeError} index exceeds ndarray bounds
+* @returns {ndarrayLike} result
+*/
+function getElements( target, property, ctx ) {
+	var idx = prop2array( property, ctx.cache );
+	if ( idx.type === 'int' ) {
+		// FIXME: handle the various "kinds" of index arrays (e.g., "linear" and "cartesian")
+
+		// return ctx.postGetArray( take( target, idx.data ) );
+		return NaN; // FIXME
+	}
+	if ( idx.type === 'bool' ) {
+		// return ctx.postGetArray( mskfilter( target, idx.data ) );
+		return NaN; // FIXME
+	}
+	if ( idx.type === 'mask' ) {
+		// return ctx.postGetArray( mskreject( target, idx.data ) );
+		return NaN; // FIXME
+	}
+	throw new Error( format( 'invalid operation. Unrecognized ndarray index type. Value: `%s`.', idx.type ) );
+}
+
+
+// EXPORTS //
+
+module.exports = getElements;