diff --git a/lib/node_modules/@stdlib/array/uint64/README.md b/lib/node_modules/@stdlib/array/uint64/README.md index 135bbba2b154..9e7ea549f00d 100644 --- a/lib/node_modules/@stdlib/array/uint64/README.md +++ b/lib/node_modules/@stdlib/array/uint64/README.md @@ -278,6 +278,44 @@ z = arr.at( -100 ); // returns undefined ``` + + +#### Uint64Array.prototype.entries() + +Returns an iterator for iterating over array key-value pairs. + +```javascript +var Uint64 = require( '@stdlib/number/uint64/ctor' ); + +var arr = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ) +]; +arr = new Uint64Array( arr ); + +// Create an iterator: +var it = arr.entries(); + +// Iterate over the key-value pairs... +var v = it.next().value; +// returns [ 0, [ 1n ] ] + +v = it.next().value; +// returns [ 1, [ 2n ] ] + +v = it.next().value; +// returns [ 2, [ 3n ] ] + +var bool = it.next().done; +// returns true +``` + +The returned [iterator][mdn-iterator-protocol] protocol-compliant object has the following properties: + +- **next**: function which returns an [iterator][mdn-iterator-protocol] protocol-compliant object containing the next iterated value (if one exists) assigned to a `value` property and a `done` property having a `boolean` value indicating whether the [iterator][mdn-iterator-protocol] is finished. +- **return**: function which closes an [iterator][mdn-iterator-protocol] and returns a single (optional) argument in an [iterator][mdn-iterator-protocol] protocol-compliant object. + #### Uint64Array.prototype.get( i ) @@ -466,6 +504,8 @@ logEach( '%s', out );
+[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol + [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray [@stdlib/array/typed]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/typed diff --git a/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.entries.js b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.entries.js new file mode 100644 index 000000000000..9aa9b74a0c4e --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/benchmark/benchmark.entries.js @@ -0,0 +1,52 @@ +/** +* @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 format = require( '@stdlib/string/format' ); +var zeroTo = require( '@stdlib/array/zero-to' ); +var pkg = require( './../package.json' ).name; +var Uint64Array = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:entries', pkg ), function benchmark( b ) { + var iter; + var arr; + var i; + + arr = new Uint64Array( zeroTo( 10, 'generic' ) ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + iter = arr.entries(); + if ( typeof iter !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( typeof iter !== 'object' || typeof iter.next !== 'function' ) { + b.fail( 'should return an iterator protocol-compliant object' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt index aad3a9918af8..6dd3c27d5987 100644 --- a/lib/node_modules/@stdlib/array/uint64/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/uint64/docs/repl.txt @@ -252,6 +252,29 @@ [ 2n ] +{{alias}}.prototype.entries() + Returns an iterator for iterating over array key-value pairs. + + Returns + ------- + iterator: Iterator + Iterator for iterating over array key-value pairs. + + Examples + -------- + > var arr = new {{alias}}( [ 1, 2, 3 ] ) + [ 1n, 2n, 3n ] + > var it = arr.entries(); + > var v = it.next().value + [ 0, [ 1n ] ] + > v = it.next().value + [ 1, [ 2n ] ] + > v = it.next().value + [ 2, [ 3n ] ] + > var bool = it.next().done + true + + {{alias}}.prototype.get( i ) Returns an array element located at integer position (index) `i`. 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 5e66f513e8bb..73e7941a80c5 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 @@ -22,7 +22,7 @@ /// -import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter'; +import { Iterator as Iter, IterableIterator, TypedIterator } from '@stdlib/types/iter'; import { ArrayLike, Uint64Array as Uint64ArrayInterface } from '@stdlib/types/array'; import { Uint64 } from '@stdlib/types/number'; import ArrayBuffer = require( '@stdlib/array/buffer' ); @@ -426,6 +426,39 @@ declare class Uint64Array implements Uint64ArrayInterface { */ at( i: number ): Uint64 | void; + /** + * Returns an iterator for iterating over array key-value pairs. + * + * @returns iterator + * + * @example + * var Uint64 = require( '@stdlib/number/uint64/ctor' ); + * + * var arr = [ + * new Uint64( 1 ), + * new Uint64( 2 ), + * new Uint64( 3 ) + * ]; + * arr = new Uint64Array( arr ); + * + * // Create an iterator: + * var it = arr.entries(); + * + * // Iterate over the key-value pairs... + * var v = it.next().value; + * // returns [ 0, [ 1n ] ] + * + * v = it.next().value; + * // returns [ 1, [ 2n ] ] + * + * v = it.next().value; + * // returns [ 2, [ 3n ] ] + * + * var bool = it.next().done; + * // returns true + */ + entries(): TypedIterator<[number, Uint64]>; + /** * Returns 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 3094e05d2787..c4c2be8f107c 100644 --- a/lib/node_modules/@stdlib/array/uint64/lib/main.js +++ b/lib/node_modules/@stdlib/array/uint64/lib/main.js @@ -597,6 +597,118 @@ setReadOnlyAccessor( Uint64Array.prototype, 'byteOffset', function get() { */ setReadOnly( Uint64Array.prototype, 'BYTES_PER_ELEMENT', Uint64Array.BYTES_PER_ELEMENT ); +/** +* Returns an iterator for iterating over array key-value pairs. +* +* @name entries +* @memberof Uint64Array.prototype +* @type {Function} +* @throws {TypeError} `this` must be a 64-bit unsigned integer array +* @returns {Iterator} iterator +* +* @example +* var Uint64 = require( '@stdlib/number/uint64/ctor' ); +* +* var arr = [ +* new Uint64( 1 ), +* new Uint64( 2 ), +* new Uint64( 3 ) +* ]; +* arr = new Uint64Array( arr ); +* +* // Create an iterator: +* var it = arr.entries(); +* +* // Iterate over the key-value pairs... +* var v = it.next().value; +* // returns [ 0, [ 1n ] ] +* +* v = it.next().value; +* // returns [ 1, [ 2n ] ] +* +* v = it.next().value; +* // returns [ 2, [ 3n ] ] +* +* var bool = it.next().done; +* // returns true +*/ +setReadOnly( Uint64Array.prototype, 'entries', function entries() { + var buffer; + var self; + var iter; + var len; + var FLG; + var i; + if ( !isUint64Array( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a 64-bit unsigned integer array.' ); + } + self = this; + buffer = this._buffer; + len = this._length; + + // Initialize an iteration index: + i = -1; + + // Create an iterator protocol-compliant object: + iter = {}; + setReadOnly( iter, 'next', next ); + setReadOnly( iter, 'return', end ); + + if ( ITERATOR_SYMBOL ) { + setReadOnly( iter, ITERATOR_SYMBOL, factory ); + } + return iter; + + /** + * Returns an iterator protocol-compliant object containing the next iterated value. + * + * @private + * @returns {Object} iterator protocol-compliant object + */ + function next() { + i += 1; + if ( FLG || i >= len ) { + return { + 'done': true + }; + } + return { + 'value': [ i, new getUint64( buffer, i ) ], + 'done': false + }; + } + + /** + * Finishes an iterator. + * + * @private + * @param {*} [value] - value to return + * @returns {Object} iterator protocol-compliant object + */ + function end( value ) { + FLG = true; + if ( arguments.length ) { + return { + 'value': value, + 'done': true + }; + } + return { + 'done': true + }; + } + + /** + * Returns a new iterator. + * + * @private + * @returns {Iterator} iterator + */ + function factory() { + return self.entries(); + } +}); + /** * Returns an array element. * diff --git a/lib/node_modules/@stdlib/array/uint64/test/test.entries.js b/lib/node_modules/@stdlib/array/uint64/test/test.entries.js new file mode 100644 index 000000000000..8e7e685452b3 --- /dev/null +++ b/lib/node_modules/@stdlib/array/uint64/test/test.entries.js @@ -0,0 +1,264 @@ +/** +* @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 proxyquire = require( 'proxyquire' ); +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isArray = require( '@stdlib/assert/is-array' ); +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 ITERATOR_SYMBOL = require( '@stdlib/symbol/iterator' ); +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 an `entries` method for returning an iterator for iterating over array key-value pairs', function test( t ) { + t.strictEqual( hasOwnProp( Uint64Array.prototype, 'entries' ), true, 'has property' ); + t.strictEqual( isFunction( Uint64Array.prototype.entries ), 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 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.entries.call( value ); + }; + } +}); + +tape( 'the method returns an iterator protocol-compliant object', function test( t ) { + var buf; + var arr; + var it; + var v; + var i; + + buf = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ), + new Uint64( 4 ) + ]; + arr = new Uint64Array( buf ); + + it = arr.entries(); + t.strictEqual( it.next.length, 0, 'has zero arity' ); + + for ( i = 0; i < arr.length; i++ ) { + v = it.next(); + t.strictEqual( isArray( v.value ), true, 'returns expected value' ); + t.strictEqual( v.value[ 0 ], i, 'returns an index' ); + t.strictEqual( isUint64( v.value[ 1 ] ), true, 'returns a 64-bit unsigned integer' ); + t.strictEqual( isEqual( v.value[ 1 ], buf[ i ] ), true, 'returns expected value' ); + t.strictEqual( typeof v.done, 'boolean', 'returns expected value' ); + } + t.end(); +}); + +tape( 'the method returns an iterator which has a `return` method for closing an iterator (no argument)', function test( t ) { + var buf; + var arr; + var it; + var v; + + buf = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ), + new Uint64( 4 ) + ]; + arr = new Uint64Array( buf ); + + it = arr.entries(); + + v = it.next(); + t.strictEqual( isEqual( v.value[ 1 ], buf[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( v.done, false, 'returns expected value' ); + + v = it.next(); + t.strictEqual( isEqual( v.value[ 1 ], buf[ 1 ] ), true, 'returns expected value' ); + t.strictEqual( v.done, false, 'returns expected value' ); + + v = it.return(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the method returns an iterator which has a `return` method for closing an iterator (argument)', function test( t ) { + var buf; + var arr; + var it; + var v; + + buf = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ), + new Uint64( 4 ) + ]; + arr = new Uint64Array( buf ); + + it = arr.entries(); + + v = it.next(); + t.strictEqual( isEqual( v.value[ 1 ], buf[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( v.done, false, 'returns expected value' ); + + v = it.next(); + t.strictEqual( isEqual( v.value[ 1 ], buf[ 1 ] ), true, 'returns expected value' ); + t.strictEqual( v.done, false, 'returns expected value' ); + + v = it.return( 'finished' ); + t.strictEqual( v.value, 'finished', 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + v = it.next(); + t.strictEqual( v.value, void 0, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); + + t.end(); +}); + +tape( 'if an environment supports `Symbol.iterator`, the method returns an iterable', function test( t ) { + var Uint64Array; + var arr; + var buf; + var it1; + var it2; + var v1; + var v2; + var i; + + Uint64Array = proxyquire( './../lib/main.js', { + '@stdlib/symbol/iterator': '__ITERATOR_SYMBOL__' + }); + + buf = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ), + new Uint64( 4 ) + ]; + arr = new Uint64Array( buf ); + + it1 = arr.entries(); + t.strictEqual( typeof it1[ '__ITERATOR_SYMBOL__' ], 'function', 'has method' ); + t.strictEqual( it1[ '__ITERATOR_SYMBOL__' ].length, 0, 'has zero arity' ); + + it2 = it1[ '__ITERATOR_SYMBOL__' ](); + t.strictEqual( typeof it2, 'object', 'returns expected value' ); + t.strictEqual( typeof it2.next, 'function', 'has `next` method' ); + t.strictEqual( typeof it2.return, 'function', 'has `return` method' ); + + for ( i = 0; i < arr.length; i++ ) { + v1 = it1.next().value; + v2 = it2.next().value; + t.strictEqual( isEqual( v1[ 0 ], v2[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isEqual( v1[ 1 ], v2[ 1 ] ), true, 'returns expected value' ); + } + t.end(); +}); + +tape( 'if an environment does not support `Symbol.iterator`, the method does not return an "iterable"', function test( t ) { + var Uint64Array; + var arr; + var buf; + var it; + + Uint64Array = proxyquire( './../lib/main.js', { + '@stdlib/symbol/iterator': false + }); + + buf = [ + new Uint64( 1 ), + new Uint64( 2 ), + new Uint64( 3 ), + new Uint64( 4 ) + ]; + arr = new Uint64Array( buf ); + + it = arr.entries(); + t.strictEqual( it[ ITERATOR_SYMBOL ], void 0, 'does not have property' ); + + t.end(); +});