@stdlib/array-to-fancy 0.1.0

package/lib/is_integer_string.js

@@ -0,0 +1,51 @@
+/**
+* @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 isString = require( '@stdlib/assert-is-string' ).isPrimitive;
+var RE_INTEGER = require( './re_integer.js' );
+
+
+// MAIN //
+
+/**
+* Tests if an indexing expression is an integer.
+*
+* @private
+* @param {(string|symbol)} prop - property name
+* @returns {boolean} result
+*
+* @example
+* var out = isIntegerString( '1' );
+* // returns true
+*
+* @example
+* var out = isIntegerString( ':' );
+* // returns false
+*/
+function isIntegerString( prop ) {
+	return ( isString( prop ) && RE_INTEGER.test( prop ) );
+}
+
+
+// EXPORTS //
+
+module.exports = isIntegerString;

package/lib/main.js

@@ -0,0 +1,68 @@
+/**
+* @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 factory = require( './factory.js' );
+
+
+// MAIN //
+
+/**
+* Converts an array to an object supporting fancy indexing.
+*
+* @name array2fancy
+* @type {Function}
+* @param {ArrayLike} x - input array
+* @param {Options} [options] - function options
+* @param {boolean} [options.strict=false] - boolean indicating whether to enforce strict bounds checking
+* @param {Function} [options.cache] - cache for resolving array index objects
+* @throws {TypeError} first argument must be array-like
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {ArrayLike} fancy array
+*
+* @example
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+*
+* var y = array2fancy( x );
+* // returns <Array>
+*
+* var z = y[ '1::2' ];
+* // returns [ 2, 4, 6 ]
+*
+* var len = z.length;
+* // returns 3
+*
+* var v = z[ 0 ];
+* // returns 2
+*
+* v = z[ 1 ];
+* // returns 4
+*
+* v = z[ 2 ];
+* // returns 6
+*/
+var array2fancy = factory();
+
+
+// EXPORTS //
+
+module.exports = array2fancy;

package/lib/prop2array.js

@@ -0,0 +1,69 @@
+/**
+* @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 trim = require( '@stdlib/string-base-trim' );
+var format = require( '@stdlib/string-format' );
+
+
+// FUNCTIONS //
+
+/**
+* Extracts an array index identifier from an array index indexing expression.
+*
+* @private
+* @param {string} str - input string
+* @returns {string} identifier
+*
+* @example
+* var str = 'ArrayIndex<0>';
+*
+* var id = getIdentifier( str );
+* // returns '0'
+*/
+function getIdentifier( str ) {
+	return str.substring( 11, str.length-1 ); // ArrayIndex<XX> => XX
+}
+
+
+// MAIN //
+
+/**
+* Converts an indexing expression to an array index.
+*
+* @private
+* @param {string} property - property name
+* @param {Object} cache - cache for resolving array index objects
+* @throws {Error} invalid array index
+* @returns {(Object|null)} index object (or null)
+*/
+function prop2array( property, cache ) {
+	var o = cache.get( getIdentifier( trim( property ) ) );
+	if ( o === null ) {
+		throw new Error( format( 'invalid operation. Unable to resolve array index. Value: `%s`.', property ) );
+	}
+	return o;
+}
+
+
+// EXPORTS //
+
+module.exports = prop2array;

package/lib/prop2slice.js

