Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,7 +4,17 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2025-05-08)
+## Unreleased (2025-05-16)
+
+<section class="features">
+
+### Features
+
+-   [`b2cefbe`](https://github.com/stdlib-js/stdlib/commit/b2cefbe2b2192cb705b85c43ffac2f57ca782c42) - add custom `valueOf` method
+
+</section>
+
+<!-- /.features -->
 
 <section class="bug-fixes">
 
@@ -23,6 +33,7 @@
 
 <details>
 
+-   [`b2cefbe`](https://github.com/stdlib-js/stdlib/commit/b2cefbe2b2192cb705b85c43ffac2f57ca782c42) - **feat:** add custom `valueOf` method _(by Athan Reines)_
 -   [`7321e29`](https://github.com/stdlib-js/stdlib/commit/7321e294d995d496b35f24f253055190ae6a78d5) - **refactor:** use base assertion utility _(by Athan Reines)_
 -   [`25abfc6`](https://github.com/stdlib-js/stdlib/commit/25abfc67b400f646304fa1f10b239a051f6569f6) - **refactor:** support non-built-in shape and strides objects _(by Athan Reines)_
 -   [`5e2bbef`](https://github.com/stdlib-js/stdlib/commit/5e2bbef14efd5937e23047c01af0e740e6cbd4f6) - **fix:** add missing boolean array support _(by Athan Reines)_

CONTRIBUTORS

@@ -174,6 +174,7 @@ Utkarsh <http://utkarsh11105@gmail.com>
 Utkarsh Raj <rajutkarsh2505@gmail.com>
 UtkershBasnet <119008923+UtkershBasnet@users.noreply.github.com>
 Vaibhav Patel <98279986+noobCoderVP@users.noreply.github.com>
+Vara Rahul Rajana <123227543+rajanarahul93@users.noreply.github.com>
 Varad Gupta <varadgupta21@gmail.com>
 Vinit Pandit <106718914+MeastroZI@users.noreply.github.com>
 Vivek Maurya <vm8118134@gmail.com>

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();
+});

dist/index.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`.
 *

dist/index.js.map

@@ -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;

lib/main.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;