gossamer - v10.0.0

gossamer/intl/number_format

Locale-aware number formatting via the JavaScript Intl.NumberFormat. Reusing a built NumberFormat across many calls is significantly faster than building one per call.

Formatting is bound per numeric type — format_float, format_int, and format_big_int — each with matching *_to_parts, *_range, and *_range_to_parts variants.

Types

Builder

opaque </>

The configuration for a NumberFormat.

pub opaque type Builder

CompactDisplay

</>

Whether NotationCompact uses short or long labels. Maps the JavaScript compactDisplay option.

pub type CompactDisplay {
  CompactShort
  CompactLong
}

Constructors 

  • CompactShort

    Short labels ("1.2K", the default).

  • CompactLong

    Long labels ("1.2 thousand").

CurrencyDisplay

</>

How currency is presented. Maps the JavaScript currencyDisplay option.

pub type CurrencyDisplay {
  CurrencyCode
  CurrencySymbol
  CurrencyNarrowSymbol
  CurrencyName
}

Constructors 

  • CurrencyCode

    The ISO 4217 currency code ("USD").

  • CurrencySymbol

    The localized currency symbol ("$", the default).

  • CurrencyNarrowSymbol

    The narrow currency symbol where available ("$" rather than "US$").

  • CurrencyName

    The localized currency name ("US dollars").

CurrencySign

</>

How negative currency amounts are presented. Maps the JavaScript currencySign option.

pub type CurrencySign {
  CurrencySignStandard
  CurrencySignAccounting
}

Constructors 

  • CurrencySignStandard

    Standard minus-sign notation ("-$1.00", the default).

  • CurrencySignAccounting

    Accounting notation, often parentheses ("($1.00)").

Notation

</>

The numeric notation. Maps the JavaScript notation option.

pub type Notation {
  NotationStandard
  NotationScientific
  NotationEngineering
  NotationCompact
}

Constructors 

  • NotationStandard

    Plain decimal notation ("1,234", the default).

  • NotationScientific

    Scientific notation ("1.234E3").

  • NotationEngineering

    Engineering notation — exponents are always multiples of three ("1.234E3").

  • NotationCompact

    Compact human-readable notation ("1.2K" or "1.2 thousand", depending on CompactDisplay).

NumberFormat

</>

A configured number formatter that produces locale-aware string output for numeric input.

See Intl.NumberFormat on MDN.

pub type NumberFormat

Part

</>

A single segment of a formatted number, returned by the format_*_to_parts family.

pub type Part {
  Part(kind: PartKind, value: String)
}

Constructors

PartKind

</>

The kind of a Part. Mirrors the JavaScript Intl.NumberFormatPart.type field.

pub type PartKind {
  Literal
  Integer
  Decimal
  Fraction
  Group
  MinusSign
  PlusSign
  Currency
  PercentSign
  Compact
  ExponentInteger
  ExponentMinusSign
  ExponentSeparator
  Infinity
  Nan
  Unit
}

Constructors 

  • Literal

    A literal string (separator words, punctuation, etc.).

  • Integer

    The integer portion.

  • Decimal

    The decimal separator ("." or "," per locale).

  • Fraction

    The fractional portion.

  • Group

    A digit-group separator ("," or " " per locale).

  • MinusSign

    A minus sign.

  • PlusSign

    A plus sign.

  • Currency

    A currency symbol or name.

  • PercentSign

    The percent sign.

  • Compact

    A compact-notation literal ("K", "thousand").

  • ExponentInteger

    The integer portion of a scientific or engineering exponent.

  • ExponentMinusSign

    A minus sign on a scientific or engineering exponent.

  • ExponentSeparator

    The "E" separator on a scientific or engineering exponent.

  • Infinity

    The literal infinity symbol ("∞").

  • Nan

    The literal NaN representation.

  • Unit

    A measurement unit name or symbol.

RangePart

</>

A single segment of a formatted number range, returned by the format_*_range_to_parts family. Like Part but also carries a intl.RangePartSource identifying which endpoint the segment came from.

pub type RangePart {
  RangePart(
    kind: PartKind,
    value: String,
    source: intl.RangePartSource,
  )
}

Constructors

ResolvedOptions

</>

The options the runtime resolved for a NumberFormat, including the defaults it filled in. locale is the BCP 47 tag chosen from the requested priority list (e.g., "en-US"). The currency fields are Some only for the StyleCurrency style, the unit fields only for StyleUnit, compact_display only for NotationCompact, and the fraction- and significant-digit fields only when the matching precision mode is in effect.

pub type ResolvedOptions {
  ResolvedOptions(
    locale: String,
    numbering_system: String,
    style: Style,
    currency: option.Option(String),
    currency_display: option.Option(CurrencyDisplay),
    currency_sign: option.Option(CurrencySign),
    unit: option.Option(String),
    unit_display: option.Option(UnitDisplay),
    minimum_integer_digits: Int,
    minimum_fraction_digits: option.Option(Int),
    maximum_fraction_digits: option.Option(Int),
    minimum_significant_digits: option.Option(Int),
    maximum_significant_digits: option.Option(Int),
    use_grouping: UseGrouping,
    notation: Notation,
    compact_display: option.Option(CompactDisplay),
    sign_display: SignDisplay,
    rounding_increment: Int,
    rounding_mode: intl.RoundingMode,
    rounding_priority: intl.RoundingPriority,
    trailing_zero_display: intl.TrailingZeroDisplay,
  )
}

