@stdlib/array-to-fancy 0.1.0 → 0.2.0

package/docs/types/index.d.ts

@@ -20,27 +20,8 @@
 
 /// <reference types="@stdlib/types"/>
 
-import { Collection, ArrayLike, AccessorArrayLike, Complex128Array, Complex64Array, DataType } from '@stdlib/types/array';
-
-/**
-* Interface describing an index object.
-*/
-interface IndexObject {
-	/**
-	* Underlying array index data.
-	*/
-	data: Collection | AccessorArrayLike<any>;
-
-	/**
-	* Index type.
-	*/
-	type: 'mask' | 'bool' | 'int';
-
-	/**
-	* Underlying array data type.
-	*/
-	dtype: DataType | null;
-}
+import { Collection, ArrayLike, AccessorArrayLike, ComplexTypedArray, TypedArray, BooleanTypedArray, ArrayIndexObject } from '@stdlib/types/array';
+import ArrayIndex = require( '@stdlib/array-index' );
 
 /**
 * Interface describing a cache for resolving array index objects.
@@ -52,7 +33,7 @@ interface Cache {
 	* @param id - identifier
 	* @returns index data
 	*/
-	get( id: any ): IndexObject | null;
+	get( id: any ): ArrayIndexObject | null;
 }
 
 /**
@@ -93,17 +74,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Float64Array>[ 1.0, 2.0, 3.0, 4.0 ]
-	*/
-	( x: Float64Array, options?: Options ): Float64Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Float32Array = require( '@stdlib/array-float32' );
@@ -115,17 +85,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Float32Array>[ 1.0, 2.0, 3.0, 4.0 ]
-	*/
-	( x: Float32Array, options?: Options ): Float32Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Complex128Array = require( '@stdlib/array-complex128' );
@@ -137,17 +96,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Complex128Array>[ 1.0, 2.0, 3.0, 4.0 ]
-	*/
-	( x: Complex128Array, options?: Options ): Complex128Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Complex64Array = require( '@stdlib/array-complex64' );
@@ -159,17 +107,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Complex64Array>[ 1.0, 2.0, 3.0, 4.0 ]
-	*/
-	( x: Complex64Array, options?: Options ): Complex64Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Int32Array = require( '@stdlib/array-int32' );
@@ -181,17 +118,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Int32Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Int32Array, options?: Options ): Int32Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Int16Array = require( '@stdlib/array-int16' );
@@ -203,17 +129,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Int16Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Int16Array, options?: Options ): Int16Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Int8Array = require( '@stdlib/array-int8' );
@@ -225,17 +140,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Int8Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Int8Array, options?: Options ): Int8Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Uint32Array = require( '@stdlib/array-uint32' );
@@ -247,17 +151,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Uint32Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Uint32Array, options?: Options ): Uint32Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Uint16Array = require( '@stdlib/array-uint16' );
@@ -269,17 +162,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Uint16Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Uint16Array, options?: Options ): Uint16Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Uint8Array = require( '@stdlib/array-uint8' );
@@ -291,17 +173,6 @@ interface Array2Fancy {
 	*
 	* var v = y[ ':' ];
 	* // returns <Uint8Array>[ 1, 2, 3, 4 ]
-	*/
-	( x: Uint8Array, options?: Options ): Uint8Array;
-
-	/**
-	* Converts an array to an object supporting fancy indexing.
-	*
-	* @param x - input array
-	* @param options - function options
-	* @param options.strict - boolean indicating whether to enforce strict bounds checking
-	* @param options.cache - cache for resolving array index objects
-	* @returns fancy array
 	*
 	* @example
 	* var Uint8ClampedArray = require( '@stdlib/array-uint8c' );
@@ -314,7 +185,7 @@ interface Array2Fancy {
 	* var v = y[ ':' ];
 	* // returns <Uint8ClampedArray>[ 1, 2, 3, 4 ]
 	*/
-	( x: Uint8ClampedArray, options?: Options ): Uint8ClampedArray;
+	<T extends TypedArray | ComplexTypedArray | BooleanTypedArray>( x: T, options?: Options ): T;
 
 	/**
 	* Converts an array to an object supporting fancy indexing.
@@ -415,6 +286,24 @@ interface Array2Fancy {
 	* // returns [ 1, 2, 3, 4 ]
 	*/
 	factory( options?: Options ): Array2Fancy;
+
+	/**
+	* Array index constructor.
+	*
+	* @param x - input array
+	* @param options - function options
+	* @param options.persist - boolean indicating whether to continue persisting an index object after first usage
+	* @returns ArrayIndex instance
+	*
+	* @example
+	* var Uint8Array = require( '@stdlib/array-uint8' );
+	*
+	* var x = new Uint8Array( [ 1, 0, 1, 0 ] );
+	*
+	* var idx = array2fancy.idx( x );
+	* // returns <ArrayIndex>
+	*/
+	idx: typeof ArrayIndex;
 }
 
 /**

package/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' );
 }
 
 

package/lib/get_elements.js

@@ -21,8 +21,8 @@
 // MODULES //
 
 var take = require( '@stdlib/array-take' );
-var mskfilter = require( '@stdlib/array-base-mskfilter' );
-var mskreject = require( '@stdlib/array-base-mskreject' );
+var mskfilter = require( '@stdlib/array-mskfilter' );
+var mskreject = require( '@stdlib/array-mskreject' );
 var format = require( '@stdlib/string-format' );
 var prop2array = require( './prop2array.js' );
 
@@ -36,7 +36,6 @@ var prop2array = require( './prop2array.js' );
 * @param {Object} 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 {Object} ctx.cache - cache for resolving array index objects
 * @param {Function} ctx.postGetArray - function to process a retrieved array
 * @throws {Error} invalid array index

package/lib/index.js

@@ -50,6 +50,7 @@
 // MODULES //
 
 var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var ArrayIndex = require( '@stdlib/array-index' );
 var main = require( './main.js' );
 var factory = require( './factory.js' );
 
@@ -57,6 +58,7 @@ var factory = require( './factory.js' );
 // MAIN //
 
 setReadOnly( main, 'factory', factory );
+setReadOnly( main, 'idx', ArrayIndex );
 
 
 // EXPORTS //

package/lib/set.js

@@ -23,6 +23,8 @@
 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_array_index_string.js' );
+var setElements = require( './set_elements.js' );
 var setElement = require( './set_element.js' );
 var setValue = require( './set_value.js' );
 var setSlice = require( './set_slice.js' );
@@ -71,6 +73,9 @@ function factory( ctx ) {
 		if ( hasProperty( property ) || !isString( property ) ) {
 			return setValue( target, property, value, ctx );
 		}
+		if ( isArrayIndexString( property ) ) {
+			return setElements( target, property, value, ctx );
+		}
 		out = setSlice( target, property, value, receiver, ctx );
 		if ( out ) {
 			return out;

package/lib/set_elements.js

@@ -0,0 +1,130 @@
+/**
+* @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 isMostlySafeCast = require( '@stdlib/array-base-assert-is-mostly-safe-data-type-cast' );
+var isRealDataType = require( '@stdlib/array-base-assert-is-real-data-type' );
+var isComplexDataType = require( '@stdlib/array-base-assert-is-complex-floating-point-data-type' );
+var isCollection = require( '@stdlib/assert-is-collection' );
+var scalar2array = require( '@stdlib/array-from-scalar' );
+var dtype = require( '@stdlib/array-dtype' );
+var put = require( '@stdlib/array-put' );
+var place = require( '@stdlib/array-place' );
+var convert = require( '@stdlib/array-convert' );
+var where = require( '@stdlib/array-base-where' ).assign;
+var format = require( '@stdlib/string-format' );
+var prop2array = require( './prop2array.js' );
+var errMessage = require( './error_message.js' );
+
+
+// MAIN //
+
+/**
+* Replaces the elements specified by an array index.
+*
+* @private
+* @param {Object} target - target object
+* @param {string} property - index string
+* @param {*} value - new value(s)
+* @param {Object} ctx - context object
+* @param {string} ctx.dtype - array data type
+* @param {Object} ctx.cache - cache for resolving array index objects
+* @param {Function} ctx.validator - function for validating new values
+* @param {(Function|null)} ctx.preSetElement - function for normalizing new values (if necessary)
+* @throws {Error} invalid array index
+* @throws {RangeError} index exceeds array bounds
+* @throws {Error} assigned value must be broadcast compatible with target array selection
+* @throws {TypeError} assigned value cannot be safely cast to the target array data type
+* @throws {TypeError} target array must have a supported data type
+* @returns {boolean} boolean indicating whether assignment succeeded
+*/
+function setElements( target, property, value, ctx ) {
+	var tdt;
+	var vdt;
+	var idx;
+	var err;
+	var v;
+
+	idx = prop2array( property, ctx.cache );
+	tdt = ctx.dtype || 'generic';
+	if ( isCollection( value ) ) {
+		// When handling collections, we delegate to implementation APIs (see below) to perform argument validation (e.g., ensuring a (mostly) safe cast, broadcast compatibility, etc), so we just reassign the value here:
+		v = value;
+	} else {
+		// When provided a "scalar", we need to check whether the value can be safely cast to the target array data type:
+		err = ctx.validator( value, tdt );
+		if ( err ) {
+			throw err;
+		}
+		if ( ctx.preSetElement ) {
+			v = ctx.preSetElement( value );
+		} else {
+			v = value;
+		}
+		// As the scalar can be safely cast, convert the scalar to an array having the same data type as the target array to allow for broadcasting during assignment:
+		v = scalar2array( v, tdt );
+		vdt = tdt;
+	}
+	if ( idx.type === 'int' ) {
+		try {
+			put( target, idx.data, v ); // note: defer to `put` for ensuring a mostly safe cast
+		} catch ( err ) {
+			throw new err.constructor( errMessage( err.message ) );
+		}
+		return true;
+	}
+	if ( idx.type === 'bool' ) {
+		try {
+			place( target, idx.data, v, {
+				'mode': 'strict_broadcast'
+			});
+		} catch ( err ) {
+			throw new err.constructor( errMessage( err.message ) );
+		}
+		return true;
+	}
+	if ( vdt === void 0 ) {
+		vdt = dtype( value ) || 'generic';
+	}
+	// Safe casts are always allowed and allow same kind casts (i.e., downcasts) only when the target array data type is floating-point...
+	if ( !isMostlySafeCast( vdt, tdt ) ) {
+		throw new TypeError( format( 'invalid operation. Assigned value cannot be safely cast to the target array data type. Data types: [%s, %s].', vdt, tdt ) );
+	}
+	// When performing a real-to-complex assignment, interpret the real-valued array as containing real components with implied imaginary components equal to zero and explicitly convert to a complex-valued array...
+	if ( isComplexDataType( tdt ) && isRealDataType( vdt ) ) {
+		v = convert( v, tdt );
+	}
+	if ( idx.type === 'mask' ) {
+		// NOTE: we intentionally deviate from boolean array indexing here and interpret the mask as applying to both the target and values array, thus requiring that the assigned value array be broadcast compatible with the target array and NOT just the selected elements as in boolean array indexing
+		try {
+			where( idx.data, target, v, target, 1, 0 );
+		} catch ( err ) {
+			throw new err.constructor( errMessage( err.message ) );
+		}
+		return true;
+	}
+	throw new Error( format( 'invalid operation. Unrecognized array index type. Value: `%s`.', idx.type ) );
+}
+
+
+// EXPORTS //
+
+module.exports = setElements;

