glecimal/notation

Decimals as people write them: 1.234,56 in Brazil, 1,234.56 in English. 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.brazilian)
// -> "1.234.567,89"
notation.parse("1.234,5", notation.brazilian)
// -> 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

1.234.567,89: Brazil, and most of continental Europe.

decimal_separator

</>

pub fn decimal_separator(notation: Notation) -> String

describe_error

</>

pub fn describe_error(error: NotationError) -> String

A sentence for logs and messages.

english

</>

pub const english: Notation

1,234,567.89: English-speaking countries.

format

</>

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

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

group_separator

</>

pub fn group_separator(notation: Notation) -> String

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. The scale is kept as written, so "1.234,50" is 1234.50 in the Brazilian notation.

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

plain

</>

pub const plain: Notation

1234567.89: the canonical text, ungrouped.