Constructors

SignDisplay

</>

When to render an explicit sign. Maps the JavaScript signDisplay option.

pub type SignDisplay {
  SignAuto
  SignAlways
  SignExceptZero
  SignNegative
  SignNever
}

Constructors 

  • SignAuto

    Render the sign only for negative numbers (the default).

  • SignAlways

    Render the sign for all numbers, including zero.

  • SignExceptZero

    Render the sign for all non-zero numbers.

  • SignNegative

    Render the sign only for numbers the formatter considers negative (including negative zero, depending on locale).

  • SignNever

    Never render an explicit sign.

Style

</>

The high-level formatting style. Maps the JavaScript style option.

pub type Style {
  StyleDecimal
  StyleCurrency
  StylePercent
  StyleUnit
}

Constructors 

  • StyleDecimal

    Plain decimal numbers (the default).

  • StyleCurrency

    Currency amounts. Requires a currency code set via with_currency.

  • StylePercent

    Percentages — input values are multiplied by 100 for display (0.25 formats as "25%").

  • StyleUnit

    Measurements. Requires a unit identifier set via with_unit.

UnitDisplay

</>

How a measurement unit is presented. Maps the JavaScript unitDisplay option.

pub type UnitDisplay {
  UnitLong
  UnitShort
  UnitNarrow
}

Constructors 

  • UnitLong

    The long unit form ("16 liters").

  • UnitShort

    The short unit form ("16 L", the default).

  • UnitNarrow

    The narrow unit form ("16L").

UseGrouping

</>

Whether and when to insert grouping separators. Maps the JavaScript useGrouping option.

pub type UseGrouping {
  UseGroupingAlways
  UseGroupingAuto
  UseGroupingMin2
  UseGroupingOff
}

Constructors 

  • UseGroupingAlways

    Group regardless of locale convention.

  • UseGroupingAuto

    Group following the locale’s convention (the default).

  • UseGroupingMin2

    Group only when there are at least two digits in a group.

  • UseGroupingOff

    Never insert grouping separators.

Values

build

</> 
pub fn build(builder: Builder) -> Result(NumberFormat, Nil)

Constructs a NumberFormat from the configured builder. Returns Error(Nil) if any locale tag, currency code, unit identifier, or numbering-system identifier is structurally invalid, if a digit-count option is outside its allowed range, or if with_rounding_increment is set to an unsupported value.

format_big_int

</> 
pub fn format_big_int(
  formatter: NumberFormat,
  value: big_int.BigInt,
) -> String

Formats a BigInt value at full precision.

format_big_int_range

</> 
pub fn format_big_int_range(
  formatter: NumberFormat,
  from start: big_int.BigInt,
  to end: big_int.BigInt,
) -> String

Formats a BigInt range. Passing end < start produces a reversed-range string without erroring.

format_big_int_range_to_parts

</> 
pub fn format_big_int_range_to_parts(
  formatter: NumberFormat,
  from start: big_int.BigInt,
  to end: big_int.BigInt,
) -> List(RangePart)

Formats a BigInt range as a list of RangeParts.

format_big_int_to_parts

</> 
pub fn format_big_int_to_parts(
  formatter: NumberFormat,
  value: big_int.BigInt,
) -> List(Part)

Formats a BigInt value as a list of Parts.

format_float

</> 
pub fn format_float(
  formatter: NumberFormat,
  value: Float,
) -> String

Formats a Float value using the configured locale and options.

format_float_range

</> 
pub fn format_float_range(
  formatter: NumberFormat,
  from start: Float,
  to end: Float,
) -> String

Formats a Float range from start to end (e.g., "$3 – $10"). Passing end < start produces a reversed-range string without erroring.

format_float_range_to_parts

</> 
pub fn format_float_range_to_parts(
  formatter: NumberFormat,
  from start: Float,
  to end: Float,
) -> List(RangePart)

Formats a Float range and returns its decomposition into RangeParts, each tagged by which endpoint it came from.

format_float_to_parts

</> 
pub fn format_float_to_parts(
  formatter: NumberFormat,
  value: Float,
) -> List(Part)

Formats a Float value and returns its decomposition into segments, useful for separating currency symbols from amounts or restyling individual digit groups.

format_int

</> 
pub fn format_int(formatter: NumberFormat, value: Int) -> String

Formats an Int value using the configured locale and options.

format_int_range

</> 
pub fn format_int_range(
  formatter: NumberFormat,
  from start: Int,
  to end: Int,
) -> String

Formats an Int range. Passing end < start produces a reversed-range string without erroring.

format_int_range_to_parts

</> 
pub fn format_int_range_to_parts(
  formatter: NumberFormat,
  from start: Int,
  to end: Int,
) -> List(RangePart)

Formats an Int range as a list of RangeParts.

format_int_to_parts

