refactor: add implementation and examples

Author: kgryte

lib/node_modules/@stdlib/ndarray/nested/examples/0d.js

@@ -20,7 +20,7 @@
 
 'use strict';
 
-var S = require( '@stdlib/slice/ctor' );
+var E = require( '@stdlib/slice/multi' );
 var NestedArray = require( './../lib' );
 
 var buffer = [ 6 ];
@@ -47,16 +47,16 @@ console.log( 'x[] = %d', x.get() );
 // => 'x[] = 10'
 
 // Use an empty slice to create a separate array view:
-var y1 = x[ S() ];
+var y1 = x[ E() ];
 console.log( y1.get() );
-// throws <TypeError>
+// => 10
 
 // Use alternative syntax:
 var y2 = x[ [] ];
 console.log( y2.get() );
-// throws <TypeError>
+// => 10
 
 // Use alternative syntax:
 var y3 = x[ '' ];
 console.log( y3.get() );
-// throws <TypeError>
+// => 10

lib/node_modules/@stdlib/ndarray/nested/examples/1d.js

@@ -51,11 +51,15 @@ console.log( 'x[2] = %d', x.get( 2 ) );
 var _ = void 0;
 
 // Use a slice to create a view on the original ndarray:
-var y1 = x[ [ S(0,_,2) ] ];
+var y1 = x[ S(0,_,2) ];
 console.log( toArray( y1 ) );
-// throws <TypeError>
+// => [ 1, 10, 5 ]
 
 // Use alternative syntax:
 var y2 = x[ '::-2' ];
 console.log( toArray( y2 ) );
-// throws <TypeError>
+// => [ 6, 4, 2 ]
+
+var y3 = x[ 3 ];
+console.log( y3.get() );
+// => 4

lib/node_modules/@stdlib/ndarray/nested/examples/3d.js

@@ -67,9 +67,9 @@ var _ = void 0;
 // Use slices to create a view on the original ndarray:
 var y1 = x[ 1 ][ S(0,_,2) ];
 console.log( toArray( y1 ) );
-// => [ [ [ 9, 10 ], [ 13, 100 ] ] ]
+// => [ [ 9, 10 ], [ 13, 100 ] ]
 
 // Use alternative syntax:
 var y2 = x[ 1 ][ '0::2' ];
 console.log( toArray( y2 ) );
-// => [ [ [ 9, 10 ], [ 13, 100 ] ] ]
+// => [ [ 9, 10 ], [ 13, 100 ] ]

lib/node_modules/@stdlib/ndarray/nested/examples/index.js

@@ -70,3 +70,8 @@ console.log( toArray( y2 ) );
 var y3 = x[ S(_,_,-2) ];
 console.log( toArray( y3 ) );
 // => [ [ 7, 20 ], [ 3, 4 ] ]
+
+// Get the second row:
+var y4 = x[ 1 ];
+console.log( toArray( y4 ) );
+// => [ 5, 6 ]

lib/node_modules/@stdlib/ndarray/nested/lib/array_options.js

