diff --git a/lib/node_modules/@stdlib/array/uint64/README.md b/lib/node_modules/@stdlib/array/uint64/README.md index 02da19409141..e5970cff63b2 100644 --- a/lib/node_modules/@stdlib/array/uint64/README.md +++ b/lib/node_modules/@stdlib/array/uint64/README.md @@ -335,6 +335,44 @@ var u = arr.get( 100 ); // returns undefined ``` + + +#### Uint64Array.prototype.reduceRight( reducerFn\[, initialValue] ) + +Applies a provided callback function to each element of the array, in reverse order, passing in the return value from the calculation on the following element and returning the accumulated result upon completion. + +```javascript +var add = require( '@stdlib/number/uint64/base/add' ); + +var arr = new Uint64Array( [ 1, 2, 3 ] ); + +var u = arr.reduceRight( add ); +// returns [ 6n ] +``` + +The reducer function is provided four arguments: + +- **acc**: accumulated result. +- **value**: current array element. +- **index**: current array element index. +- **arr**: the array on which this method was called. + +By default, the function initializes the accumulated result to the last element in the array and passes the second-last array element as `value` during the first invocation of the provided callback. To begin accumulation from a different starting value and pass in the last array element as `value` during the first invocation of the provided callback, provide an `initialValue` argument. + +```javascript +var Number = require( '@stdlib/number/ctor' ); + +function reducer( acc, v ) { + acc += Number( v ); + return acc; +} + +var arr = new Uint64Array( [ 1, 2, 3 ] ); + +var sum = arr.reduceRight( reducer, 2 ); +// returns 8 +``` + #### Uint64Array.prototype.set( value\[, i] ) diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.js new file mode 100644 index 000000000000..a967e8d7006d --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.js @@ -0,0 +1,81 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 bench = require( '@stdlib/bench' ); +var isUint64 = require( '@stdlib/assert/is-uint64' ); +var add = require( '@stdlib/number/uint64/base/add' ); +var Uint64 = require( '@stdlib/number/uint64/ctor' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Uint64Array = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:reduceRight', pkg ), function benchmark( b ) { + var out; + var arr; + var i; + + arr = new Uint64Array( 10 ); + + // Benchmark worst case scenario (i.e., every element is visited and passed to the reducer)... + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = arr.reduceRight( add ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isUint64( out ) ) { + b.fail( 'should return a 64-bit unsigned integer' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::initial_value:reduceRight', pkg ), function benchmark( b ) { + var out; + var arr; + var v; + var i; + + arr = new Uint64Array( 10 ); + + v = new Uint64( 0 ); + + // Benchmark worst case scenario (i.e., every element is visited and passed to the reducer)... + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = arr.reduceRight( add, v ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isUint64( out ) ) { + b.fail( 'should return a 64-bit unsigned integer' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.length.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.length.js new file mode 100644 index 000000000000..702f3f0874f2 --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.reduce_right.length.js @@ -0,0 +1,97 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 bench = require( '@stdlib/bench' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var isUint64 = require( '@stdlib/assert/is-uint64' ); +var add = require( '@stdlib/number/uint64/base/add' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Uint64Array = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var arr = new Uint64Array( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var out; + var i; + + // Benchmark worst case scenario (i.e., every element is visited and passed to the reducer)... + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = arr.reduceRight( add ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isUint64( out ) ) { + b.fail( 'should return a 64-bit unsigned integer' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( format( '%s:reduceRight:len=%d', pkg, len ), f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt index c737fc5bf588..7dd6aa7a67de 100644 --- a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt @@ -299,6 +299,47 @@ [ 2n ] +{{alias}}.prototype.reduceRight( reducerFn[, initialValue] ) + Applies a provided function to each element of the array, in reverse order, + passing in the return value from the calculation on the preceding element + and returning the accumulated result upon completion. + + A reducer function is provided the following arguments: + + - acc: accumulated result. + - value: current array element. + - index: current array element index. + - arr: the array on which the method was called. + + If provided an initial value, the method invokes a provided function with + the initial value as the first argument and the last array element as the + second argument. + + If not provided an initial value, the method invokes a provided function + with the last array element as the first argument and the second-to-last + array element as the second argument. + + Parameters + ---------- + reducerFn: Function + Function to apply to each array element. + + initialValue: any (optional) + Initial accumulation value. + + Returns + ------- + out: any + Accumulated result. + + Examples + -------- + > var arr = new {{alias}}( [ 1, 2, 3 ] ) + [ 1n, 2n, 3n ] + > var u = arr.reduceRight( {{alias:@stdlib/number/uint64/base/add}} ) + [ 6n ] + + {{alias}}.prototype.set( v[, i] ) Sets one or more array elements. diff --git a/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts index 78b11c503625..d8954cbef16d 100644 --- a/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/uint64/docs/types/index.d.ts @@ -477,6 +477,23 @@ declare class Uint64Array implements Uint64ArrayInterface { */ get( i: number ): Uint64 | void; + /** + * Applies a provided callback function to each element of the array, in reverse order, passing in the return value from the calculation on the following element and returning the accumulated result upon completion. + * + * @param reducer - callback function + * @param initialValue - initial value + * @returns accumulated result + * + * @example + * var add = require( '@stdlib/number/uint64/base/add' ); + * + * var arr = new Uint64Array( [ 1, 2, 3 ] ); + * + * var u = arr.reduceRight( add ); + * // returns [ 6n ] + */ + reduceRight( reducer: Reducer, initialValue?: U ): U; + /** * Sets an array element. * diff --git a/lib/node_modules/@stdlib/array/uint64/lib/main.js b/lib/node_modules/@stdlib/array/uint64/lib/main.js index 684cb8e4b9bd..8cf3d73aa2df 100644 --- a/lib/node_modules/@stdlib/array/uint64/lib/main.js +++ b/lib/node_modules/@stdlib/array/uint64/lib/main.js @@ -758,6 +758,58 @@ setReadOnlyAccessor( Uint64Array.prototype, 'length', function get() { return this._length; }); +/** +* Applies a provided callback function to each element of the array, in reverse order, passing in the return value from the calculation on the following element and returning the accumulated result upon completion. +* +* @name reduceRight +* @memberof Uint64Array.prototype +* @type {Function} +* @param {Function} reducer - callback function +* @param {*} [initialValue] - initial value +* @throws {TypeError} `this` must be a 64-bit unsigned integer array +* @throws {TypeError} first argument must be a function +* @throws {Error} if not provided an initial value, the array must have at least one element +* @returns {*} accumulated result +* +* @example +* var add = require( '@stdlib/number/uint64/base/add' ); +* +* var arr = new Uint64Array( [ 1, 2, 3 ] ); +* +* var u = arr.reduceRight( add ); +* // returns [ 6n ] +*/ +setReadOnly( Uint64Array.prototype, 'reduceRight', function reduceRight( reducer, initialValue ) { + var buf; + var acc; + var len; + var v; + var i; + if ( !isUint64Array( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a 64-bit unsigned integer array.' ); + } + if ( !isFunction( reducer ) ) { + throw new TypeError( format( 'invalid argument. First argument must be a function. Value: `%s`.', reducer ) ); + } + buf = this._buffer; + len = this._length; + if ( arguments.length > 1 ) { + acc = initialValue; + i = len - 1; + } else { + if ( len === 0 ) { + throw new Error( 'invalid operation. If not provided an initial value, an array must contain at least one element.' ); + } + acc = getUint64( buf, len-1 ); + i = len - 2; + } + for ( ; i >= 0; i-- ) { + v = getUint64( buf, i ); + acc = reducer( acc, v, i, this ); + } + return acc; +}); + /** * Sets an array element. * diff --git a/lib/node_modules/@stdlib/array/uint64/test/test.reduce_right.js b/lib/node_modules/@stdlib/array/uint64/test/test.reduce_right.js new file mode 100644 index 000000000000..1b7a33b02c36 --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/test/test.reduce_right.js @@ -0,0 +1,209 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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 tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var isUint64 = require( '@stdlib/assert/is-uint64' ); +var isEqual = require( '@stdlib/number/uint64/base/assert/is-equal' ); +var add = require( '@stdlib/number/uint64/base/add' ); +var Number = require( '@stdlib/number/ctor' ); +var Uint64 = require( '@stdlib/number/uint64/ctor' ); +var Uint64Array = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof Uint64Array, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the prototype of the main export is a `reduceRight` method', function test( t ) { + t.strictEqual( hasOwnProp( Uint64Array.prototype, 'reduceRight' ), true, 'has property' ); + t.strictEqual( isFunction( Uint64Array.prototype.reduceRight ), true, 'has method' ); + t.end(); +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a 64-bit unsigned integer array instance', function test( t ) { + var values; + var arr; + var i; + + arr = new Uint64Array( 5 ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return arr.reduceRight.call( value, add ); + }; + } +}); + +tape( 'the method throws an error if provided a first argument which is not a function', function test( t ) { + var values; + var arr; + var i; + + arr = new Uint64Array( 5 ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return arr.reduceRight( value ); + }; + } +}); + +tape( 'the method throws an error if not provided an initial value when operating on an empty 64-bit unsigned integer array', function test( t ) { + var arr; + + arr = new Uint64Array( 0 ); + t.throws( foo, Error, 'throws an error' ); + t.end(); + + function foo() { + arr.reduceRight( add ); + } +}); + +tape( 'the method uses the last element of the array as the initial value when an initial value is not provided', function test( t ) { + var valueArray; + var accArray; + var expected; + var actual; + var arr; + var len; + + arr = new Uint64Array( [ 1, 2, 3 ] ); + len = arr.length; + accArray = [ 3, 5 ]; + valueArray = [ 2, 1 ]; + expected = new Uint64( 6 ); + actual = arr.reduceRight( reducer ); + + t.strictEqual( isUint64( actual ), true, 'returns expected value' ); + t.strictEqual( isEqual( actual, expected ), true, 'returns expected value' ); + + t.end(); + + function reducer( acc, value, index ) { + var ind = len - index - 2; + t.strictEqual( isUint64( acc ), true, 'returns expected value' ); + t.strictEqual( isEqual( acc, new Uint64( accArray[ ind ] ) ), true, 'returns expected value' ); + t.strictEqual( isUint64( value ), true, 'returns expected value' ); + t.strictEqual( isEqual( value, new Uint64( valueArray[ ind ] ) ), true, 'returns expected value' ); + return add( acc, value ); + } +}); + +tape( 'the method supports providing an initial value as the second argument', function test( t ) { + var valueArray; + var accArray; + var expected; + var actual; + var arr; + var len; + + arr = new Uint64Array( [ 1, 2, 3 ] ); + len = arr.length; + accArray = [ 2, 5, 7 ]; + valueArray = [ 3, 2, 1 ]; + expected = new Uint64( 8 ); + actual = arr.reduceRight( reducer, new Uint64( 2 ) ); + + t.strictEqual( isUint64( actual ), true, 'returns expected value' ); + t.strictEqual( isEqual( actual, expected ), true, 'returns expected value' ); + + t.end(); + + function reducer( acc, value, index ) { + var ind = len - index - 1; + t.strictEqual( isUint64( acc ), true, 'returns expected value' ); + t.strictEqual( isEqual( acc, new Uint64( accArray[ ind ] ) ), true, 'returns expected value' ); + t.strictEqual( isUint64( value ), true, 'returns expected value' ); + t.strictEqual( isEqual( value, new Uint64( valueArray[ ind ] ) ), true, 'returns expected value' ); + return add( acc, value ); + } +}); + +tape( 'the method returns the accumulated result', function test( t ) { + var expected; + var actual; + var arr; + + arr = new Uint64Array( [ 1, 2, 3 ] ); + expected = new Uint64( 6 ); + actual = arr.reduceRight( add ); + + t.strictEqual( isUint64( actual ), true, 'returns expected value' ); + t.strictEqual( isEqual( actual, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the method supports returning real-valued results', function test( t ) { + var expected; + var actual; + var arr; + + arr = new Uint64Array( [ 1, 2, 3 ] ); + expected = 6; + actual = arr.reduceRight( reducer, 0 ); + + t.strictEqual( actual, expected, 'returns expected value' ); + t.end(); + + function reducer( acc, value ) { + return acc + Number( value ); + } +});