Search documentation of Localize

# Number Formatting & Parsing Cheatsheet

Copy Markdown View Source

## Formatting numbers

    Localize.Number.to_string(1234567.89)
    #=> {:ok, "1,234,567.89"}

### Locale-specific decimal formatting

Locale | `1234567.89` | Grouping style
--- | --- | ---
`:en` | `"1,234,567.89"` | Western (groups of 3)
`:de` | `"1.234.567,89"` | Period grouping, comma decimal
`:ja` | `"1,234,567.89"` | Western (same as English)
`:hi` | `"12,34,567.89"` | Indian (lakhs/crores)
`:fr` | `"1 234 567,89"` | Thin-space grouping, comma decimal

### Currency formatting

    Localize.Number.to_string(1234.56, currency: :USD, locale: :en)
    #=> {:ok, "$1,234.56"}

    Localize.Number.to_string(1234.56, currency: :EUR, locale: :de)
    #=> {:ok, "1.234,56 €"}

    Localize.Number.to_string(1234, currency: :JPY, locale: :ja)
    #=> {:ok, "￥1,234"}

### Accounting format (negative in parentheses)

    Localize.Number.to_string(1234.56, format: :accounting, currency: :USD)
    #=> {:ok, "$1,234.56"}

    Localize.Number.to_string(-1234.56, format: :accounting, currency: :USD)
    #=> {:ok, "($1,234.56)"}

### Percentage

    Localize.Number.to_string(0.456, format: :percent, locale: :en)
    #=> {:ok, "46%"}

    Localize.Number.to_string(0.456, format: :percent, locale: :de)
    #=> {:ok, "46 %"}

### Scientific notation

    Localize.Number.to_string(1234567.89, format: :scientific)
    #=> {:ok, "1.23456789E6"}

### Compact / short formats

    Localize.Number.to_string(1234567, format: :decimal_short)
    #=> {:ok, "1M"}

    Localize.Number.to_string(1234567890, format: :decimal_short)
    #=> {:ok, "1B"}

    Localize.Number.to_string(1234567, format: :decimal_long)
    #=> {:ok, "1 million"}

    Localize.Number.to_string(1234567, format: :currency_short, currency: :USD)
    #=> {:ok, "$1M"}

### Fractional digit control

    Localize.Number.to_string(42, fractional_digits: 2)
    #=> {:ok, "42.00"}

    Localize.Number.to_string(3.14159, max_fractional_digits: 2)
    #=> {:ok, "3.14"}

    Localize.Number.to_string(3.1, min_fractional_digits: 3)
    #=> {:ok, "3.100"}

### Number ranges

    Localize.Number.to_range_string(3..5)
    #=> {:ok, "3–5"}

    Localize.Number.to_range_string(3, 5, locale: :de)
    #=> {:ok, "3–5"}

### Format options summary

Option | Values | Default | Description
--- | --- | --- | ---
`:locale` | atom, string, `LanguageTag` | `Localize.get_locale()` | Formatting locale
`:format` | `:standard`, `:percent`, `:scientific`, `:currency`, `:accounting`, `:decimal_short`, `:decimal_long`, `:currency_short`, or a pattern string | `:standard` | Number format style
`:currency` | ISO 4217 atom (`:USD`, `:EUR`, etc.) | `nil` | Currency code (auto-selects currency format)
`:number_system` | `:default`, `:native`, `:traditional`, or a system name | `:default` | Digit system
`:rounding_mode` | `:half_even`, `:half_up`, `:down`, `:up`, `:ceiling`, `:floor` | `:half_even` | Rounding mode
`:fractional_digits` | integer | from format pattern | Sets both min and max fractional digits
`:min_fractional_digits` | integer | from format pattern | Minimum fractional digits (trailing zeros)
`:max_fractional_digits` | integer | from format pattern | Maximum fractional digits (rounds to fit)

## Parsing numbers

    Localize.Number.parse("1,234.56")
    #=> {:ok, 1234.56}

    Localize.Number.parse("1.234,56", locale: :de)
    #=> {:ok, 1234.56}

    Localize.Number.parse("-42.5")
    #=> {:ok, -42.5}

### Scanning for numbers in text

    Localize.Number.scan("The price is $1,234.56 per unit")
    #=> ["The price is $", 1234.56, " per unit"]

## Pre-validated options (hot-loop performance)

    # Validate once
    {:ok, options} = Localize.Number.Format.Options.validate_options(0, locale: :en, currency: :USD)

    # Reuse for many calls — skips per-call option resolution
    {:ok, _} = Localize.Number.to_string(1234.56, options)
    {:ok, _} = Localize.Number.to_string(9876.54, options)

← Previous Page Date, Time & DateTime Formatting Cheatsheet
Next Page → Unit Formatting Cheatsheet