ExNumerlo

ExNumerlo is an Elixir library for rendering and parsing integers using various Unicode numeral systems. It supports 88 systems — from the modern positional scripts of South and Southeast Asia to ancient additive systems like Mayan and Kaktovik, and specialized mathematical and programmer bases.

Features

• Unified API: One function (ExNumerlo.convert/2) for all your conversion needs — encoding, decoding, and cross-system conversion.
• Auto-Detection: Intelligent source system detection for easy decoding. Pass from: explicitly when ambiguity matters.
• Broad Support: From Western Arabic to ancient Mayan and Kaktovik Iñupiaq numerals.
• Formatted Input: Support for separators (e.g., thousands separators) and +/- signs in positional systems.

Installation

Add ex_numerlo to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_numerlo, "~> 0.4.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs.

Usage

The sole public interface is ExNumerlo.convert/2, which handles encoding, decoding, and cross-system conversion.

Encoding Integers

To encode an integer (or a list of integers) into a specific numeral system:

ExNumerlo.convert(123, to: :devanagari)
# {:ok, "१२३"}

ExNumerlo.convert(2026, to: :roman)
# {:ok, "MMXXVI"}

ExNumerlo.convert([1, 2, 3], to: :roman)
# {:ok, ["I", "II", "III"]}

Decoding Strings

To decode an encoded string back to an integer, use the to: :integer option. You can specify the source system or let it be auto-detected:

# Explicit source
ExNumerlo.convert("१२३", from: :devanagari, to: :integer)
# {:ok, 123}

# Auto-detection
ExNumerlo.convert("MMXXVI", to: :integer)
# {:ok, 2026}

Cross-System Conversion

Convert directly between two numeral systems without going through an intermediate integer:

ExNumerlo.convert("MMXXVI", to: :egyptian)
# {:ok, "𓆼𓆼𓎆𓎆𓏺𓏺𓏺𓏺𓏺𓏺"}

ExNumerlo.convert("͵βκϛ", to: :roman)
# {:ok, "MMXXVI"}

Separator Support

Positional systems support custom separators for grouping:

ExNumerlo.convert(1234567, to: :arabic, separator: ",")
# {:ok, "1,234,567"}

ExNumerlo.convert("1.234.567", from: :arabic, to: :integer, separator: ".")
# {:ok, 1234567}

Supported Systems

The following 88 systems are currently supported. Examples show 123 (or a nearby value within each system's range); the range column notes supported inputs.

LLM Agent Instructions

Usage rules for LLM agents are provided in usage-rules.md for integration with the usage_rules tool.