@@ -0,0 +1,163 @@
+/**
+* @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 trim = require( '@stdlib/string-base-trim' );
+var seq2slice = require( '@stdlib/slice-base-seq2slice' );
+var str2slice = require( '@stdlib/slice-base-str2slice' );
+var startsWith = require( '@stdlib/string-base-starts-with' );
+var format = require( '@stdlib/string-format' );
+var RE_SUBSEQ = require( './re_subseq.js' );
+
+
+// FUNCTIONS //
+
+/**
+* Tests if an indexing expression is a serialized Slice object.
+*
+* @private
+* @param {string} prop - property name
+* @returns {boolean} result
+*
+* @example
+* var out = isSlice( 'Slice(null,null,1)' );
+* // returns true
+*
+* @example
+* var out = isSlice( ':' );
+* // returns false
+*/
+function isSlice( prop ) {
+	return (
+		prop[ 0 ] === 'S' &&
+		startsWith( prop, 'Slice(', 0 ) &&
+		prop[ prop.length-1 ] === ')'
+	);
+}
+
+/**
+* Tests if an indexing expression is a subsequence.
+*
+* @private
+* @param {string} prop - property name
+* @returns {boolean} result
+*
+* @example
+* var out = isSubsequence( '::-2' );
+* // returns true
+*
+* @example
+* var out = isSubsequence( '-2' );
+* // returns false
+*/
+function isSubsequence( prop ) {
+	// TODO: consider whether to make this check more robust (e.g., should we actually throw if someone tries to access `foo:bar`? If we make this check more exact, how would we distinguish between a non-existent `foo:bar` property and an actual error in the subsequence string?)
+	return RE_SUBSEQ.test( prop );
+}
+
+/**
+* Parses a serialized Slice object.
+*
+* @private
+* @param {string} raw - original unprocessed input string
+* @param {string} str - serialized Slice object
+* @throws {Error} invalid slice operation
+* @returns {Slice} Slice object
+*
+* @example
+* var s = parseSlice( '  Slice(null,null,1)  ', 'Slice(null,null,1)' );
+* // returns <Slice>
+*/
+function parseSlice( raw, str ) {
+	var s = str2slice( str );
+	if ( s === null ) {
+		throw new Error( format( 'invalid operation. Unsupported slice operation. Value: `%s`.', raw ) );
+	}
+	return s;
+}
+
+/**
+* Parses a subsequence string.
+*
+* @private
+* @param {string} raw - original unprocessed input string
+* @param {string} str - subsequence string
+* @param {NonNegativeInteger} max - index upper bound
+* @param {boolean} strict - boolean indicating whether to enforce strict bounds checking
+* @throws {Error} invalid slice operation
+* @throws {RangeError} slice exceeds array bounds
+* @returns {Slice} Slice object
+*
+* @example
+* var s = parseSubsequence( ' ::-2 ', '::-2', 10, false );
+* // returns <Slice>
+*/
+function parseSubsequence( raw, str, max, strict ) {
+	var s = seq2slice( str, max, true );
+	if ( s.code ) {
+		if ( s.code === 'ERR_SLICE_INVALID_INCREMENT' ) {
+			throw new Error( format( 'invalid operation. A subsequence increment must be a non-zero integer. Value: `%s`.', raw ) );
+		}
+		if ( s.code === 'ERR_SLICE_INVALID_SUBSEQUENCE' ) {
+			throw new Error( format( 'invalid operation. Unsupported slice operation. Value: `%s`.', raw ) );
+		}
+		// NOTE: the following error check must come last due to fall-through when in non-strict mode...
+		if ( s.code === 'ERR_SLICE_OUT_OF_BOUNDS' ) {
+			if ( strict ) {
+				throw new RangeError( format( 'invalid operation. Slice exceeds array bounds.' ) );
+			}
+			// Repeat parsing, this time allowing for out-of-bounds slices:
+			s = seq2slice( str, max, false );
+		}
+	}
+	return s;
+}
+
+
+// MAIN //
+
+/**
+* Converts an indexing expression to a Slice object.
+*
+* @private
+* @param {Object} target - target object
+* @param {string} property - property name
+* @param {boolean} strict - boolean indicating whether to enforce strict bounds checking
+* @throws {Error} invalid slice operation
+* @throws {RangeError} slice exceeds array bounds
+* @returns {(Slice|null)} slice object (or null)
+*/
+function prop2slice( target, property, strict ) {
+	var prop = trim( property );
+	if ( isSlice( prop ) ) {
+		return parseSlice( property, prop );
+	}
+	if ( isSubsequence( prop ) ) {
+		return parseSubsequence( property, prop, target.length, strict );
+	}
+	// Everything else (including undefined/non-existent properties):
+	return null;
+}
+
+
+// EXPORTS //
+
+module.exports = prop2slice;

package/lib/re_array_index.js

@@ -0,0 +1,47 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Regular expression for testing whether a string is a serialized array index.
+*
+* @private
+* @name RE_ARRAY_INDEX
+* @type {RegExp}
+*
+* @example
+* var bool = RE_ARRAY_INDEX.test( 'ArrayIndex<0>' );
+* // returns true
+*
+* @example
+* var bool = RE_ARRAY_INDEX.test( '0' );
+* // returns false
+*
+* @example
+* var bool = RE_ARRAY_INDEX.test( 'Slice(0,10,2)' );
+* // returns false
+*/
+var RE_ARRAY_INDEX = /\s*ArrayIndex<[^>]+>\s*/;
+
+
+// EXPORTS //
+
+module.exports = RE_ARRAY_INDEX;

package/lib/re_integer.js

@@ -0,0 +1,47 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Regular expression for testing whether a string is an integer string.
+*
+* @private
+* @name RE_INTEGER
+* @type {RegExp}
+*
+* @example
+* var bool = RE_INTEGER.test( '10' );
+* // returns true
+*
+* @example
+* var bool = RE_INTEGER.test( '-1' );
+* // returns true
+*
+* @example
+* var bool = RE_INTEGER.test( '0:10:2' );
+* // returns false
+*/
+var RE_INTEGER = /^-?[0-9]+$/;
+
+
+// EXPORTS //
+
+module.exports = RE_INTEGER;

