num2words_plus #

num2words_plus converts numbers to words for Dart and Flutter apps that need offline, deterministic wording for accounting, invoicing, banking, receipts, and other money-adjacent workflows.

Version 1.0.0 supports Nepali and English with Nepali numbering-system scale names such as लाख, करोड, अर्ब, lakh, crore, and arab.

Features #

• Nepali and English output in v1.0.0.
• Nepali numbering-system grouping and scale names.
• Callable converter API: converter(1234).
• Validated string API: converter.parse('1234.56').
• Modes for standard numbers, ordinals, years, phone/ID digits, and English cheque/check formatting.
• Optional currency unit and subunit labels.
• Domain-specific exceptions for format, range, and mode errors.
• Zero runtime dependencies.

Feature Comparison #

Installation #

Add the package to your pubspec.yaml:

dependencies:
  num2words_plus: ^1.0.0

Then import it:

import 'package:num2words_plus/num2words_plus.dart';

Quick Start #

const nepali = Num2WordsPlus();

print(nepali(1234));
// एक हजार दुई सय चौँतीस

print(nepali.parse('1234.56'));
// एक हजार दुई सय चौँतीस दशमलव पाँच छ

const english = Num2WordsPlus(language: Num2WordsLanguage.english);

print(english(100000));
// one lakh

print(english(10000000));
// one crore

Currency Units #

Standard mode can include currency units when you provide primaryUnit and secondaryUnit. Subunits are always spelled out in words, never as fraction notation.

const nepaliMoney = Num2WordsPlus(
  primaryUnit: 'रुपैयाँ',
  secondaryUnit: 'पैसा',
);

print(nepaliMoney.parse('1234.56'));
// एक हजार दुई सय चौँतीस रुपैयाँ, छपन्न पैसा

const englishMoney = Num2WordsPlus(
  language: Num2WordsLanguage.english,
  primaryUnit: 'rupees',
  secondaryUnit: 'paisa',
);

print(englishMoney.parse('1234.56'));
// one thousand two hundred thirty-four rupees and fifty-six paisa

Modes #

Standard #

Num2WordsMode.standard is the default mode.

const converter = Num2WordsPlus(language: Num2WordsLanguage.english);

print(converter(123456789));
// twelve crore thirty-four lakh fifty-six thousand seven hundred eighty-nine

Ordinal #

const nepaliOrdinal = Num2WordsPlus(mode: Num2WordsMode.ordinal);

print(nepaliOrdinal(1));
// पहिलो

print(nepaliOrdinal(21));
// एक्काइसौं

const englishOrdinal = Num2WordsPlus(
  language: Num2WordsLanguage.english,
  mode: Num2WordsMode.ordinal,
);

print(englishOrdinal(21));
// twenty-first

Year #

const nepaliYear = Num2WordsPlus(mode: Num2WordsMode.year);

print(nepaliYear(2077));
// दुई हजार सतहत्तर

const englishYear = Num2WordsPlus(
  language: Num2WordsLanguage.english,
  mode: Num2WordsMode.year,
);

print(englishYear(2024));
// two thousand twenty-four

Phone / ID #

Phone mode spells each digit independently and ignores letterCase.

const phone = Num2WordsPlus(mode: Num2WordsMode.phone);

print(phone.parse('9841234567'));
// नौ आठ चार एक दुई तीन चार पाँच छ सात

Check #

Check mode is English-only in v1.0.0. Using it with Nepali throws Num2WordsModeException.

const check = Num2WordsPlus(
  language: Num2WordsLanguage.english,
  letterCase: Num2WordsLettercase.titlecase,
  mode: Num2WordsMode.check,
);

print(check.parse('1234.56'));
// One Thousand Two Hundred Thirty-Four Rupees and Fifty-Six Paisa

Letter Case #

const uppercase = Num2WordsPlus(
  language: Num2WordsLanguage.english,
  letterCase: Num2WordsLettercase.uppercase,
);

print(uppercase(21));
// TWENTY-ONE

Supported values:

• Num2WordsLettercase.lowercase
• Num2WordsLettercase.uppercase
• Num2WordsLettercase.titlecase
• Num2WordsLettercase.sentencecase

Validation and Errors #

All string input is validated before conversion.

try {
  const converter = Num2WordsPlus();
  converter.parse('1.2.3');
} on Num2WordsFormatException catch (error) {
  print(error.message);
}

Exception types:

• Num2WordsFormatException: empty strings, negative numbers, signed input, non-numeric characters, multiple decimal points, or empty currency units.
• Num2WordsRangeException: integer part exceeds 18 digits.
• Num2WordsModeException: unsupported language or mode/language combination, such as check mode with Nepali.

Every exception message includes the invalid input, the violated rule, and an example of valid input.

Supported Range #

The integer part may contain up to 18 normalized digits. Leading zeroes do not count against the limit.

const converter = Num2WordsPlus(language: Num2WordsLanguage.english);

print(converter.parse('100000000000000000'));
// one shankh

Inputs with 19 or more normalized integer digits throw Num2WordsRangeException.

Language Support #

Development #

dart pub get
dart analyze
dart test

The package is built with Dart SDK >=3.2.0 <4.0.0.

Flutter Web Demo #

The example/ directory contains a Flutter web app for trying the converter interactively.

cd example
flutter pub get
flutter run -d web-server

Documentation #

• 📖 Contributing Guide
• 🔒 Security Policy
• 📝 Changelog

License #

See LICENSE.