ethiopian_birr 0.1.0

Format Ethiopian Birr in Amharic and Latin script, including Amharic amount-in-words, Ge'ez numerals, and ETB string parsing. Pure Dart, zero dependencies.

ethiopian_birr

Pure-Dart, zero-dependency formatting for Ethiopian Birr — the Amharic/Ethiopia-specific layer that intl doesn't cover.

import 'package:ethiopian_birr/ethiopian_birr.dart';

void main() {
  print(Birr.toWords(1234.56));
  // አንድ ሺህ ሁለት መቶ ሠላሳ አራት ብር ከሃምሳ ስድስት ሳንቲም
}

Amount-in-words is the reason to install this package: it's needed for invoices, receipts, contracts, and cheques, and nothing else on pub.dev does it. Everything else — Amharic/Latin currency formatting, Ge'ez numerals, santim splitting, and parsing — supports that same use case.

Why not just intl?

intl's NumberFormat.currency already formats ETB in Latin as Br 1,234.56. This package doesn't re-implement that. It fills in what intl structurally can't:

1. Amharic-script currency output — ብር instead of Br.
2. Ge'ez numerals — rendering whole-birr amounts with ፩፪፫-style digits, using the classical additive numeral system.
3. Amharic amount-in-words — the headline feature above.

The core is pure Dart with zero runtime dependencies.

Installation

dependencies:
  ethiopian_birr: ^0.1.0

Usage

Amount in words

Birr.toWords(1);        // አንድ ብር
Birr.toWords(0.56);     // ሃምሳ ስድስት ሳንቲም
Birr.toWords(100);      // መቶ ብር
Birr.toWords(1234.56);  // አንድ ሺህ ሁለት መቶ ሠላሳ አራት ብር ከሃምሳ ስድስት ሳንቲም
Birr.toWords(1000000);  // አንድ ሚሊዮን ብር

Formatting

Birr.format(1234.5);                                   // Br 1,234.50
Birr.format(1234.5, format: BirrFormat.amharic);        // 1,234.50 ብር
Birr.format(1234.5, format: const BirrFormat(
  symbolPosition: SymbolPosition.after,
));                                                      // 1,234.50 ETB
Birr.format(1234.5, format: const BirrFormat(
  grouping: false,
  decimalDigits: 0,
));                                                      // Br 1234

decimalDigits is always derived from the same rounded santim value (via Birr.split), so different decimalDigits settings never disagree about what the "true" rounded amount is — the original amount is only ever rounded once.

Ge'ez numerals

Birr.format(1234, format: BirrFormat.geez);     // ብር ፲፪፻፴፬
Birr.format(100, format: BirrFormat.geez);      // ብር ፻
Birr.format(1000000, format: BirrFormat.geez);  // ብር ፻፼

Ge'ez numerals use the classical base-100 additive system, not a digit-by-digit swap of Arabic numerals: 100 is ፻ (not ፩፻), and 1234 is ፲፪፻፴፬ (twelve-hundred thirty-four). Since Ge'ez has no zero glyph, decimalDigits/grouping are ignored in this mode and an amount that rounds to zero whole birr throws ArgumentError.

Splitting and parsing

Birr.split(1234.56);        // (1234, 56)
Birr.split(-0.56);          // (0, -56)

Birr.parse('Br 1,234.56');  // 1234.56
Birr.parse('1,234.56 ETB'); // 1234.56
Birr.parse('1,234.56 ብር');  // 1234.56

Extension methods

1234.56.toBirr();       // Br 1,234.56
1234.56.toBirrWords();  // አንድ ሺህ ሁለት መቶ ሠላሳ አራት ብር ከሃምሳ ስድስት ሳንቲም

See example/main.dart for a runnable invoice-line demo covering all of the above.

Orthographic note

Amharic has letter variants for some words (e.g. ሦስት/ሶስት, ሠላሳ/ሰላሳ). This package defaults to ሦስት/ሠላሳ; the word maps (amharicUnits, amharicTens, etc.) are exposed as public constants for reference.

Status

Rounding is 2 decimal places (ties away from zero), performed once via Birr.split; all other output is derived from that single rounding. Birr.parse accepts Western Arabic digits only — it does not parse Ge'ez numeral strings.

License

MIT