package/lib/re_subseq.js

@@ -0,0 +1,47 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Regular expression for testing whether a string is a subsequence string.
+*
+* @private
+* @name RE_SUBSEQ
+* @type {RegExp}
+*
+* @example
+* var bool = RE_SUBSEQ.test( '0:10:2' );
+* // returns true
+*
+* @example
+* var bool = RE_SUBSEQ.test( '0' );
+* // returns false
+*
+* @example
+* var bool = RE_SUBSEQ.test( 'Slice(0,10,2)' );
+* // returns false
+*/
+var RE_SUBSEQ = /:/;
+
+
+// EXPORTS //
+
+module.exports = RE_SUBSEQ;

package/lib/resolve_index.js

@@ -0,0 +1,66 @@
+/**
+* @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 normalizeIndex = require( '@stdlib/ndarray-base-normalize-index' );
+var format = require( '@stdlib/string-format' );
+
+
+// MAIN //
+
+/**
+* Resolves an integer index from an integer string.
+*
+* @private
+* @param {string} str - integer string
+* @param {NonNegativeInteger} max - index upper bound (exclusive)
+* @param {boolean} strict - boolean indicating whether to enforce strict bounds checking
+* @throws {RangeError} index exceeds array bounds
+* @returns {integer} integer index
+*
+* @example
+* var idx = resolveIndex( '-1', 10, false );
+* // returns 9
+*
+* @example
+* var idx = resolveIndex( '-20', 10, false );
+* // returns -20
+*/
+function resolveIndex( str, max, strict ) {
+	var idx;
+	var i;
+
+	idx = parseInt( str, 10 );
+	i = normalizeIndex( idx, max-1 );
+	if ( i === -1 ) {
+		if ( strict ) {
+			throw new RangeError( format( 'invalid operation. Index exceeds array bounds.' ) );
+		}
+		// Return the non-normalized index, as this should fallback to default property handling and returning "undefined":
+		return idx;
+	}
+	return i;
+}
+
+
+// EXPORTS //
+
+module.exports = resolveIndex;

package/lib/set.js

@@ -0,0 +1,86 @@
+/**
+* @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 isString = require( '@stdlib/assert-is-string' ).isPrimitive;
+var hasProperty = require( '@stdlib/assert-has-property' );
+var isIntegerString = require( './is_integer_string.js' );
+var setElement = require( './set_element.js' );
+var setValue = require( './set_value.js' );
+var setSlice = require( './set_slice.js' );
+
+
+// MAIN //
+
+/**
+* Returns a trap for setting property values.
+*
+* @private
+* @param {Object} ctx - context object
+* @param {Function} ctx.setter - accessor for setting array elements
+* @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
+* @param {Function} ctx.setter - accessor for setting array elements
+* @param {(Function|null)} ctx.preSetElement - function for normalizing new values (if necessary)
+* @returns {Function} handler
+*/
+function factory( ctx ) {
+	return set;
+
+	/**
+	* Trap for setting property values.
+	*
+	* @private
+	* @param {Object} target - target object
+	* @param {(string|symbol)} property - property name
+	* @param {*} value - new value
+	* @param {Object} receiver - the proxy object or an object inheriting from the proxy
+	* @throws {Error} invalid slice operation
+	* @throws {Error} assigned value must be broadcast compatible with output array view
+	* @throws {TypeError} assigned value cannot be safely cast to the output array data type
+	* @throws {TypeError} slice exceeds array bounds
+	* @throws {TypeError} index exceeds array bounds
+	* @returns {boolean} boolean indicating whether assignment succeeded
+	*/
+	function set( target, property, value, receiver ) {
+		var out;
+
+		// Note that we need to check for an integer string *before* checking for an own property, as we want to explicitly handle *all* indexed properties, not just negative integers, in order to perform assignment validation...
+		if ( isIntegerString( property ) ) {
+			return setElement( target, property, value, ctx );
+		}
+		if ( hasProperty( property ) || !isString( property ) ) {
+			return setValue( target, property, value, ctx );
+		}
+		out = setSlice( target, property, value, receiver, ctx );
+		if ( out ) {
+			return out;
+		}
+		// If we were unsuccessful (e.g., due to an invalid subsequence, etc), set the "property" in the same way as would any normal property (e.g., if an indexing expression is an invalid subsequence, assign as would a regular property: `i = 'a:b:c'` => `x[i] = 1` => `v = x[i]` => `v === 1`):
+		return setValue( target, property, value, ctx );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;