View Source UkraineNbuqrEx.Amount (ukraine_nbuqr v0.1.0)

The UkraineNbuqrEx.Amount module handles parsing and formatting of monetary amounts for Ukrainian hryvnia (UAH) in the context of NBU QR codes.

The module provides functionality to:

  • Parse string amounts into a structured format
  • Validate monetary amounts according to NBU specifications
  • Format amounts back to strings in the required NBU QR code format

Summary

Types

t()

Amounts are represented as a struct with two fields

Functions

normalize/1 format amount by parsing and converting amount back to string

parse/1 cleans, splits, and validates the amount. It returns a struct with units and cents. If the amount is invalid, it returns an error tuple

to_str/1 converts Amount struct to string representation in Ukrainian hryvnas formatted compatible with NBU QR code specification (with cents only if it exists and correct decimal separator)

validate/1 validates amount structure according to NBU requirements.

Types

t()

@type t() :: %UkraineNbuqrEx.Amount{cents: String.t() | nil, units: String.t()}

Amounts are represented as a struct with two fields:

  • units: The whole number part of the amount (hryvnias)
  • cents: The decimal part of the amount (kopiykas), optional

Functions

normalize(value)

@spec normalize(value :: String.t()) :: String.t() | {:error, String.t()}

normalize/1 format amount by parsing and converting amount back to string

Examples

    iex> UkraineNbuqrEx.Amount.normalize("0123.40")
    "UAH123.4"

    iex> UkraineNbuqrEx.Amount.normalize("123")
    "UAH123"

parse(value)

@spec parse(String.t()) :: {:ok, t()} | {:error, String.t()}

parse/1 cleans, splits, and validates the amount. It returns a struct with units and cents. If the amount is invalid, it returns an error tuple

Examples

    iex> UkraineNbuqrEx.Amount.parse("123.45")
    {:ok, %UkraineNbuqrEx.Amount{units: "123", cents: "45"}}

to_str(error)

@spec to_str(t() | {:ok, t()}) :: String.t()

to_str/1 converts Amount struct to string representation in Ukrainian hryvnas formatted compatible with NBU QR code specification (with cents only if it exists and correct decimal separator)

validate(amount)

@spec validate(amount :: t() | {:ok, t()} | {:error, String.t()}) ::
  {:ok, t()} | {:error, String.t()}

validate/1 validates amount structure according to NBU requirements.

Validation rules include:

  • Units must be a non-negative integer not exceeding 999,999,999
  • If cents are present, they must be between 0 and 99
  • Overall amount format must conform to NBU QR code specifications

Delegate to UkraineNbuqrEx.Amount.Validator.validate/1

Parameters

  • amount: A struct containing the parsed amount with units and optional cents

Returns

  • {:ok, amount} if validation passes
  • {:error, message} if validation fails

Examples

    iex> UkraineNbuqrEx.Amount.validate(%UkraineNbuqrEx.Amount{units: "123", cents: "45"})
    {:ok, %UkraineNbuqrEx.Amount{units: "123", cents: "45"}}

    iex> UkraineNbuqrEx.Amount.validate(%UkraineNbuqrEx.Amount{units: "999999999", cents: nil})
    {:ok, %UkraineNbuqrEx.Amount{units: "999999999", cents: nil}}

    iex> UkraineNbuqrEx.Amount.validate(%UkraineNbuqrEx.Amount{units: "1000000000", cents: nil})
    {:error, "Amount greather then 999999999.99"}