Search packages, repositories and app categories

Package detailsv2.3.2

numerus

Dart extensions for translating integers to Roman numerals and Roman numeral strings to integers.

AndroidiOSWebmacOSWindowsLinux
30-day downloads
74.1K
Likes
18
Pub points
160

Install package

flutter pub add numerus

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

Numerus is a Dart package that provides extensions for converting integers to Roman numerals and vice versa. It simplifies working with Roman numeral representations by offering intuitive methods directly on integer and string types. Ideal for educational apps, historical data processing, or any application requiring Roman numeral formatting. The package supports all major platforms including Android, iOS, Web, macOS, Windows, and Linux, ensuring broad compatibility. With clean, minimal syntax, it enhances code readability and reduces boilerplate when handling numeral conversions.

Use cases

  • Converting dates to Roman numerals
  • Educational apps for number systems
  • Historical document digitization
  • Displaying chapter numbers in Roman style
  • Game score tracking with Roman numerals

Key features

  • Simple integer-to-Roman conversion
  • String-to-integer parsing
  • Dart extension methods
  • Cross-platform support
  • Minimal API surface
  • Robust error handling

Suitable for

  • Developers building math tools
  • Educational software
  • Apps with historical themes
  • Projects needing readable numeral formats
  • Users preferring concise syntax

Considerations

  • Only handles standard Roman numerals (no subtractive variants beyond common rules)
  • Does not support very large numbers (>3999) due to Roman numeral limitations
  • No localization support for non-Latin scripts
  • Requires manual validation for edge cases like invalid input strings

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

Numerus

Dart extensions for translating decimal numbers to Roman numerals and vice versa.

  • Negative numbers are not supported.
  • Functions will return null in place of generating nonsense.
  • Zero can be specified as an option to the RomanNumeralConfig.
  • "Common" Roman numeral format used in modern times (i.e. MDCLXVI) is the default RomanNumeralConfig style. There are other styles: vinculum, apostrophus, and a compact apostrophus that uses single Unicode characters instead of tally marks. See the example below.

Coverage

Examples

import 'package:numerus/numerus.dart';

void main() {
  /// 1) Nice and easy, default config is the "common" config.

  var n = 418;
  print(n.toRomanNumeralString());
  // 'CDXVIII'

  var str = 'CDXVIII';
  print(str.isValidRomanNumeralValue());
  // true
  print(str.toRomanNumeralValue());
  // 418

  /// 2) You can specify other [RomanNumeralConfig]'s to change the style.
  /// You can set the config globally, if you'd like.
  RomanNumerals.romanNumeralsConfig = VinculumRomanNumeralsConfig();

  /// 3) Vinculum config style
  n = 3449671;
  print(n.toRomanNumeralString());
  // M̅M̅M̅C̅D̅X̅L̅MX̅DCLXXI

  str = 'M̅M̅M̅C̅D̅X̅L̅MX̅DCLXXI';
  print(str.isValidRomanNumeralValue());
  // true
  print(str.toRomanNumeralValue());
  // 3449671

  /// 4) You can specify the config inline, too.
  /// 5) Apostrophus style
  n = 2449671;
  print(n.toRomanNumeralString(config: ApostrophusRomanNumeralsConfig()));
  // CCCCIↃↃↃↃCCCCIↃↃↃↃCCCIↃↃↃIↃↃↃↃCCIↃↃIↃↃↃCIↃCCIↃↃIↃCLXXI

  /// 6) ... but frankly, globally set is probably the most common use case
  RomanNumerals.romanNumeralsConfig = ApostrophusRomanNumeralsConfig();

  str = 'CCCCIↃↃↃↃCCCCIↃↃↃↃCCCIↃↃↃIↃↃↃↃCCIↃↃIↃↃↃCIↃCCIↃↃIↃCLXXI';
  print(str.isValidRomanNumeralValue());
  // true
  print(str.toRomanNumeralValue());
  // 2449671

  /// 7) The compact Apostrophus style uses special Unicode characters
  /// just for these symbols.
  RomanNumerals.romanNumeralsConfig = CompactApostrophusRomanNumeralsConfig();
  n = 347449;
  print(n.toRomanNumeralString());
  // ↈↈↈↂↇↁↀↀCCCCXLIX

  // NOTE: if you see missing characters in this example, then you'll need to
  // install a font that supports them.
  str = 'ↈↈↈↂↇↁↀↀCCCCXLIX';
  print(str.isValidRomanNumeralValue());
  // true
  print(str.toRomanNumeralValue());
  // 347449

  /// 8) You can specify a "nulla" (zero placeholder) if you want
  /// to support zero easily.
  RomanNumerals.romanNumeralsConfig = CommonRomanNumeralsConfig(nulla: 'N');
  n = 0;
  print(n.toRomanNumeralString());
  // N

  str = 'N';
  print(str.isValidRomanNumeralValue());
  // true
  print(str.toRomanNumeralValue());
  // 0
}

Features and bugs

Please file feature requests and bugs at the issue tracker.

Local development

Set up an environment for local development
  • Install Dart or Flutter
  • Install the coverage tool
    $ dart pub global activate coverage
    
  • Install lcov on your system. e.g. macOS with brew:
    $ brew install lcov
    
Generate code coverage from tests
$ ./bin/coverage-gen
# If you are on macOS and would like the report to immediately
# open, then run the following (not suitable for automation):
$ ./bin/coverage-gen -i

Categories

Dependencies

Dependency list 1 items

Source repository

Projects using this package