glecimal - v1.2.0

glecimal/notation

Decimals as people write them: 1.234,56 in Brazil, 1,234.56 in the United States. A notation is named by its locale’s BCP 47 tag (notation.pt_br, or for_locale("pt-BR") for a tag from a browser), with the separators CLDR gives that locale. format writes a value for display and parse reads a form field back, strictly: digit groups have exactly three digits or are not used at all, a grouped number never starts with a zero group, and the bounds of glecimal.parse apply. So 0.500 typed into a Brazilian field is refused rather than read as five hundred.

import glecimal/notation

notation.format(amount, notation.pt_br)
// -> "1.234.567,89"
notation.parse("1.234,5", notation.pt_br)
// -> Ok(1234.5)

A notation carries separators only. Currency symbols, spacing and padding to a fixed scale are the caller’s: glecimal.rescale a value to two places before formatting it as an amount.

Types

Notation

opaque </>

The separators a text uses: a decimal separator, and a group separator between thousands, or none.

pub opaque type Notation

NotationError

</>

Why new refused a pair of separators.

pub type NotationError {
  InvalidSeparator(separator: String)
  SameSeparators
}

Constructors 

  • InvalidSeparator(separator: String)

    A separator must be one character that is not a digit or -; the group separator may also be empty, for no grouping.

  • SameSeparators

    The two separators are the same character.

Values

brazilian

</> 
pub const brazilian: Notation

Deprecated: Use notation.pt_br, or for_locale with the reader's locale

1.234.567,89: the separators of Brazil and much of Europe.

cldr_version

</> 
pub const cldr_version: String

The CLDR release behind for_locale and the locale constants.

de_ch

</> 
pub const de_ch: Notation

1'234'567.89: German in Switzerland (de-CH).

de_de

</> 
pub const de_de: Notation

1.234.567,89: German in Germany (de-DE).

decimal_separator

</> 
pub fn decimal_separator(notation: Notation) -> String

describe_error

</> 
pub fn describe_error(error: NotationError) -> String

A sentence for logs and messages.

en_gb

</> 
pub const en_gb: Notation

1,234,567.89: British English (en-GB).

en_us

</> 
pub const en_us: Notation

1,234,567.89: United States English (en-US).

english

</> 
pub const english: Notation

Deprecated: Use notation.en_us, or for_locale with the reader's locale

1,234,567.89: the separators of English-speaking countries.

for_locale

</> 
pub fn for_locale(tag: String) -> Result(Notation, Nil)

The notation CLDR gives a locale, from its BCP 47 tag: "pt-BR", "fr-FR", "de". Case does not matter, and _ may stand for -, so a POSIX name such as pt_BR works too.

A locale is in the table only when CLDR’s formatting of it is exactly what a notation produces: Latin digits, a group every three digits from the fourth, and an ASCII minus. Others return Error(Nil), among them es-ES, it-IT and pt-PT (no group under five digits), en-IN (groups of two) and sv-SE (a Unicode minus). There is no fallback from a region to its language, since pt-AO and pt write numbers differently; choose a fallback yourself, such as plain.

format

</> 
pub fn format(
  decimal: glecimal.Decimal,
  notation: Notation,
) -> String

The value at its own scale, with the notation’s separators.

fr_fr

</> 
pub const fr_fr: Notation

1 234 567,89 with narrow no-break spaces: French in France (fr-FR).

group_separator

</> 
pub fn group_separator(notation: Notation) -> String

locales

</> 
pub fn locales() -> List(String)

Every tag for_locale knows, as CLDR writes it.

new

</> 
pub fn new(
  decimal_separator decimal_separator: String,
  group_separator group_separator: String,
) -> Result(Notation, NotationError)

A notation with other separators, such as ' for Swiss grouping or a narrow no-break space (U+202F) for SI grouping.

parse

</> 
pub fn parse(
  text: String,
  notation: Notation,
) -> Result(glecimal.Decimal, glecimal.ParseError)

Reads -?digits(decimal-separator digits)?, where the integer digits are either ungrouped or grouped in threes. Where the group separator is a space, any space counts as one (a plain, no-break or narrow no-break space), and where it is an apostrophe, either ' or ’ does, since people type the plain character. The scale is kept as written, so "1.234,50" is 1234.50 in the Brazilian notation.

notation.parse("1.234,56", notation.pt_br)  // -> Ok(1234.56)
notation.parse("1234,56", notation.pt_br)   // -> Ok(1234.56)
notation.parse("12.34,5", notation.pt_br)
// -> Error(InvalidGrouping(position: 2))

plain

</> 
pub const plain: Notation

1234567.89: the canonical text, ungrouped.

pt_br

</> 
pub const pt_br: Notation

1.234.567,89: Brazilian Portuguese (pt-BR).

✨ Search Document