package/lib/set_slice.js

@@ -40,6 +40,7 @@ var errMessage = require( './error_message.js' );
 * @param {Object} ctx - context object
 * @param {string} ctx.dtype - array data type
 * @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @param {Function} ctx.validator - function for validating new values
 * @throws {Error} invalid slice operation
 * @throws {RangeError} slice exceeds array bounds
 * @throws {Error} assigned value must be broadcast compatible with target array view
@@ -67,14 +68,14 @@ function setSlice( target, property, value, receiver, ctx ) {
 			throw err;
 		}
 		// As the scalar can be safely cast, convert the scalar to an array having the same data type as the target array to allow for broadcasting during slice assignment:
-		v = scalar2array( value, ctx.dtype );
+		v = scalar2array( value, ctx.dtype || 'generic' );
 	}
 	try {
 		sliceAssign( v, receiver, s, ctx.strict );
-		return true;
 	} catch ( err ) {
 		throw new err.constructor( errMessage( err.message ) );
 	}
+	return true;
 }
 
 

package/lib/validator.js

@@ -22,10 +22,12 @@
 
 var isNumber = require( '@stdlib/assert-is-number' ).isPrimitive;
 var isInteger = require( '@stdlib/assert-is-integer' ).isPrimitive;
+var isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive;
 var isComplexLike = require( '@stdlib/assert-is-complex-like' );
 var isRealFloatingDataType = require( '@stdlib/array-base-assert-is-real-floating-point-data-type' );
 var isUnsignedIntegerDataType = require( '@stdlib/array-base-assert-is-unsigned-integer-data-type' );
 var isSignedIntegerDataType = require( '@stdlib/array-base-assert-is-signed-integer-data-type' );