</> 
pub fn format_int_to_parts(
  formatter: NumberFormat,
  value: Int,
) -> List(Part)

Formats an Int value as a list of Parts.

new

</> 
pub fn new(locales: List(String)) -> Builder

Creates a Builder for the given locale priority list. The runtime picks the first locale it supports; pass an empty list to use the runtime’s default locale.

resolved_options

</> 
pub fn resolved_options(
  formatter: NumberFormat,
) -> ResolvedOptions

The full configuration the runtime resolved from the builder, including the digit and rounding defaults it derived from the style and locale.

supported_locales_of

</> 
pub fn supported_locales_of(
  locales: List(String),
) -> Result(List(String), Nil)

Filters locales to those the runtime supports for number formatting, preserving the input order. Returns Error(Nil) if any locale tag is structurally malformed.

with_compact_display

</> 
pub fn with_compact_display(
  builder: Builder,
  compact_display: CompactDisplay,
) -> Builder

Sets the compact-notation label form. Only applies when the notation is NotationCompact.

with_currency

</> 
pub fn with_currency(
  builder: Builder,
  currency: String,
) -> Builder

Sets the ISO 4217 currency code (e.g., "USD", "EUR"). Used when the style is StyleCurrency.

with_currency_display

</> 
pub fn with_currency_display(
  builder: Builder,
  currency_display: CurrencyDisplay,
) -> Builder

Sets how the currency is presented.

with_currency_sign

</> 
pub fn with_currency_sign(
  builder: Builder,
  currency_sign: CurrencySign,
) -> Builder

Sets how negative currency amounts are presented.

with_locale_matcher

</> 
pub fn with_locale_matcher(
  builder: Builder,
  locale_matcher: intl.LocaleMatcher,
) -> Builder

Sets the locale-matching algorithm used to pick a locale from the priority list.

with_maximum_fraction_digits

</> 
pub fn with_maximum_fraction_digits(
  builder: Builder,
  maximum_fraction_digits: Int,
) -> Builder

Sets the maximum number of fraction digits.

with_maximum_significant_digits

</> 
pub fn with_maximum_significant_digits(
  builder: Builder,
  maximum_significant_digits: Int,
) -> Builder

Sets the maximum number of significant digits.

with_minimum_fraction_digits

</> 
pub fn with_minimum_fraction_digits(
  builder: Builder,
  minimum_fraction_digits: Int,
) -> Builder

Sets the minimum number of fraction digits.

with_minimum_integer_digits

</> 
pub fn with_minimum_integer_digits(
  builder: Builder,
  minimum_integer_digits: Int,
) -> Builder

Sets the minimum number of integer digits. Values below the minimum are zero-padded.

with_minimum_significant_digits

</> 
pub fn with_minimum_significant_digits(
  builder: Builder,
  minimum_significant_digits: Int,
) -> Builder

Sets the minimum number of significant digits.

with_notation

</> 
pub fn with_notation(
  builder: Builder,
  notation: Notation,
) -> Builder

Sets the numeric notation.

with_numbering_system

</> 
pub fn with_numbering_system(
  builder: Builder,
  numbering_system: String,
) -> Builder

Sets the numbering system identifier (e.g., "arab", "hans", "latn"). When unset, the locale’s default numbering system is used.

with_rounding_increment

</> 
pub fn with_rounding_increment(
  builder: Builder,
  rounding_increment: Int,
) -> Builder

Sets the rounding increment — the formatter rounds to the nearest multiple of this value. Valid values are 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, and 5000; other values cause build to return Error(Nil).

with_rounding_mode

</> 
pub fn with_rounding_mode(
  builder: Builder,
  rounding_mode: intl.RoundingMode,
) -> Builder

Sets the rounding strategy applied when the formatter discards digits past the configured precision.

with_rounding_priority

</> 
pub fn with_rounding_priority(
  builder: Builder,
  rounding_priority: intl.RoundingPriority,
) -> Builder

Sets how rounding interacts when both significant-digit and fraction-digit options are set.

with_sign_display

</> 
pub fn with_sign_display(
  builder: Builder,
  sign_display: SignDisplay,
) -> Builder

Sets when explicit signs are rendered.

with_style

</> 
pub fn with_style(builder: Builder, style: Style) -> Builder

Sets the high-level formatting style. Pairs with with_currency and with_unit for the corresponding StyleCurrency and StyleUnit cases.

with_trailing_zero_display

</> 
pub fn with_trailing_zero_display(
  builder: Builder,
  trailing_zero_display: intl.TrailingZeroDisplay,
) -> Builder

Sets whether trailing fraction zeros are stripped from integer values.

with_unit

</> 
pub fn with_unit(builder: Builder, unit: String) -> Builder

Sets the measurement unit identifier (e.g., "meter", "kilometer-per-hour"). Used when the style is StyleUnit.

with_unit_display

</> 
pub fn with_unit_display(
  builder: Builder,
  unit_display: UnitDisplay,
) -> Builder

Sets how the unit is presented.

with_use_grouping

</> 
pub fn with_use_grouping(
  builder: Builder,
  use_grouping: UseGrouping,
) -> Builder

Sets whether and when grouping separators are inserted.

✨ Search Document