Macaw.Data.Format.Locale (macaw_data v0.18.0)

View Source

How a locale writes numbers (spec/05 §3): a d3-format locale definition, as data.

FieldEnglishWhat it is
decimal"."the decimal point
thousands","the group separator
grouping[3]the group sizes from the right, used in turn and again from the first
currency{"$", ""}what the $ symbol writes before and after the number
minus"-"the minus sign (d3's default is −, U+2212)
nan"NaN"a value that is no number
percent"%"the percent sign of the % and p types
symbolsUSD $, EUR €, GBP £, JPY ¥the ISO 4217 codes written by a symbol
periodsAM, PMa time's period on a twelve-hour clock
days, short_daysSunday … Saturday, Sun … Satthe weekdays, from Sunday
months, short_monthsJanuary … December, Jan … Decthe months

A locale is the viewer's choice, as the unit system is: nothing is derived from it.

iex> {:ok, german} = Macaw.Data.Format.Locale.new(decimal: ",", thousands: ".", currency: {"", " €"})
iex> Macaw.Data.Format.number(Macaw.Data.Format.parse!("$,.2f", locale: german), 1234.5)
"1.234,50 €"

Summary

Functions

English, the default: . and ,, groups of three, $, the hyphen-minus.

A locale from a keyword list or a map of the fields in the table, each one absent being English's (spec/05 §3): {:ok, locale} or {:error, faults}.

As new/1, the locale alone, raising Macaw.Data.Error with the faults in Macaw.Data.Format.format_error/1's words.

Types

t()

@type t() :: %Macaw.Data.Format.Locale{
  currency: {String.t(), String.t()},
  days: [String.t()],
  decimal: String.t(),
  grouping: [pos_integer()],
  minus: String.t(),
  months: [String.t()],
  nan: String.t(),
  percent: String.t(),
  periods: [String.t()],
  short_days: [String.t()],
  short_months: [String.t()],
  symbols: %{required(String.t()) => String.t()},
  thousands: String.t()
}

Functions

english()

@spec english() :: t()

English, the default: . and ,, groups of three, $, the hyphen-minus.

iex> Macaw.Data.Format.Locale.english().grouping
[3]

new(fields)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, [{[term()], term()}, ...]}

A locale from a keyword list or a map of the fields in the table, each one absent being English's (spec/05 §3): {:ok, locale} or {:error, faults}.

A key it does not take is {[key], :unknown_key}; a field of the wrong kind {[key], {:type, kind}}, kind being :text, :grouping, :currency or :symbols; a list of names of the wrong length or holding anything but strings {[key], {:names, n}}; a symbol under a code not in the ISO table {[:symbols, code], {:unknown_currency, code}}; fields that are neither a keyword list nor a map {[], {:type, :keyword}}.

iex> Macaw.Data.Format.Locale.new(%{decimal: 1, grouping: [0]})
{:error, [{[:decimal], {:type, :text}}, {[:grouping], {:type, :grouping}}]}

new!(fields)

@spec new!(keyword() | map()) :: t()

As new/1, the locale alone, raising Macaw.Data.Error with the faults in Macaw.Data.Format.format_error/1's words.