Help language development. Donate to The Perl Foundation
A module for formatting numbers in a localized manner
To use, simply say
use Intl::Format::Number;
# Assuming user-language is 'en' (English)
say format-number 4834853; # 4,834,853
say format-number 12.394; # 12.394
say format-number 1/3; # 0.333333333333333
# A separate call can get a number formatter which allows you to specify more options
my $formatter = local-number-formatter('en', :minimum-significant-digits<2>);
It's that easy :-)
Currently supports percent, permille and scientific formatting in addition to the basic number format for languages with decimal number systems (sorry ancient Romans or Mayans!).
Other formatting styles (like compact) styles and options specified in TR 35 / CLDR, are NYI but will be available soon (current will be available via a separate module).
Performance is about an order of magnitude slower than .Str for most formatting, and I continue to try to optimize it farther.
Balancing performance with the ability to, e.g., format a FatRat of several thousand digits, isn't easy :-)
The Raku-defined variable $*TOLERANCE is used in the case of extremely long decimals (e.g. any repeating decimal like 1/3).
Raku defaults it to 1e-15 (thus providing 15 digits of decimals) but you can set it to any number.
You are highly advised not to set it to 0 as this may cause an infinite loop unless.
(In the future, setting the maximum fractional digits to Inf and $*TOLERANCE to 0 will generate an error).
Basic options
* :language<…>
Sets the language to use for formatting. If the Unicode U Extension tag nu (for numbering system) is present, it will be respected.
* :type<…> (standard, percent, permille, scientific, compact)
Sets the type of number desired. If percent or permille is selected, the number is multiplied by 100 or 1000 prior to display (such that .123 becomes 12.3% or 123‰). Compact numbers are not yet supported.
* :length<…>
Sets the length to use for formatting. Defaults to standard, which is the only option available outside of compact numbers.
Number formatter options (for use with get-number-formatter)
| option | description | example |
|---|---|---|
maximum-integer-digits |
No more whole digits than this | when 2 1234 yields 34 |
minimum-integer-digits |
Pad with zeros to have at least this many | when 412 yields 0012 |
maximum-fractional-digits |
No more decimal digits than this | when 21.2345 yields 1.23 |
minimum-fractional-digits |
Add trailing zeros to have at least this many | when 31.2 yields 1.200 |
maximum-significant-digits |
Limits the amount of significant digits used | when 21234 yields 1200 |
minimum-significant-digits |
Add trailing zeros if necessary | when 31 yields 1.00 |
show-decimal |
Forces the decimal to be shown | when True1 yields 1. |
show-sign |
Shows the sign regardless polarity | when True1 yields +1 |
symbols |
Adjusts the symbols used in formatting. | |
number-system |
Set the digits used. Must be a CLDR code. | when arab, 1234 yields ١٢٣٤ |
rast |
Returns a RakuAST node instead |
If significant digits are specified, then the integral/fractional digits are currently ignored.
Presently, the RakuAST node generated is a RakuAST::Sub. Additional documentation on it will
be included in future updates to improve its integration with other modules.
local-number-formatter and number-formatter:type<exponential>):type<percent> and :type<permille>):language<en-u-nu-limb> will use Limbu numerals)© 2020-2023 Matthew Stephen Stuckwisch. Licensed under the Artistic License 2.0.