{"id":"kiy4ku/robloxformatnumber","name":"robloxformatnumber","scope":"kiy4ku","platform":"roblox","description":"Forked from FormatNumber by Blockzez.","version":"31.1.0","latest":"31.1.0","versions":["31.1.0"],"license":"BSD-2-Clause","licenseRating":"safe","licenseCaveats":["The copyright notice must be preserved in copies.","License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"1b0a5d63b749b7d59afb3547a77f9d492861b161f1ac37719408e7422c784a8f","likes":0,"downloads":0,"install":"forest install kiy4ku/robloxformatnumber","url":"https://forest.dev/p/roblox/kiy4ku/robloxformatnumber","files":"https://api.forest.dev/ai/package/roblox/kiy4ku/robloxformatnumber/files","readme":"# FormatNumber\r\nThis is a number formatting module for Roblox.\r\n\r\n# Main API (FormatNumber.Main)\r\n## NumberFormatter\r\nThe class to format the numbers, located in `FormatNumber.NumberFormatter`.\r\n\r\n### Static methods\r\n`function NumberFormatter.with(): NumberFormatter`\r\nCreates a new number formatter with the default setting.\r\n\r\n`function NumberFormatter.forSkeleton(skeleton: string): (boolean, NumberFormatter | string)`\r\nTries to create a new number formatter with the skeleton string provided. If unsuccessful (e.g. the skeleton syntax is invalid) then it returns `false` and a message string, otherwise it returns `true` and the NumberFormatter.\r\nSee the Number Skeletons section of this API documentation for the skeleton syntax.\r\n\r\n### Methods\r\n`function NumberFormatter:Format(value: string): string`\r\nThe number to format, it could be any Luau number. It accounts for negative numbers, infinities, and NaNs. It returns `string` instead of `FormattedNumber` to simplify the implementation of module.\r\n`function NumberFormatter:ToSkeleton(): (boolean, string)`\r\nTries to convert it to skeleton. If it is unable to (like the settings having compact notation or symbols) then the first value will return `false` and a message stating that it is unsupported.\r\nIf it's successful then the first value will return `true` and the second value will return the skeleton.\r\n\r\n#### Settings chain methods\r\nThese are methods that returns NumberFormatter with the specific settings changed. Calling the methods doesn’t change the NumberFormatter object itself as it is immutable so you have to use the NumberFormatter that it returned.\r\n\r\n`function NumberFormatter:Notation(notation: FormatNumber.Notation): NumberFormatter`\r\nSee Notation.\r\n`function NumberFormatter:Precision(precision: FormatNumber.Precision): NumberFormatter`\r\nSee Precision.\r\n`function NumberFormatter:RoundingMode(roundingMode: FormatNumber.RoundingMode): NumberFormatter`\r\nSee FormatNumber.RoundingMode enum.\r\n`function NumberFormatter:Grouping(strategy: FormatNumber.GroupingStrategy): NumberFormatter`\r\nSee FormatNumber.GroupingStrategy enum.\r\n`function NumberFormatter:IntegerWidth(style: FormatNumber.IntegerWidth): NumberFormatter`\r\nSee IntegerWidth.\r\n`function NumberFormatter:Sign(style: FormatNumber.SignDisplay): NumberFormatter`\r\nSee FormatNumber.SignDisplay enum.\r\n`function NumberFormatter:Decimal(style: FormatNumber.DecimalSeparatorDisplay): NumberFormatter`\r\nSee FormatNumber.DecimalSeparatorDisplay enum.\r\n\r\n## Notation\r\nThese specify how the number is rendered, located in `FormatNumber.Notation`.\r\n\r\n### Static methods\r\n`function Notation.scientific(): ScientificNotation`\r\n`function Notation.engineering(): ScientificNotation`\r\nScientific notation and the engineering version of it respectively. Uses `E` as the exponent separator but you can change this through the `Symbols` settings.\r\n\r\n`function Notation.compactWithSuffixThousands(suffixTable: {string}): CompactNotation`\r\nBasically abbreviations with suffix appended, scaling by every thousands as the suffix changes.\r\nThe `suffixTable` argument does not respect the `__index` metamethod nor the `__len` metamethod.\r\n\r\n`function Notation.simple(): SimpleNotation`\r\nThe standard formatting without any scaling. The default.\r\n\r\n### ScientificNotation (methods)\r\nScientificNotation is a subclass of `Notation`.\r\n\r\n`function ScientificNotation:WithMinExponentDigits(minExponetDigits: number): ScientificNotation`\r\nThe minimum, padding with zeroes if necessary.\r\n\r\n`function ScientificNotation:WithExponentSignDisplay(FormatNumber.SignDisplay exponentSignDisplay): ScientificNotation`\r\nSee FormatNumber.SignDisplay enum.\r\n\r\n### CompactNotation (methods)\r\nNo methods currently but this is created just in case. This is a subclass of `Notation`.\r\n\r\n### SimpleNotation (methods)\r\nNo methods currently but this is created just in case. This is a subclass of `Notation`.\r\n\r\n## Precision\r\nThese are precision settings and changes to what places/figures the number rounds to, located in `FormatNumber.Precision`. The default is `Precision.integer():WithMinDigits(2)` for abbreviations and `Precision.maxFraction(6)` otherwise (for compatibility reasons).\r\n\r\n### Static methods\r\n`function Precision.integer(): FractionPrecision`\r\nRounds the number to the nearest integer\r\n\r\n`function Precision.minFraction(minFractionDigits: number): FractionPrecision`\r\n`function Precision.maxFraction(maxFractionDigits: number): FractionPrecision`\r\n`function Precision.minMaxFraction(minFractionDigits: number, maxFractionDigits: number): FractionPrecision`\r\n`function Precision.fixedFraction(fixedFractionDigits: number): FractionPrecision`\r\nRounds the number to a certain fractional digits (or decimal places), min is the minimum fractional (decimal) digits to show, max is the fractional digits (decimal places) to round, fixed refers to both min and max.\r\n\r\n`function Precision.minSignificantDigits(minSignificantDigits: number): SignificantDigitsPrecision`\r\n`function Precision.maxSignificantDigits(maxSignificantDigits: number): SignificantDigitsPrecision`\r\n`function Precision.minMaxSignificantDigits(minSignificantDigits: number, maxSignificantDigits: number): SignificantDigitsPrecision`\r\n`function Precision.fixedFraction(fixedSignificantDigits: number): SignificantDigitsPrecision`\r\nRound the number to a certain significant digits; min, max, and fixed are specified above but with significant digits.\r\n\r\n`function Precision.unlimited(): Precision`\r\nShow all available digits to its full precision.\r\n\r\n### FractionPrecision (methods)\r\n`FractionPrecision` is subclass of `Precision` with more options for the fractional (decimal) digits precision. Calling these methods is not required.\r\n\r\n`function FractionPrecision:WithMinDigits(minSignificantDigits: number): Precision`\r\nRound to the decimal places specified by the FractionPrecision object but keep at least the amount of significant digit specified by the argument.\r\n\r\n`function FractionPrecision:WithMaxDigits(maxSignificantDigits: number): Precision`\r\nRound to the decimal places specified by the FractionPrecision object but don’t keep any more the amount of significant digit specified by the argument.\r\n\r\n### SignificantDigitsPrecision (methods)\r\nNo methods currently but this is created just in case. This is a subclass of `Precision`.\r\n\r\n## IntegerWidth\r\n\r\n### Static methods\r\n`function IntegerWidth.zeroFillTo(minInt: number): IntegerWidth`\r\nZero fill numbers at the integer part of the number to guarantee at least certain digit in the integer part of the number.\r\n\r\n### Methods\r\n`function IntegerWidth:TruncateAt(maxInt: number): IntegerWidth`\r\nTruncates the integer part of the number to certain digits.\r\n\r\n## Enums\r\nThe associated numbers in all these enums are an implementation detail, please do not rely on them so instead of using `0`, use `FormatNumber.SignDisplay.AUTO`.\r\n\r\n### FormatNumber.GroupingStrategy\r\nThis determines how the grouping separator (comma by default) is inserted - integer part only. There are three options.\r\n\r\n* OFF - no grouping.\r\n* MIN2 - grouping only on 5 digits or above. (default for compact notation - for compatibility reasons)\r\n* ON_ALIGNED - always group the value. (default unless it’s compact notation)\r\n\r\nExample:\r\nGrouping strategy|123|1234|12345|123456|1234567\r\n-|-|-|-|-|-\r\nOFF|123|1234|12345|123456|1234567\r\nMIN2|123|1234|12,345|123,456|1,234,567\r\nON_ALIGNED|123|1,234|12,345|123,456|1,234,567\r\n\r\n### FormatNumber.SignDisplay\r\nThis determines how you display the plus sign (`+`) and the minus sign (`-`):\r\n\r\n* AUTO - Displays the minus sign only if the value is negative (that includes -0 and -NaN). (default)\r\n* ALWAYS - Displays the plus/minus sign on all values.\r\n* NEVER - Don’t display the plus/minus sign.\r\n* EXCEPT_ZERO - Display the plus/minus sign on all values except zero, numbers that round to zero and NaN.\r\n* NEGATIVE - Display the minus sign only if the value is negative but do not display the minus sign on -0 and -NaN.\r\n\r\nExample:\r\nSign display|+12|-12|+0|-0\r\n-|-|-|-|-\r\nAUTO|12|-12|0|-0\r\nALWAYS|+12|-12|+0|-0\r\nNEVER|12|12|0|0\r\nEXCEPT_ZERO|+12|-12|0|0\r\nNEGATIVE|12|-12|0|0\r\n\r\n### FormatNumber.RoundingMode\r\nThis determines the rounding mode. I only documented three rounding modes but there are others undocumented if you need it.\r\n\r\n* HALF_EVEN - Round it to the nearest even if it’s in the midpoint, round it up if it’s above the midpoint and down otherwise. (default unless it’s compact or scientific/engineering notation)\r\n* HALF_UP - Round it away from zero if it’s in the midpoint or above, down otherwise. (most familiar, this is probably the method you are taught at school)\r\n* DOWN - Round the value towards zero (truncates the value). (default for compact and scientific/engineering notation)\r\n\r\nExample:\r\nRounding mode|1.0|1.2|1.5|1.8|2.0|2.2|2.5|2.8\r\n-|-|-|-|-|-|-|-|-\r\nHALF_EVEN|1.0|1.0|2.0|2.0|2.0|2.0|2.0|3.0\r\nHALF_UP|1.0|1.0|2.0|2.0|2.0|2.0|3.0|3.0\r\nDOWN|1.0|1.0|1.0|1.0|2.0|2.0|2.0|2.0\r\n\r\n### FormatNumber.DecimalSeparatorDisplay\r\nThis determines how the decimal separator (`.` by default) is displayed.\r\n\r\n* AUTO - only show the decimal separators if there are at least one digits after it (default)\r\n* ALWAYS - always display the decimal separator, even if there's no digits after it\r\n\r\nExample:\r\nDecimal separator display|1|1.5\r\n-|-|-\r\nAUTO|1|1.5\r\nALWAYS|1.|1.5\r\n\r\n# Simple API (FormatNumberFolder.Simple)\r\n`function FormatNumber.Format(value: number, skeleton: string?): string`\r\nFormats a number with the skeleton settings if provided.\r\nSee the Number Skeletons section of this API documentation for the skeleton syntax.\r\n\r\n`function FormatNumber.FormatCompact(value: number, skeleton: string?): string`\r\nFormats a number in compact notation.\r\nYou'll need to provide the suffixes in the `Simple` ModuleScript. Multiple instances of suffixes are not supported\r\nSee the Number Skeletons section of this API documentation for the full skeleton syntax, but here's the several skeleton syntax for quick reference if you want to change precision (e.g. decimal places)\r\nSkeleton|Precision description\r\n-|-\r\nprecision-integer|no decimal places\r\nprecision-integer/@@\\*|whatever returns the longer result out of no decimal places and 2 significant digits (default)\r\n.#|1 decimal place\r\n.##|2 decimal places\r\n.###|3 decimal places\r\n@#|2 significant digits\r\n@##|3 significant digits\r\n\r\n# Number Skeletons\r\nThis feature is introduced in version 31.\r\nThe syntax is identical to the one used in ICU, so you can use this page for reference: https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html#skeleton-stems-and-options\r\nSee the Main API documentation for the settings.\r\nDo note that for this module, it only supports the following part of the Skeleton Stems and Options of the page linked:\r\n- Notation (but ignore `compact-short`/`K` and `compact-long`/`KK` as that's not supported)\r\n- Precision (but ignore `precision-increment/dddd`, `precision-currency`, `precision-currency-cash`, and Trailing Zero Display as that's not supported)\r\n- Rounding Mode (but ignore `rounding-mode-unnecessary` as that's not supported)\r\n- Integer Width\r\n- Grouping (but ignore `group-auto` and `group-thousands` as that's not supported)\r\n- Sign Display (but ignore any accounting sign display)\r\n- Decimal Separator Display\r\n","readmeTruncated":false}