feat: add number/uint64/base/string2words

[impawstarlight]

Resolves none.

Description

What is the purpose of this pull request?

This pull request:

• Adds a new package for parsing numeric strings into high and low words of an 64-bit unsigned integer.

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

• Should the validation blocks for invalid radix and too big number remain in the assign function or be removed for performance?
• Any refinements necessary in the notes section of the readme file?

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

I used Gemini and GitHub Copilot to generate & refine the JSDoc comment for the CHUNKMAP variable, conduct overall research and code review.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
number/uint64/base/string2words	$\\color{green}323/323$ $\\color{green}+0.00\\%$	$\\color{green}21/21$ $\\color{green}+0.00\\%$	$\\color{green}3/3$ $\\color{green}+0.00\\%$	$\\color{green}323/323$ $\\color{green}+0.00\\%$

The above coverage report was generated for the changes in this PR.

[kgryte]

LGTM

[kgryte]

Actually, before we merge, @impawstarlight would you mind adding additional tests so that we can achieve 100% coverage? See https://coverage.stdlib.io/pr-13356/number/uint64/base/string2words/index.html.

[impawstarlight]

@kgryte Added additional tests for 100% coverage.

[kgryte]

Okay...I am backtracking here. I am thinking we should raise an exception here. The reason being that it is impossible currently to disambiguate the string '0' from an error state here.

In other scenarios, we can return sentinel values (e.g., NaN, -1, etc), but here we cannot. As such, I am of opinion that it would be better to throw.

We do raise exceptions in "base" implementations, depending on the context. Typically, when there is the possibility of a runtime error, rather than, let's call it, a static error (e.g., providing a string instead of a number; something which would be caught by a static compiler, if JS had one).

That applies here and when str is too big for uint64. Thoughts?

[impawstarlight]

One thing we can do to distinguish '0' from a too big str is to check in the call site whether the passed string was actually '0' or not. For example in uint64/parse we can do this:

function parseUint64( str, radix ) {
    // Check str type and throw TypeErrors
    ...

    // Sanitize and validate str: trim whitespaces, sign symbol, leading zeros, detect radix prefix, check invalid chars and throw,
    ...

    // Check radix type and range and throw Type/RangeError
    if ( radix < 2 || radix > 36 )
    ...

    // Call string2words, str will be trimmed of whitespace, sign symbol, leading zeros and contain no invalid chars at this point
    string2words.assign( str, radix, out, 1, 0 );

    // Check for too big value / overflow and throw RangeError
    if ( out[ 0 ] === 0 && out[ 1 ] === 0 && str !== '0' )
    ...
   
    ...
}

So like, the only error that we cannot detect beforehand from the call site is the too big value case, and we can differentiate it after the call with the combined str !== '0' check.

And in all other cases we can detect the error before the call. That's why I think we can remove the radix check from string2words.assign altogether.

And about runtime errors due to an invalid radix (0, 1, or 37), there is no crash in those cases and just gives wrong output ([ 0, 0 ]) even without the radix check at the top.

[impawstarlight]

So that's my pitch, pushing all the validation burden up to the call site and only keep the too big check.

[kgryte]

Wouldn't you need to check for all variations of 0? 0, 00, 000, etc?

[impawstarlight]

No because the string will be stripped of extra leading zeros before passing to string2words.assign.

[kgryte]

throw two RangeErrors, one for invalid radix and one for too big value?

Yes, I think that makes sense.

[impawstarlight]

What happens if values are out-of-range?

Truncation

[impawstarlight]

Since bigint2words uses BigInt.asUintN( 64, value ), it truncates cleanly like unsigned long long of C. But number2words is trickier since it just divides the input value by 2^32 then coerces to uint32 with the >>> operator. So it involves truncation along with floating point rounding and precision loss.

[kgryte]

For bigint2words, should be easy enough to check for too big a value.

v = BigInt.asUintN( 64, value );
if ( v !== value ) {
    throw( ... );
}

For number2words, we can use the max safe integer as the upper bound.

if ( value > MAX_SAFE_INTEGER ) {
    throw( ... );
}

[impawstarlight]

Alright, on it.

[kgryte]

LGTM