BigInt.prototype.toLocaleString

[littledan]

In the Stage 3 BigInt proposal, toLocaleString is defined. We should have a definition for this in the ECMA-402 specification.

I wasn't able to find an ICU API which would be useful here; does one exist?

cc @jakobkummerow

[anba]

ICU4C has unum_formatDecimal, ICU4J has NumberFormat#format(java.math.BigInteger).

[littledan]

That looks perfect for this case. Seems like we could pass the output of ToString(bigInt) to unum_formatDecimal as its number/length arguments, if I'm understanding the Decimal Arithmetic Specification correctly.

@anba Would you be interested in writing specification text for BigInt.prototype.toLocaleString in ECMA 402? The design I was imagining would be to base it on an overload of Intl.NumberFormat.prototype.format for BigInts--Number Format Functions could start with ToNumeric rather than ToNumber, and then PartitionNumberPattern would somehow be either generalized or cloned to handle BigInt in addition to Number.

cc @cxielarko

[anba]

AFAICT the descriptions for FormatNumberToString, PartitionNumberPattern, FormatNumber, ToRawPrecision, and ToRawFixed only need to be changed to allow BigInt values for the x parameter. BigInt.prototype.toLocaleString can then be defined as:

1. Let x be ? thisBigIntValue(this value).
2. Let numberFormat be ? Construct(%NumberFormat%, « locales, options »).
3. Return FormatNumber(numberFormat, x).

And maybe s/Number/Numeric/ for FormatNumberToString, PartitionNumberPattern, and FormatNumber?

Do we also want to modify (or add a new method) to allow BigInt values for Intl.NumberFormat.prototype.format and Intl.NumberFormat.prototype.formatToParts? The latter may not be implementable in ICU4C because it lacks a unum_formatDecimalForFields function.

[sffc]

FYI, better than unum_formatDecimal and NumberFormat#format(java.math.BigInteger) is to use the new methods offered in icu.number and numberformatter.h. The former two methods are not deprecated (at least not yet), but they are discouraged for new users.

numberformatter.h has an endpoint for the same syntax as unum_formatDecimal, but it also has full support for the field position iterator needed for formatToParts. You use it like this:

FormattedNumber result = NumberFormatter::withLocale(...).formatDecimal(..., status);
result.populateFieldPositionIterator(...);
UnicodeString resultString = result.toString();

[anba]

Thanks for the info that the new number formatting API will support this use case! For SpiderMonkey we may need to wait for https://ssl.icu-project.org/trac/ticket/13597, because we generally only use the C-API for its compatibility across different releases.

[sffc]

As a general comment, I think that we should interpret string inputs as the highest precision datatype supported. So if I give a string containing something like "987654321987654321987654321", that should be interpreted as a BigInteger. However, "9876.543" should be interpreted as a double until Ecma adds a datatype for BigDecimal, for example.

[littledan]

I'd prefer not to do this sort of "magical" semantic overloading. If your intuition is that that should exist, then I'm inclined to add another method, and avoid overloading, e.g., Intl.NumberFormat.prototype.formatBigInt/formatBigIntToParts. What would you think of that?

[sffc]

I don't see this as "magical" overloading. I see it as the method taking the input data type and then internally choosing the highest precision data type available to represent it.

My intuition is that it's weird to ever convert strings to Numbers, and we should avoid it when possible with better alternative behavior.

[littledan]

My intuition is that it's weird to ever convert strings to Numbers, and we should avoid it when possible with better alternative behavior.

Following this intuition, I'd like to mentally classify the format method accepting String arguments at all as weird random legacy behavior, and based on that analysis, not upgrade it to get higher precision. We can't remove it, but we also don't have to improve it. Leaving format(String)'s behavior unchanged will simplify the specification and implementation.

[FrankYFTang]

Could someone show me a js example code of how to use BigInt with the toLocaleString?

IS it like

12345678901234567890n.toLocaleString("fr")

?
Is it adding a "n" after the digit good enough to denote the BigInt? Sorry of my lack of confidence of knowing BigInt well here.

[jakobkummerow]

Yes, that looks correct.

[FrankYFTang]

Thanks for the code review from @jakobkummerow the v8 implementation sync with the current spec ( 040f809 ) is landed into v8 tree behind the flag --harmony-intl-bigint . You can also see the test I wrote here
https://chromium-review.googlesource.com/c/v8/v8/+/1424021/8/test/intl/bigint/tolocalestring.js
Notice in this implementation BigInt(-0).toLocaleString() will output "0" instead of "-0". @jakobkummerow said that is the expected behavior. In the other hand (-0).toLocaleString() will return "-0".

[littledan]

Great work, @FrankYFTang !

That's right; for BigInt, -0n is 0n.

I'm going to present on this issue in the upcoming TC39 meeting, arguing we should instead make a separate method, formatBigInt, and consider that a pattern going forward. See slides.

[ray007]

I can understand there being a difference between -0 and 0 for double/float, but for integers?

[FrankYFTang]

The reason my current v8 implementation output BigInt(-0) to "0" is because the BitInt.prototype.toString output "0" instead of "-0".

[jakobkummerow]

And the reason that (-0n).toString() === "0" is because there is no negative-zero BigInt. It's not a question of what toString does. -0.0 is an IEEE floating-point concept; integers of any kind don't have it.

See our implementation of BigInt negation:

Handle<BigInt> BigInt::UnaryMinus(Isolate* isolate, Handle<BigInt> x) {
  // Special case: There is no -0n.
  if (x->is_zero()) {
    return x;
  }
  Handle<MutableBigInt> result = MutableBigInt::Copy(isolate, x);
  result->set_sign(!x->sign());
  return MutableBigInt::MakeImmutable(result);
}