Skip to content

fix: support full 64-bit integer range for number inputs in uint64/ctor #15476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kgryte merged 3 commits into from
Sep 24, 2026
Merged

fix: support full 64-bit integer range for number inputs in uint64/ctor #15476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15743c4
fix: support full 64-bit integer range for number inputs in Uint64 co…
impawstarlight Sep 23, 2026
148f435
Apply batched suggestions from code review
kgryte Sep 24, 2026
5c57f87
docs: add anchors
kgryte Sep 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions lib/node_modules/@stdlib/number/uint64/ctor/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ var w = x.lo;

### Static Methods

<a name="static-method-from"></a>

#### Uint64.from( array )

Creates a new 64-bit unsigned integer from an array-like object containing a high and low word.
Expand All @@ -130,6 +132,8 @@ var x = Uint64.from( [ 1234, 5678 ] );
// returns <Uint64>
```

<a name="static-method-of"></a>

#### Uint64.of( high, low )

Creates a new 64-bit unsigned integer from a high and low word.
Expand Down Expand Up @@ -190,6 +194,8 @@ var v = x.valueOf();
## Notes

- A 64-bit unsigned integer has a range of \[`0`, `2^64-1`].
- The constructor accepts either a `number` or a `bigint` on the interval `[0, 2^64-1]`.
- Passing a number argument is safe and exact for integers within \[`0`, `2^53`]. For values exceeding `2^53`, JavaScript numbers incur precision loss; provide a `bigint` argument or construct from words using [`Uint64.of()`](#static-method-of) or [`Uint64.from()`](#static-method-from).

</section>

Expand Down
24 changes: 10 additions & 14 deletions lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,13 @@
var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' );
var setReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' );
var BigInt = require( '@stdlib/bigint/ctor' );
var Number = require( '@stdlib/number/ctor' );
var Uint32Array = require( '@stdlib/array/uint32' );
var join = require( '@stdlib/array/base/join' );
var UINT32_MAX = require( '@stdlib/constants/uint32/max' );
var MAX_SAFE_INTEGER = require( '@stdlib/constants/float64/max-safe-integer' );
var format = require( '@stdlib/string/format' );
var ToPrimitiveSymbol = require( '@stdlib/symbol/to-primitive' );
var bigint2words = require( '@stdlib/number/uint64/base/bigint2words' ).assign;
var number2words = require( '@stdlib/number/uint64/base/number2words' ).assign;
var indices = require( './indices.js' );
var int2str = require( './to_string.js' );

Expand All @@ -47,6 +47,9 @@

var HAS_BIGINT = hasBigIntSupport();
var TWO_32 = 0x100000000; // 2^32
var TWO_64 = 0x10000000000000000; // 2^64
var STRIDE = indices.LOW - indices.HIGH;
var OFFSET = indices.HIGH;


// MAIN //
Expand All @@ -66,23 +69,16 @@
*/
function Uint64( value ) {
var buffer;
var v;
if ( !( this instanceof Uint64 ) ) {
throw new TypeError( 'invalid invocation. Constructor must be called with the `new` keyword.' );
}
buffer = new Uint32Array( 2 );
if ( isBigInt( value ) ) {
v = BigInt.asUintN( 64, value );
if ( v !== value ) {
throw new TypeError( format( 'invalid argument. Must provide an integer on the interval [0, 2^64-1]. Value: `%s`.', value ) );
}
buffer[ indices.HIGH ] = Number( v >> BigInt( 32 ) );
buffer[ indices.LOW ] = Number( v & BigInt( UINT32_MAX ) );
} else if ( isInteger( value ) && isBetween( value, 0, MAX_SAFE_INTEGER ) ) {
buffer[ indices.HIGH ] = ( value / TWO_32 ) >>> 0;
buffer[ indices.LOW ] = value >>> 0;
if ( isBigInt( value ) && BigInt.asUintN( 64, value ) === value ) {
bigint2words( value, buffer, STRIDE, OFFSET );
} else if ( isInteger( value ) && isBetween( value, 0, TWO_64, 'closed', 'open' ) ) {
number2words( value, buffer, STRIDE, OFFSET );
} else {
throw new TypeError( format( 'invalid argument. Must provide an integer on the interval [0, 2^53-1]. Value: `%s`.', value ) );
throw new TypeError( format( 'invalid argument. Must provide an integer on the interval [0, 2^64-1]. Value: `%s`.', value ) );
}
setReadOnly( this, '_buffer', buffer );
return this;
Expand Down Expand Up @@ -132,7 +128,7 @@
return v;
}

// TODO: consider supporting any iterable object

Check warning on line 131 in lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js

View workflow job for this annotation

GitHub Actions / Lint Changed Files 

Unexpected 'todo' comment: 'TODO: consider supporting any iterable...'

if (
isInteger( words[ 0 ] ) &&
Expand All @@ -140,7 +136,7 @@
isBetween( words[ 0 ], 0, UINT32_MAX ) &&
isBetween( words[ 1 ], 0, UINT32_MAX )
) {
// TODO: consider whether we should support accessor arrays here

Check warning on line 139 in lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js

View workflow job for this annotation

GitHub Actions / Lint Changed Files 

Unexpected 'todo' comment: 'TODO: consider whether we should support...'
v._buffer[ indices.HIGH ] = words[ 0 ]; // eslint-disable-line no-underscore-dangle
v._buffer[ indices.LOW ] = words[ 1 ]; // eslint-disable-line no-underscore-dangle
return v;
Expand Down Expand Up @@ -229,7 +225,7 @@
*
* @name hi
* @memberof Uint64.prototype
* @type {uinteger32}

Check warning on line 228 in lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js

View workflow job for this annotation

GitHub Actions / Lint Changed Files 

Unknown word: "uinteger"
* @returns {uinteger32} high word (32-bit unsigned integer)
*
* @example
Expand All @@ -247,7 +243,7 @@
*
* @name lo
* @memberof Uint64.prototype
* @type {uinteger32}

Check warning on line 246 in lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js

View workflow job for this annotation

GitHub Actions / Lint Changed Files 

Unknown word: "uinteger"
* @returns {uinteger32} low word (32-bit unsigned integer)
*
* @example
Expand Down Expand Up @@ -293,7 +289,7 @@
if ( HAS_BIGINT ) {
return BigInt( this.valueOf() ).toString( rad );
}
// TODO: Refactor to use `uint64/base/words2string` later

Check warning on line 292 in lib/node_modules/@stdlib/number/uint64/ctor/lib/main.js

View workflow job for this annotation

GitHub Actions / Lint Changed Files 

Unexpected 'todo' comment: 'TODO: Refactor to use...'
return int2str( [ this.hi, this.lo ], rad );
});

Expand Down
14 changes: 13 additions & 1 deletion lib/node_modules/@stdlib/number/uint64/ctor/test/test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ var Uint64 = require( './../lib' );
// VARIABLES //

var HAS_BIGINT = hasBigIntSupport();
var TWO_64 = 0x10000000000000000; // 2^64


// TESTS //
Expand Down Expand Up @@ -93,7 +94,8 @@ tape( 'the constructor throws an error if provided an invalid/unsupported number
values = [
-1,
0.5,
1 + MAX_SAFE_INTEGER
TWO_64,
TWO_64 + 4096 // Smallest integer greater than 2^64 exactly representable as a double
];
for ( i = 0; i < values.length; i++ ) {
t.throws( badValue( values[i] ), TypeError, format( 'throws an error when provided %s', values[i] ) );
Expand Down Expand Up @@ -152,6 +154,16 @@ tape( 'the constructor returns a 64-bit unsigned integer', function test( t ) {
t.strictEqual( x.hi, 2097151, 'returns expected value' );
t.strictEqual( x.lo, 4294967295, 'returns expected value' );

x = new Uint64( MAX_SAFE_INTEGER + 1 );
t.ok( x instanceof Uint64, 'returns expected value' );
t.strictEqual( x.hi, 2097152, 'returns expected value' );
t.strictEqual( x.lo, 0, 'returns expected value' );

x = new Uint64( TWO_64 - 2048 ); // Largest integer less than 2^64 exactly representable as a double
t.ok( x instanceof Uint64, 'returns expected value' );
t.strictEqual( x.hi, 4294967295, 'returns expected value' );
t.strictEqual( x.lo, 4294965248, 'returns expected value' );

if ( HAS_BIGINT ) {
x = new Uint64( BigInt( 0 ) );
t.ok( x instanceof Uint64, 'returns expected value' );
Expand Down
18 changes: 15 additions & 3 deletions lib/node_modules/@stdlib/number/uint64/ctor/test/test.to_string.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,21 @@
// MODULES //

var tape = require( 'tape' );
var hasBigIntSupport = require( '@stdlib/assert/has-bigint-support' );
var BigInt = require( '@stdlib/bigint/ctor' );
var MAX_SAFE_INTEGER = require( '@stdlib/constants/float64/max-safe-integer' );
var UINT32_MAX = require( '@stdlib/constants/uint32/max' );
var Uint64 = require( './../lib' );


// VARIABLES //

var TWO_64 = 0x10000000000000000; // 2^64
var opts = {
'skip': !hasBigIntSupport()
};


// TESTS //

tape( 'main export is a function', function test( t ) {
Expand All @@ -46,7 +56,7 @@ tape( 'the constructor returns an instance having a `toString` method for serial
t.end();
});

tape( 'the method accepts a radix parameter for serializing an instance as a string in bases 2 through 36', function test( t ) {
tape( 'the method accepts a radix parameter for serializing an instance as a string in bases 2 through 36', opts, function test( t ) {
var values;
var radix;
var i;
Expand All @@ -68,11 +78,13 @@ tape( 'the method accepts a radix parameter for serializing an instance as a str
UINT32_MAX,
UINT32_MAX + 1,
MAX_SAFE_INTEGER - 1,
MAX_SAFE_INTEGER
MAX_SAFE_INTEGER,
MAX_SAFE_INTEGER + 1,
TWO_64 - 2048 // Maximum integer value less than 2^64 that can be stored in a 64-bit float
];

for ( i = 0; i < values.length; i++ ) {
z = values[i];
z = BigInt( values[i] );

@kgryte kgryte Sep 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not clear why this change is necessary, but I'll defer to your judgment.

@impawstarlight impawstarlight Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because calling toString on an unsafe integer truncates the trailing digits to zero even though those digits are exactly representable in double, which we can see with toPrecision. But there's no way to use toPrecision with arbitrary radix, so we need rely on BigInt for precise serialization with specified radix in this test.
Screenshot_20260924_145703

@kgryte kgryte Sep 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation.

@kgryte kgryte Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like #.toString behavior is odd here and a likely source of confusion, especially when used in the REPL. Maybe we should add a dedicated utility to number/float64/to-exact-string (name?) to provide something more robust.

@kgryte kgryte Sep 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After a bit of back-and-forth with ChatGPT, I understand why #.toString behaves as it does (namely, serialize to the shortest representation which generates the exact same double). But, for usage in the REPL, this can lead to misleading results.

x = new Uint64( z );

for ( radix = 2; radix <= 36; radix++ ) {
Expand Down
Loading