Auto-generated commit

README.md

@@ -146,8 +146,19 @@ v = y[ ':' ];
 
 The function supports the following options:
 
+-   **cache**: cache for resolving array index objects. Must have a `get` method which accepts a single argument: a string identifier associated with an array index.
+
+    If an array index associated with a provided identifier exists, the `get` method should return an object having the following properties:
+
+    -   **data**: the underlying index array.
+    -   **type**: the index type. Must be either `'mask'`, `'bool'`, or `'int'`.
+    -   **dtype**: the [data type][@stdlib/array/dtypes] of the underlying array.
+
+    If an array index is not associated with a provided identifier, the `get` method should return `null`.
+
+    Default: [`ArrayIndex`][@stdlib/array/index].
+
 -   **strict**: boolean indicating whether to enforce strict bounds checking. Default: `false`.
--   **cache**: cache for resolving array index objects. Default: [`ArrayIndex`][@stdlib/array/index].
 
 By default, the function returns a fancy array which does **not** enforce strict bounds checking. For example,
 
@@ -189,8 +200,19 @@ var v = y[ ':' ];
 
 The function supports the following options:
 
+-   **cache**: default cache for resolving array index objects. Must have a `get` method which accepts a single argument: a string identifier associated with an array index.
+
+    If an array index associated with a provided identifier exists, the `get` method should return an object having the following properties:
+
+    -   **data**: the underlying index array.
+    -   **type**: the index type. Must be either `'mask'`, `'bool'`, or `'int'`.
+    -   **dtype**: the [data type][@stdlib/array/dtypes] of the underlying array.
+
+    If an array index is not associated with a provided identifier, the `get` method should return `null`.
+
+    Default: [`ArrayIndex`][@stdlib/array/index].
+
 -   **strict**: boolean indicating whether to enforce strict bounds checking by default. Default: `false`.
--   **cache**: cache for resolving array index objects. Default: [`ArrayIndex`][@stdlib/array/index].
 
 By default, the function returns a function which, by default, does **not** enforce strict bounds checking. For example,
 
@@ -238,6 +260,72 @@ The returned function supports the same options as above. When the returned func
 -   Indexing expressions provide a convenient and powerful means for creating and operating on array views; however, their use does entail a performance cost. Indexing expressions are best suited for interactive use (e.g., in the [REPL][@stdlib/repl]) and scripting. For performance critical applications, prefer equivalent functional APIs supporting array-like objects.
 -   In older JavaScript environments which do **not** support [`Proxy`][@stdlib/proxy/ctor] objects, the use of indexing expressions is **not** supported.
 
+### Bounds Checking
+
+By default, fancy arrays do **not** enforce strict bounds checking across index expressions. The motivation for the default fancy array behavior stems from a desire to maintain parity with plain arrays; namely, the returning of `undefined` when accessing a single non-existent property.
+
+Accordingly, when `strict` is `false`, one may observe the following behaviors:
+
+<!-- run throws: true -->
+
+```javascript
+var idx = require( '@stdlib/array-index' );
+
+var x = array2fancy( [ 1, 2, 3, 4 ], {
+    'strict': false
+});
+
+// Access a non-existent property:
+var v = x[ 'foo' ];
+// returns undefined
+
+// Access an out-of-bounds index:
+v = x[ 10 ];
+// returns undefined
+
+v = x[ -10 ];
+// returns undefined
+
+// Access an out-of-bounds slice:
+v = x[ '10:' ];
+// returns []
+
+// Access one or more out-of-bounds indices:
+v = x[ idx( [ 10, 20 ] ) ];
+// throws <RangeError>
+```
+
+When `strict` is `true`, fancy arrays normalize index behavior and consistently enforce strict bounds checking.
+
+<!-- run throws: true -->
+
+```javascript
+var idx = require( '@stdlib/array-index' );
+
+var x = array2fancy( [ 1, 2, 3, 4 ], {
+    'strict': true
+});
+
+// Access a non-existent property:
+var v = x[ 'foo' ];
+// returns undefined
+
+// Access an out-of-bounds index:
+v = x[ 10 ];
+// throws <RangeError>
+
+v = x[ -10 ];
+// throws <RangeError>
+
+// Access an out-of-bounds slice:
+v = x[ '10:' ];
+// throws <RangeError>
+
+// Access one or more out-of-bounds indices:
+v = x[ idx( [ 10, 20 ] ) ];
+// throws <RangeError>
+```
+
 ### Broadcasting
 
 Fancy arrays support **broadcasting** in which assigned scalars and single-element arrays are repeated (without additional memory allocation) to match the length of a target array instance.
