# `NumberF.Formatter`
[🔗](https://github.com/jamesnjovu/elixir_number_functions/blob/v0.3.0/lib/number_f/formatter.ex#L1)

General formatting utilities for NumberF.

# `abbreviate_number`

Formats large numbers as K, M, B (e.g., 1.2K, 3.4M).

## Parameters
  - `number`: The number to abbreviate
  - `precision`: Number of decimal places (default: 1)

## Examples

    iex> NumberF.Formatter.abbreviate_number(1234)
    "1.2K"

    iex> NumberF.Formatter.abbreviate_number(1234567)
    "1.2M"

    iex> NumberF.Formatter.abbreviate_number(1234567890)
    "1.2B"

# `accounting_format`

Accounting format: negatives in parentheses rather than with a minus sign.

## Examples

    iex> NumberF.Formatter.accounting_format(-1234.56, unit: "$")
    "($1,234.56)"

    iex> NumberF.Formatter.accounting_format(1234.56, unit: "$")
    "$1,234.56"

# `decimal_to_fraction`

Formats a decimal as a fraction.

## Parameters
  - `decimal`: The decimal number to convert
  - `options`: Additional options
    - `:max_denominator`: Maximum allowed denominator (default: 1000)
    - `:mixed`: Whether to show as mixed number if improper (default: false)

## Examples

    iex> NumberF.Formatter.decimal_to_fraction(0.75)
    "3/4"

    iex> NumberF.Formatter.decimal_to_fraction(1.25, mixed: true)
    "1 1/4"

# `engineering_notation`

Formats a number in engineering notation (exponents are multiples of 3).

## Parameters
  - `number`: The number to format
  - `precision`: Number of decimal places (default: 2)

## Examples

    iex> NumberF.Formatter.engineering_notation(1234567)
    "1.23e6"

    iex> NumberF.Formatter.engineering_notation(0.000123)
    "123.0e-6"

# `format_bytes`

Human-readable byte size.

Pass `base: :binary` for KiB/MiB units (powers of 1024); the default is SI
(powers of 1000), which is what storage vendors and most operating systems print.

## Examples

    iex> NumberF.Formatter.format_bytes(1_500_000)
    "1.5 MB"

    iex> NumberF.Formatter.format_bytes(1_048_576, base: :binary)
    "1.0 MiB"

    iex> NumberF.Formatter.format_bytes(5_000_000_000_000)
    "5.0 TB"

# `format_duration`

Human-readable duration from a number of seconds.

Formats: `:short` (default) gives `"1h 2m 5s"`, `:long` gives
`"1 hour, 2 minutes, 5 seconds"`, `:clock` gives `"01:02:05"`.

## Examples

    iex> NumberF.Formatter.format_duration(3725)
    "1h 2m 5s"

    iex> NumberF.Formatter.format_duration(3725, format: :clock)
    "01:02:05"

    iex> NumberF.Formatter.format_duration(90, format: :long)
    "1 minute, 30 seconds"

# `format_fraction`

Formats a number as a fraction.

## Parameters
  - `numerator`: The numerator
  - `denominator`: The denominator
  - `options`: Additional options
    - `:reduce`: Whether to reduce to lowest terms (default: true)
    - `:mixed`: Whether to show as mixed number if improper (default: false)

## Examples

    iex> NumberF.Formatter.format_fraction(3, 4)
    "3/4"

    iex> NumberF.Formatter.format_fraction(6, 8)
    "3/4"

    iex> NumberF.Formatter.format_fraction(5, 4, mixed: true)
    "1 1/4"

# `format_percentage`

Formats a percentage with specified precision.

## Parameters
  - `value`: The value to calculate percentage for
  - `total`: The total value (100%)
  - `precision`: Number of decimal places (default: 2)
  - `options`: Additional options
    - `:symbol`: Whether to include % symbol (default: true)

## Examples

    iex> NumberF.Formatter.format_percentage(25, 100)
    "25.0%"

    iex> NumberF.Formatter.format_percentage(1, 3, 2)
    "33.33%"

    iex> NumberF.Formatter.format_percentage(1, 3, 2, symbol: false)
    "33.33"

# `format_phone`

Formats phone numbers based on country code.

## Parameters
  - `number`: The phone number as a string
  - `country_code`: The country code (default: "ZM" for Zambia)

## Examples

    iex> NumberF.Formatter.format_phone("260977123456", "ZM")
    "+260 97 712 3456"

    iex> NumberF.Formatter.format_phone("14155552671", "US")
    "+1 (415) 555-2671"

# `format_significant`

Formats to a number of significant figures, preserving trailing zeros.

## Examples

    iex> NumberF.Formatter.format_significant(1.5, 4)
    "1.500"

# `format_with_units`

Formats a number with custom prefix and suffix.

## Parameters
  - `number`: The number to format
  - `options`: Formatting options
    - `:prefix`: String to prepend (default: "")
    - `:suffix`: String to append (default: "")
    - `:precision`: Number of decimal places (default: 2)
    - `:thousands_separator`: Thousands separator (default: ",")

## Examples

    iex> NumberF.Formatter.format_with_units(1234.56, prefix: "$", suffix: " USD")
    "$1,234.56 USD"

    iex> NumberF.Formatter.format_with_units(98.6, suffix: "°F", precision: 1)
    "98.6°F"

# `from_roman`

Converts Roman numerals to Arabic numbers.

## Parameters
  - `roman`: The Roman numeral string

## Examples

    iex> NumberF.Formatter.from_roman("IV")
    4

    iex> NumberF.Formatter.from_roman("XLII")
    42

    iex> NumberF.Formatter.from_roman("MCMXCIX")
    1999

# `ordinal`

Converts numbers to ordinals (1st, 2nd, 3rd, etc.).

## Parameters
  - `number`: The number to convert

## Examples

    iex> NumberF.Formatter.ordinal(1)
    "1st"

    iex> NumberF.Formatter.ordinal(2)
    "2nd"

    iex> NumberF.Formatter.ordinal(3)
    "3rd"

    iex> NumberF.Formatter.ordinal(4)
    "4th"

# `pad_number`

Pads a number to a fixed width.

## Examples

    iex> NumberF.Formatter.pad_number(42, 6)
    "    42"

    iex> NumberF.Formatter.pad_number(42, 6, char: "0")
    "000042"

    iex> NumberF.Formatter.pad_number(42, 6, align: :left)
    "42    "

# `pluralize`

Pairs a count with a correctly pluralised noun.

Appends "s" unless an explicit plural is given, which covers the regular cases
without pretending to know English morphology.

## Examples

    iex> NumberF.Formatter.pluralize(1, "item")
    "1 item"

    iex> NumberF.Formatter.pluralize(3, "item")
    "3 items"

    iex> NumberF.Formatter.pluralize(3, "person", "people")
    "3 people"

# `scientific_notation`

Formats a number in scientific notation.

## Parameters
  - `number`: The number to format
  - `precision`: Number of decimal places (default: 2)

## Examples

    iex> NumberF.Formatter.scientific_notation(1234567)
    "1.23e6"

    iex> NumberF.Formatter.scientific_notation(0.000123, 3)
    "1.23e-4"

# `significant_figures`

Rounds to a number of significant figures.

## Precision

Significant figures count from the first non-zero digit, so this is scale
independent in a way that decimal-place rounding is not: three significant
figures keeps three meaningful digits whether the value is 1234 or 0.0001234.

## Examples

    iex> NumberF.Formatter.significant_figures(1234.5678, 3)
    1230.0

    iex> NumberF.Formatter.significant_figures(0.00012345, 3)
    0.000123

# `to_roman`

Converts Arabic numbers to Roman numerals.

## Parameters
  - `number`: The number to convert (1-3999)

## Examples

    iex> NumberF.Formatter.to_roman(4)
    "IV"

    iex> NumberF.Formatter.to_roman(42)
    "XLII"

    iex> NumberF.Formatter.to_roman(1999)
    "MCMXCIX"

# `with_sign`

Prefixes a number with an explicit sign.

## Examples

    iex> NumberF.Formatter.with_sign(42)
    "+42"

    iex> NumberF.Formatter.with_sign(-42)
    "-42"

    iex> NumberF.Formatter.with_sign(0, zero: " ")
    " 0"

---

*Consult [api-reference.md](api-reference.md) for complete listing*