"number-format" expression

[ChrisLoer]

Add "number-format" expression, to fix #4119. Example:

["number-format", 1234.5678, { "currency": "EUR" } ] -> "€ 1,234.56"

Format options are:

• "locale": BCP 47 language tag, defaults to current locale. May or may not succeed in loading the locale, currently the only way to inspect this is to use the resolved-locale expression on a collator.
• "currency": If set, ISO 4217 currency code, used for currency formatting. Returned string includes a symbol representing the currency (e.g. "JP¥" or "€").
• "min-fraction-digits": Formatter will include at least this many digits after the decimal point. Defaults to 0.
• "max-fraction-digits": Formatter will include at most this many digits after the decimal point. Defaults to 3.

Launch Checklist

• briefly describe the changes in this PR
• write tests for all new functionality
• document any changes to public APIs
• post benchmark scores
• manually test the debug page
• tagged @mapbox/studio and/or @mapbox/maps-design if this PR includes style spec changes

[ChrisLoer]

This would fix #4119

[ChrisLoer]

cc @chloekraw and @mapbox/maps-design -- I know this isn't near the top of our prioritized list, but it's potential low-hanging fruit and could be pretty useful for displaying contextual information, especially with POIs.

Caveat on "low-hanging fruit" claim: just like the collator expressions, this requires us to come up with uniform behavior across multiple differing platform implementations, so there are pitfalls. The good news is that unlike the collator work, no further changes to the expression language itself are necessary.

[1ec5]

Thanks for making this proposal! This expression operator would be a boon for data visualization use cases especially, but also more subtly when dealing with elevations or clustering. It would also represent a significant usability win even for small numbers in languages that use non-Western numeral systems, such as Arabic and Hindi.

[1ec5]

Intl.NumberFormat requires this in "currency" mode, it doesn't just guess based on the locale

Yeah, that’s the right approach. Operating systems allow you to choose the preferred currency independently of the system region. By default, the system region typically affects mechanics like decimal separators, but not semantics or content.

[1ec5]

Here’s a correspondence to other implementation languages:

Style specification	Objective-C
NumberFormat.style	NSNumberFormatter.numberStyle
NumberFormat.locale	NSNumberFormatter.locale
NumberFormat.currency	NSNumberFormatter.currencyCode
Minimum/maximum fraction digits	NSNumberFormatter.minimumFractionDigits, maximumFractionDigits

In Java, use NumberFormat.get{Currency,Number,Percent}Instance() and NumberFormat.setCurrency().

[1ec5]

Would we support any extensions, such as zh-Hans-CN-u-nu-hanidec to specify Chinese decimal numbering? Perhaps it would be an “if it works, it works” situation, with no availability guarantees from one platform to another.

[ChrisLoer]

Perhaps it would be an “if it works, it works” situation, with no availability guarantees from one platform to another.

That sounds right to me.

[1ec5]

NSNumberFormatterStyle actually supports a number of styles, including NSNumberFormatterSpellOutStyle and NSNumberFormatterOrdinalStyle. However, I recognize the need to stick to JavaScript’s Intl as a common denominator, without implementing our own custom types that could conflict with future JavaScript types.

This does mean that the style author will need to hard-code some logic to implement short formats, such as the “1k” for 1,000 that Supercluster implements (only for English) in the point_count_abbreviated property (mapbox/supercluster#110).

/ref tc39/ecma402#37 tc39/ecma402#215.

[ChrisLoer]

I think this is ready. The tests may break if run on a machine that doesn't have a US locale installed, which makes me feel squirmy, although I think so far that has worked out OK with the collator tests. If it becomes a problem we can make the tests more verbose (check for "resolved-locale" and just pass the test the locale isn't available).

@asheemmamoowala would you have a chance to review?

Also tagging @mapbox/studio b/c I don't think they got the original notification.

[asheemmamoowala]

This proposal is 👌 ! If the need arises, a number-style parameter can be added to the supported options to include other formatting styles.

Would there be a need to use data-driven styling for the currency field?

[dasulit]

Thanks for tagging Studio in!

[ChrisLoer]

Would there be a need to use data-driven styling for the currency field?

I could imagine DDS being used for currency in something like a map showing hotel costs in local currencies, where the currency to use would depend on data in the map.