+var isBooleanDataType = require( '@stdlib/array-base-assert-is-boolean-data-type' );
 var isSafeCast = require( '@stdlib/array-base-assert-is-safe-data-type-cast' );
 var minDataType = require( '@stdlib/array-min-dtype' );
 var minSignedIntegerDataType = require( '@stdlib/array-base-min-signed-integer-dtype' );
@@ -52,7 +54,32 @@ function validateGeneric() {
 }
 
 /**
-* Verifies whether a provided value can be safely assigned to an element in an array have a real-valued floating-point data type.
+* Verifies whether a provided value can be safely assigned to an element in an array having a boolean data type.
+*
+* @private
+* @param {*} value - input value
+* @param {string} dtype - array data type
+* @returns {(Error|null)} error object or null
+*
+* @example
+* var err = validateBoolean( true, 'bool' );
+* // returns null
+*
+* @example
+* var Complex128 = require( '@stdlib/complex-float64-ctor' );
+*
+* var err = validateBoolean( new Complex128( 5.0, 6.0 ), 'bool' );
+* // returns <TypeError>
+*/
+function validateBoolean( value, dtype ) {
+	if ( isBoolean( value ) ) {
+		return null;
+	}
+	return new TypeError( format( 'invalid operation. Assigned value cannot be safely cast to the target array data type. Data types: [%s, %s].', typeof value, dtype ) );
+}
+
+/**
+* Verifies whether a provided value can be safely assigned to an element in an array having a real-valued floating-point data type.
 *
 * @private
 * @param {*} value - input value
@@ -64,7 +91,7 @@ function validateGeneric() {
 * // returns null
 *
 * @example
-* var Complex128 = require( '@stdlib/complex-float64' );
+* var Complex128 = require( '@stdlib/complex-float64-ctor' );
 *
 * var err = validateRealFloating( new Complex128( 5.0, 6.0 ), 'float64' );
 * // returns <TypeError>
@@ -80,7 +107,7 @@ function validateRealFloating( value, dtype ) {
 }
 
 /**
-* Verifies whether a provided value can be safely assigned to an element in an array have a complex-valued floating-point data type.
+* Verifies whether a provided value can be safely assigned to an element in an array having a complex-valued floating-point data type.
 *
 * @private
 * @param {*} value - input value
@@ -88,7 +115,7 @@ function validateRealFloating( value, dtype ) {
 * @returns {(Error|null)} error object or null
 *
 * @example
-* var Complex128 = require( '@stdlib/complex-float64' );
+* var Complex128 = require( '@stdlib/complex-float64-ctor' );
 *
 * var err = validateComplexFloating( new Complex128( 5.0, 6.0 ), 'complex128' );
 * // returns null
@@ -105,7 +132,7 @@ function validateComplexFloating( value, dtype ) {
 }
 
 /**
-* Verifies whether a provided value can be safely assigned to an element in an array have a signed integer data type.
+* Verifies whether a provided value can be safely assigned to an element in an array having a signed integer data type.
 *
 * @private
 * @param {*} value - input value
@@ -139,7 +166,7 @@ function validateSignedInteger( value, dtype ) {
 }
 
 /**
-* Verifies whether a provided value can be safely assigned to an element in an array have an unsigned integer data type.
+* Verifies whether a provided value can be safely assigned to an element in an array having an unsigned integer data type.
 *
 * @private
 * @param {*} value - input value
@@ -201,6 +228,9 @@ function validator( dtype ) {
 	if ( isSignedIntegerDataType( dtype ) ) {
 		return validateSignedInteger;
 	}
+	if ( isBooleanDataType( dtype ) ) {
+		return validateBoolean;
+	}
 	// Case: isComplexDataType( dtype ) === true
 	return validateComplexFloating;
 }