@@ -0,0 +1,39 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 //
+
+/**
+* Returns array creation options.
+*
+* @private
+* @returns {Object} options
+*/
+function options() {
+	return {
+		// Default to always returning read-only arrays:
+		'readonly': true
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = options;

lib/node_modules/@stdlib/ndarray/nested/lib/empty.js

@@ -0,0 +1,56 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 buffer = require( '@stdlib/ndarray/base/buffer' );
+var zeros = require( '@stdlib/array/base/zeros' );
+var options = require( './array_options.js' );
+
+
+// MAIN //
+
+/**
+* Returns an empty n-dimensional ndarray.
+*
+* @private
+* @param {Function} ctor - ndarray constructor
+* @param {string} dtype - array data type
+* @param {NonNegativeIntegerArray} shape - array shape
+* @param {string} order - layout order
+* @returns {ndarray} empty ndarray
+*/
+function empty( ctor, dtype, shape, order ) {
+	var strides;
+	var ndims;
+
+	ndims = shape.length;
+	if ( ndims === 0 ) {
+		strides = [ 0 ];
+	} else {
+		strides = zeros( ndims );
+	}
+	return new ctor( dtype, buffer( dtype, 0 ), shape, strides, 0, order, options() ); // eslint-disable-line max-len
+}
+
+
+// EXPORTS //
+
+module.exports = empty;

lib/node_modules/@stdlib/ndarray/nested/lib/get.0d.js

@@ -0,0 +1,118 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isFunction = require( '@stdlib/assert/is-function' );
+var trim = require( '@stdlib/string/base/trim' );
+var str2multislice = require( '@stdlib/slice/base/str2multislice' );
+var format = require( '@stdlib/string/format' );
+var hasProperty = require( './has_property.js' );
+var options = require( './array_options.js' );
+var RE_INTEGER = require( './re_integer.js' );
+
+
+// MAIN //
+
+/**
+* Trap for retrieving property values.
+*
+* @private
+* @param {Object} target - target object
+* @param {(string|symbol)} property - property name
+* @param {Object} receiver - the proxy object or an object inheriting from the proxy
+* @throws {Error} invalid slice operation
+* @throws {RangeError} number of slice dimensions must match the number of array dimensions
+* @returns {*} result
+*/
+function get( target, property, receiver ) {
+	var dtype;
+	var value;
+	var prop;
+	var ch;
+	var sh;
+	var s;
+	if ( hasProperty( property ) ) {
+		value = target[ property ];
+		if ( isFunction( value ) ) {
+			return wrapper;
+		}
+		return value;
+	}
+	prop = trim( property );
+
+	// Resolve target meta data:
+	dtype = target.dtype;
+	sh = target.shape;
+
+	// Retrieve the first character in order to to detect how a slice operation was specified:
+	ch = prop[ 0 ];
+
+	// Case: multi-slice
+	if ( ch === 'M' ) {
+		// Convert the string to a slice object:
+		s = str2multislice( prop );
+		if ( s === null ) {
+			throw new Error( format( 'invalid operation. Unsupported slice operation. Value: `%s`.', property ) );
+		}
+		// TODO: => @stdlib/ndarray/base/slice: return slice( receiver, s.data );
+
+		// Ensure that we were provided an empty multi-slice:
+		if ( s.ndims !== sh.length ) {
+			throw new RangeError( format( 'invalid operation. Number of array dimensions does not match the number of slice dimensions. Array shape: (%s). Slice dimensions: %u.', sh.join( ',' ), s.ndims ) );
+		}
+	}
+	// Case: non-empty string
+	else if ( prop.length !== 0 ) {
+		// TODO: the following can be generalized by going ahead and parsing the slice string or integer and passing to a functional API which then verifies that s.ndims !== sh.length. We need only retain the error raised for an invalid operation.
+
+		// Case: slice or an integer
+		if ( ch === 'S' || RE_INTEGER.test( prop ) ) {
+			throw new RangeError( format( 'invalid operation. Number of array dimensions does not match the number of slice dimensions. Array shape: (%s). Slice dimensions: %u.', sh.join( ',' ), 1 ) );
+		}
+		throw new Error( format( 'invalid operation. Unsupported slice operation. Value: `%s`.', property ) );
+	}
+	// TODO: => @stdlib/ndarray/base/slice: return slice( receiver, [] );
+
+	// Return an zero-dimensional array view:
+	return new receiver.constructor( dtype, target.data, sh, target.strides, target.offset, target.order, options() ); // eslint-disable-line max-len
+
+	/**
+	* Method wrapper.
+	*
+	* @private
+	* @returns {*} results
+	*/
+	function wrapper() {
+		var args;
+		var i;
+
+		args = [];
+		for ( i = 0; i < arguments.length; i++ ) {
+			args.push( arguments[ i ] );
+		}
+		return value.apply( ( this === receiver ) ? target : this, args ); // eslint-disable-line no-invalid-this
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = get;