Auto-generated commit

stdlib-bot · stdlib-bot · commit d22cdc60a744 · 2025-05-16T11:59:04.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@
 
 ### Features
 
+-   [`b2cefbe`](https://github.com/stdlib-js/stdlib/commit/b2cefbe2b2192cb705b85c43ffac2f57ca782c42) - add custom `valueOf` method
 -   [`848f226`](https://github.com/stdlib-js/stdlib/commit/848f226d45aad2d627453c8306ae192c75338ac3) - add `factory` method
 -   [`916b907`](https://github.com/stdlib-js/stdlib/commit/916b9073d6cf82262233e835f9bbbaca26d685f0) - add `ndarray/vector/ctor`
 -   [`9b0d852`](https://github.com/stdlib-js/stdlib/commit/9b0d8520418c2788d20d446b6a39471b6393a787) - add `loopOrder` to namespace
@@ -390,6 +391,8 @@ A total of 15 issues were closed in this release:
 
 <details>
 
+-   [`01544ae`](https://github.com/stdlib-js/stdlib/commit/01544aef20deb6e2b8c6826462cd29916ce3e45b) - **test:** add tests _(by Athan Reines)_
+-   [`b2cefbe`](https://github.com/stdlib-js/stdlib/commit/b2cefbe2b2192cb705b85c43ffac2f57ca782c42) - **feat:** add custom `valueOf` method _(by Athan Reines)_
 -   [`848f226`](https://github.com/stdlib-js/stdlib/commit/848f226d45aad2d627453c8306ae192c75338ac3) - **feat:** add `factory` method _(by Athan Reines)_
 -   [`d30fed0`](https://github.com/stdlib-js/stdlib/commit/d30fed0b3516e362f957aa15d1521b3b3fe6cefd) - **docs:** update examples _(by Athan Reines)_
 -   [`916b907`](https://github.com/stdlib-js/stdlib/commit/916b9073d6cf82262233e835f9bbbaca26d685f0) - **feat:** add `ndarray/vector/ctor` _(by Athan Reines)_
diff --git a/base/ctor/benchmark/benchmark.js b/base/ctor/benchmark/benchmark.js
@@ -1275,3 +1275,71 @@ bench( pkg+':toString', function benchmark( b ) {
 	b.pass( 'benchmark finished' );
 	b.end();
 });
+
+bench( pkg+':valueOf:ndims=0', function benchmark( b ) {
+	var strides;
+	var buffer;
+	var offset;
+	var shape;
+	var order;
+	var out;
+	var v;
+	var i;
+
+	buffer = [ 1.0 ];
+	shape = [];
+	strides = [ 0 ];
+	offset = 0;
+	order = 'row-major';
+
+	out = ndarray( 'generic', buffer, shape, strides, offset, order );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		buffer[ 0 ] = i;
+		v = out.valueOf();
+		if ( typeof v !== 'number' ) {
+			b.fail( 'should return a number' );
+		}
+	}
+	b.toc();
+	if ( typeof v !== 'number' ) {
+		b.fail( 'should return a number' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':valueOf:ndims>=1', function benchmark( b ) {
+	var strides;
+	var buffer;
+	var offset;
+	var shape;
+	var order;
+	var out;
+	var v;
+	var i;
+
+	buffer = [ 1.0, 2.0 ];
+	shape = [ 2 ];
+	strides = [ 1 ];
+	offset = 0;
+	order = 'row-major';
+
+	out = ndarray( 'generic', buffer, shape, strides, offset, order );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		buffer[ i%buffer.length ] = i;
+		v = out.valueOf();
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( typeof v !== 'object' ) {
+		b.fail( 'should return an object' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
diff --git a/base/ctor/lib/main.js b/base/ctor/lib/main.js
@@ -38,6 +38,7 @@ var igetValue = require( './iget.js' );
 var isetValue = require( './iset.js' );
 var setValue = require( './set.js' );
 var getValue = require( './get.js' );
+var valueOf = require( './valueof.js' ); // eslint-disable-line stdlib/no-redeclare
 var toJSON = require( './tojson.js' );
 var toString = require( './tostring.js' ); // eslint-disable-line stdlib/no-redeclare
 var meta2dataview = require( './meta2dataview.js' );
@@ -569,6 +570,42 @@ setReadOnly( ndarray.prototype, 'toString', toString );
 */
 setReadOnly( ndarray.prototype, 'toJSON', toJSON );
 
+/**
+* Converts an ndarray instance to a primitive value.
+*
+* ## Notes
+*
+* -   Only zero-dimensional ndarrays are converted to a primitive value. For ndarray instances having one or more dimensions, the method returns the `this` value, as is the default behavior for objects.
+*
+* @name valueOf
+* @memberof ndarray.prototype
+* @type {Function}
+* @returns {(*|ndarray)} result
+*
+* @example
+* var buffer = [ 3.14 ];
+* var shape = [];
+* var strides = [ 0 ];
+* var offset = 0;
+*
+* var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
+*
+* var v = x.valueOf();
+* // returns 3.14
+*
+* @example
+* var buffer = [ 3.14 ];
+* var shape = [ 1 ];
+* var strides = [ 1 ];
+* var offset = 0;
+*
+* var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
+*
+* var v = x.valueOf();
+* // returns <ndarray>
+*/
+setReadOnly( ndarray.prototype, 'valueOf', valueOf );
+
 /**
 * Serializes ndarray meta data to a `DataView`.
 *
diff --git a/base/ctor/lib/valueof.js b/base/ctor/lib/valueof.js
@@ -0,0 +1,46 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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 //
+
+/**
+* Converts an ndarray instance to a primitive value.
+*
+* ## Notes
+*
+* -   Only zero-dimensional ndarrays are converted to a primitive value. For ndarray instances having one or more dimensions, the method returns the `this` value, as is the default behavior for objects.
+*
+* @private
+* @returns {(*|ndarray)} result
+*/
+function valueOf() { // eslint-disable-line stdlib/no-redeclare
+	/* eslint-disable no-invalid-this */
+	if ( this._ndims === 0 ) {
+		return this.iget();
+	}
+	return this;
+
+	/* eslint-enable no-invalid-this */
+}
+
+
+// EXPORTS //
+
+module.exports = valueOf;
diff --git a/base/ctor/test/test.js b/base/ctor/test/test.js
@@ -3551,7 +3551,9 @@ tape( 'an ndarray has a custom `toString()` method (large array)', function test
 	var arr;
 
 	dtype = 'generic';
-	buffer = new Array( 1e4 );
+
+	// Intentionally create a sparse array:
+	buffer = new Array( 1e4 ); // eslint-disable-line stdlib/no-new-array
 	shape = [ buffer.length ];
 	order = 'row-major';
 	strides = [ 1 ];
@@ -3817,6 +3819,68 @@ tape( 'an ndarray has a custom `toJSON()` method (0d)', function test( t ) {
 	t.end();
 });
 
+tape( 'an ndarray has a custom `valueOf()` method (0d)', function test( t ) {
+	var expected;
+	var strides;
+	var actual;
+	var buffer;
+	var offset;
+	var dtype;
+	var order;
+	var shape;
+	var arr;
+
+	dtype = 'generic';
+	buffer = [ 3.14 ];
+	shape = [];
+	order = 'row-major';
+	strides = [ 0 ];
+	offset = 0;
+
+	arr = ndarray( dtype, buffer, shape, strides, offset, order );
+
+	t.strictEqual( hasOwnProp( arr, 'valueOf' ), false, 'does not have own property' );
+	t.strictEqual( hasProp( arr, 'valueOf' ), true, 'has property' );
+	t.strictEqual( isFunction( arr.valueOf ), true, 'has method' );
+
+	expected = 3.14;
+	actual = arr.valueOf();
+	t.strictEqual( actual, expected, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'an ndarray has a custom `valueOf()` method (>=1d)', function test( t ) {
+	var expected;
+	var strides;
+	var actual;
+	var buffer;
+	var offset;
+	var dtype;
+	var order;
+	var shape;
+	var arr;
+
+	dtype = 'generic';
+	buffer = [ 1.0, 2.0 ];
+	shape = [ 2 ];
+	order = 'row-major';
+	strides = [ 0 ];
+	offset = 0;
+
+	arr = ndarray( dtype, buffer, shape, strides, offset, order );
+
+	t.strictEqual( hasOwnProp( arr, 'valueOf' ), false, 'does not have own property' );
+	t.strictEqual( hasProp( arr, 'valueOf' ), true, 'has property' );
+	t.strictEqual( isFunction( arr.valueOf ), true, 'has method' );
+
+	expected = arr;
+	actual = arr.valueOf();
+	t.strictEqual( actual, expected, 'returns expected value' );
+
+	t.end();
+});
+
 tape( 'an ndarray has a protocol method for serializing meta data to a DataView', function test( t ) {
 	/* eslint-disable no-underscore-dangle */
 	var expected;
diff --git a/vector/ctor/lib/main.js b/vector/ctor/lib/main.js
@@ -165,7 +165,7 @@ function arraybuffer2vector( dtype, buffer, length, stride, byteOffset, order, o
 	N = length * stride;
 
 	// Adjust the byte offset to point to the element marking the beginning of the view:
-	if ( stride < 0 ) {
+	if ( stride < 0 ) { // TODO: the following is effectively unreachable code, as provided strides are never anything other than unity; however, we keep this around in the event that we want to extract this function to a separate package and would like to maintain generality
 		N *= -1;
 		o -= N * bytesPerElement( dtype );
 	}
@@ -483,6 +483,9 @@ function vector() {
 	if ( nargs === 2 ) {
 		// Case: vector( dtype, options )
 		if ( isDataType( arg0 ) ) {
+			if ( arg1 === null ) {
+				throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', arg1 ) );
+			}
 			return vectorWithDType( 0, arg0, arg1 );
 		}
 		// Case: vector( arg0, dtype )
@@ -501,6 +504,9 @@ function vector() {
 			return arraybuffer2vector( DEFAULT_DTYPE, arg0, (arg0.byteLength-arg1)/bytesPerElement( DEFAULT_DTYPE ), 1, arg1, DEFAULT_ORDER );
 		}
 		// Case: vector( arg0, options )
+		if ( arg1 === null ) {
+			throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', arg1 ) );
+		}
 		out = vectorWithDType( arg0, DEFAULT_DTYPE, arg1 );
 		if ( out === null ) {
 			throw new TypeError( format( 'invalid argument. First argument must be a length, ArrayBuffer, typed array, array-like object, or iterable. Value: `%s`.', arg0 ) );
@@ -523,6 +529,9 @@ function vector() {
 		}
 		// Case: vector( arg0, dtype, options )
 		if ( isDataType( arg1 ) ) {
+			if ( arg2 === null ) {
+				throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', arg2 ) );
+			}
 			out = vectorWithDType( arg0, arg1, arg2 );
 			if ( out === null ) {
 				throw new TypeError( format( 'invalid argument. First argument must be a length, ArrayBuffer, typed array, array-like object, or iterable. Value: `%s`.', arg0 ) );
@@ -536,15 +545,15 @@ function vector() {
 		if ( !isNonNegativeInteger( arg1 ) ) {
 			throw new TypeError( format( 'invalid argument. Byte offset must be a nonnegative integer. Value: `%s`.', arg1 ) );
 		}
-		// Case: vector( ArrayBuffer, byteOffset, options )
-		if ( isPlainObject( arg2 ) ) {
-			return arraybuffer2vector( DEFAULT_DTYPE, arg0, (arg0.byteLength-arg1)/bytesPerElement( DEFAULT_DTYPE ), 1, arg1, resolveOrder( arg2 ), arg2 );
-		}
 		// Case: vector( ArrayBuffer, byteOffset, length )
-		if ( !isNonNegativeInteger( arg2 ) ) {
-			throw new TypeError( format( 'invalid argument. Length must be a nonnegative integer. Value: `%s`.', arg2 ) );
+		if ( isNonNegativeInteger( arg2 ) ) {
+			return arraybuffer2vector( DEFAULT_DTYPE, arg0, arg2, 1, arg1, DEFAULT_ORDER );
+		}
+		// Case: vector( ArrayBuffer, byteOffset, options )
+		if ( arg2 === null ) {
+			throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', arg2 ) );
 		}
-		return arraybuffer2vector( DEFAULT_DTYPE, arg0, arg2, 1, arg1, DEFAULT_ORDER );
+		return arraybuffer2vector( DEFAULT_DTYPE, arg0, (arg0.byteLength-arg1)/bytesPerElement( DEFAULT_DTYPE ), 1, arg1, resolveOrder( arg2 ), arg2 );
 	}
 	arg3 = arguments[ 3 ];
 
diff --git a/vector/ctor/test/test.js b/vector/ctor/test/test.js
@@ -37,5 +37,3 @@ tape( 'attached to the main export is a `factory` method', function test( t ) {
 	t.strictEqual( isMethod( vector, 'factory' ), true, 'returns expected value' );
 	t.end();
 });
-
-// FIXME: add tests (see array/typed and ndarray/zeros)
diff --git a/vector/ctor/test/test.main.js b/vector/ctor/test/test.main.js
