Words Numbers #

A high-performance Dart and Flutter library for bidirectional conversion between English words and numbers. Parse compound number words into digits, clean speech-to-text sentences, convert numbers back into English words, and format checks and invoices with currency text.

✨ Features #

• 🧠 Compound Word-to-Number Engine: Parses full compound numbers from units up to quintillions ("five hundred twenty-two" $\rightarrow$ 522, "one million five hundred thousand" $\rightarrow$ 1500000).
• 🔄 Bidirectional (Numbers to Words): Convert integers into clear English words (1250 $\rightarrow$ "one thousand two hundred fifty"), with configurable conjunctions ("and") and hyphenation.
• 💵 Currency & Invoices: Generate check/receipt strings with dollars and cents (1250.50 $\rightarrow$ "one thousand two hundred and fifty dollars and fifty cents") or custom currencies (euros, pounds).
• 🎙️ Speech-to-Text Sentence Parser: Replaces number words inside sentences while preserving punctuation, newlines, and non-numeric text intact.
• 🔢 Decimals, Negatives & Ordinals: Supports signs ("minus forty-two" $\rightarrow$ -42), decimals ("three point one four" $\rightarrow$ 3.14), and ordinals ("twenty-first" $\rightarrow$ "21st" or 21).
• 🚀 Dart Extensions: Fluent syntax on String, int, and num ('forty-two'.toNum(), 42.toWords()).
• ⚡ Zero External Dependencies: Pure, lightweight Dart implementation that runs everywhere (Flutter, Web, Server, CLI).

📦 Installation #

Add words_numbers to your pubspec.yaml:

dependencies:
  words_numbers: ^0.1.0

Then import it in your Dart code:

import 'package:words_numbers/words_numbers.dart';

🚀 Quick Usage #

1. Compound Number Parsing #

Parse English number phrases into numeric values (int or double):

// Parse integers
num a = WordsNumbers.parse('five hundred twenty-two'); // 522
num b = WordsNumbers.parse('one million five hundred thousand'); // 1500000

// Parse decimals & signs
num pi = WordsNumbers.parse('three point one four'); // 3.14
num temp = WordsNumbers.parse('minus forty-two'); // -42

// Parse ordinals
num rank = WordsNumbers.parse('twenty-first'); // 21

// Safe parsing with tryParse
num? val = WordsNumbers.tryParse('one hundred and five'); // 105
num? invalid = WordsNumbers.tryParse('invalid string'); // null

2. Sentence & Speech-to-Text Processing #

Clean transcribed speech or text sentences by converting number words into digits while preserving surrounding text, punctuation, and newlines:

String text = 'I bought twenty-two apples for five hundred dollars.';
String result = WordsNumbers.convertTextNumberToString(text);
print(result);
// 'I bought 22 apples for 500 dollars.'

String transcript = 'The total was three point one four meters on the twenty-first day.';
print(WordsNumbers.convertTextNumberToString(transcript));
// 'The total was 3.14 meters on the 21st day.'

3. Number to Words (Bidirectional) #

Convert numbers to English words with options for conjunctions (and) and hyphenation:

// Standard conversion
WordsNumbers.toWords(42); 
// 'forty-two'

// Without hyphenation
WordsNumbers.toWords(42, hyphenate: false); 
// 'forty two'

// With 'and' conjunction
WordsNumbers.toWords(105, includeAnd: true); 
// 'one hundred and five'

WordsNumbers.toWords(1250, includeAnd: true); 
// 'one thousand two hundred and fifty'

// Large numbers
WordsNumbers.toWords(1500000); 
// 'one million five hundred thousand'

4. Currency & Invoice Formatting #

Generate formatted words for checks, receipts, and invoices:

// Standard USD dollars and cents
WordsNumbers.toCurrency(1250.50);
// 'one thousand two hundred and fifty dollars and fifty cents'

// Singular handling
WordsNumbers.toCurrency(1.01);
// 'one dollar and one cent'

// Custom currency
WordsNumbers.toCurrency(
  100,
  currencyWord: 'euros',
  centWord: 'cents',
);
// 'one hundred euros'

5. Fluent Dart Extensions #

Use convenient extensions directly on numbers and strings:

// String extensions
'forty-two'.toNum(); // 42
'I have twenty-two apples'.wordsToNumbers(); // 'I have 22 apples'

// Number extensions
42.toWords(); // 'forty-two'
105.toWords(includeAnd: true); // 'one hundred and five'
1250.50.toCurrencyWords(); // 'one thousand two hundred and fifty dollars and fifty cents'

📱 Interactive Playground Example #

The included example application demonstrates a full Material 3 playground:

• Speech-to-Text & Sentence Parser Tab: Live typing with real-time numeric conversion and preset chips.
• Numbers to Words & Currency Tab: Live word generation with toggleable hyphenation, conjunctions, and currency mode.
• One-Tap Copy: Quick clipboard copying for converted results.

To run the example:

cd example
flutter run

🧪 Testing #

The package includes an extensive test suite covering compound parsing, negative scales, decimals, ordinals, currency, sentence formatting, and backward compatibility:

flutter test

👨‍💻 Created & Maintained By #

Abdul Rehman

• GitHub: @arsarsars1
• LinkedIn: Abdul Rehman

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.