@@ -373,22 +461,6 @@ im = imag( v );
 // returns 0.0
 ```
 
-Note, however, that attempting to assign a real-valued array to a complex number array slice is **not** supported due to the ambiguity of whether the real-valued array is a collection of real components (with implied imaginary components equal to zero) or an array of interleaved real and imaginary components.
-
-<!-- run throws: true -->
-
-```javascript
-var Float64Array = require( '@stdlib/array-float64' );
-var Complex128Array = require( '@stdlib/array-complex128' );
-
-var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0 ] );
-var y = array2fancy( x );
-
-// Attempt to assign a real-valued array:
-y[ ':' ] = new Float64Array( [ 5.0, 6.0 ] ); // is this a single complex number which should be broadcast or a list of real components with implied imaginary components?
-// throws <Error>
-``` 
-
 </section>
 
 <!-- /.notes -->
@@ -404,12 +476,16 @@ y[ ':' ] = new Float64Array( [ 5.0, 6.0 ] ); // is this a single complex number
 <!-- eslint no-undef: "error" -->
 
 ```javascript
+var Uint8Array = require( '@stdlib/array-uint8' );
+var Int32Array = require( '@stdlib/array-int32' );
+var idx = require( '@stdlib/array-index' );
 var array2fancy = require( '@stdlib/array-to-fancy' );
 
 var x = [ 1, 2, 3, 4, 5, 6 ];
 var y = array2fancy( x );
 // returns <Array>
 
+// Slice retrieval:
 var z = y[ '1::2' ];
 // returns [ 2, 4, 6 ]
 
@@ -419,13 +495,31 @@ z = y[ '-2::-2' ];
 z = y[ '1:4' ];
 // returns [ 2, 3, 4 ]
 
+// Slice assignment:
 y[ '4:1:-1' ] = 10;
 z = y[ ':' ];
 // returns [ 1, 2, 10, 10, 10, 6 ]
 
 y[ '2:5' ] = [ -10, -9, -8 ];
 z = y[ ':' ];
 // returns [ 1, 2, -10, -9, -8, 6 ]
+
+// Array index retrieval:
+var i = idx( [ 1, 3, 4 ] ); // integer index array
+z = y[ i ];
+// returns [ 2, -9, -8 ]
+
+i = idx( [ true, false, false, true, true, true ] ); // boolean array
+z = y[ i ];
+// returns [ 1, -9, -8, 6 ]
+
+i = idx( new Uint8Array( [ 0, 0, 1, 0, 0, 1 ] ) ); // mask array
+z = y[ i ];
+// returns [ 1, 2, -9, -8 ]
+
+i = idx( new Int32Array( [ 0, 0, 1, 1, 2, 2 ] ) ); // integer index array
+z = y[ i ];
+// returns [ 1, 1, 2, 2, -10, -10 ]
 ```
 
 </section>
@@ -540,6 +634,8 @@ Copyright &copy; 2016-2024. The Stdlib [Authors][stdlib-authors].
 
 [@stdlib/array/index]: https://github.com/stdlib-js/array-index
 
+[@stdlib/array/dtypes]: https://github.com/stdlib-js/array-dtypes
+
 </section>
 
 <!-- /.links -->