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

Feature	num2words_plus
Nepali language	✅
English language	✅
Nepali numbering system	✅
Offline conversion	✅
Zero runtime dependencies	✅
Custom currency units	✅
cheque formatting	✅
Ordinals	✅
Year formatting	✅
Phone digit spelling	✅

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

Language	v1.0.0 status
Nepali	Supported
English	Supported

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.