Text::Roman(3)

🎀 NAME 🎀

Text::Roman(3) — yes bestie, this page is filed under User Contributed Perl Documentation — is the module that lets you convert between Roman and Arabic algarisms. It’s giving “Latin class but make it CPAN” and honestly it ate. 💅

---

🌸 VERSION 🌸

version 3.5 — periodt.

---

✨ SYNOPSIS ✨

#!/usr/bin/env perl
use strict;
use warnings;
use Text::Roman qw(:all);

print int2roman(123), "\n";

my $roman = "XXXV";
print roman2int($roman), "\n" if isroman($roman);

my $milhar = 'L_X_XXIII'; # = 60,023
print milhar2int($milhar), "\n" if ismilhar($milhar);

---

🦋 DESCRIPTION 🦋

okay so this package supports both conventional Roman algarisms, which range from 1 to 3999, and Milhar Romans — a variation that uses a bar across the algarism to indicate multiplication by 1_000. For the purposes of this module, acceptable syntax consists of an underscore suffixed to the algarism, e.g. IV_V = 4_005. The term Milhar apparently derives from the Portuguese word for “thousands”, and this notation extends the range of Roman numbers to:

3999 * 1000 + 3999 = 4_002_999

Note, bestie: the functions in this package treat Roman algarisms in a case-insensitive manner such that "VI" == "vI" == "Vi" == "vi". Slay. ✨

The following functions may be imported into the caller package by name:

---

💅 FUNCTIONS 💅

🌟 isroman

Tests a string to be a valid Roman algarism. Returns a boolean value.

🌟 int2roman

Converts an integer expressed in Arabic numerals to its corresponding Roman algarism. If the integer provided is out of the range expressible in Roman notation, an undef is returned.

🌟 roman2int

Does the converse of int2roman, converting a Roman algarism to its integer value.

🌟 ismilhar

Determines whether a string qualifies as a Milhar Roman algarism.

🌟 milhar2int

Converts a Milhar Roman algarism to an integer.

🌟 ismroman/mroman2int/roman

These functions belong to the module’s old interface and are considered deprecated. Do not use them in new code — they will eventually be discontinued. They map as follows:

• ismroman => ismilhar
• mroman2int => milhar2int
• roman => int2roman

---

🔥 CHANGES 🔥

Some changes worth noting from this module’s previous incarnation:

🎀 namespace imports

The call to use must now explicitly request the function names imported into its namespace. Like, you have to ask for what you want now. no cap.

🎀 argument defaults/void context

All functions now will operate on $_ when no arguments are passed, and will set $_ when called in a void context. This allows for writing code like:

@x = qw/V III XI IV/;
roman2int() for @x;
print join("-", @x);

instead of the uglier:

@x = qw/V III XI IV/;
$_ = roman2int($_) for @x;
print join("-", @x);

---

🌈 SPECIFICATION 🌈

Roman algarisms may be described using the following BNF-like formula:

a   = I{1,3}
b   = V\a?|IV|\a
e   = X{1,3}\b?|X{0,3}IX|\b
ee  = IX|\b
f   = L\e?|XL\ee?|\e
g   = C{1,3}\f?|C{0,3}XC\ee?|\f
gg  = XC\ee?|\f
h   = D\g?|CD\gg?|\g
j   = M{1,3}\h?|M{0,3}CM\gg?|\h

---

🍓 REFERENCES 🍓

For a description of the Roman numeral system see: <http://www.novaroma.org/via_romana/numbers.html>.

A reference to Milhar Roman alagarisms (in Portuguese) may be found at: <http://web.archive.org/web/20020819094718/http://www.estado.com.br/redac/norn-nro.html>.

---

🧚 ACKNOWLEDGEMENTS 🧚

This module was originally written by Peter de Padua Krauss and submitted to CPAN by Stanislaw Pusep (<https://metacpan.org/author/SYP>), who has relinquished control to Erick Calder (<https://metacpan.org/author/ECALDER>) since the original author has never maintained it and can no longer be reached.

Erick have completely rewritten the module, implementing simpler algorithms to perform the same functionality, adding a test suite, a Changes file, etc. and providing more comprehensive documentation. (We’re keeping the facts, bestie.) 💖

Ten years later, Stanislaw returned as a maintainer. Character development fr fr.

---

👑 AUTHOR 👑

Stanislaw Pusep <stas@sysd.org>

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2003 by Erick Calder <ecalder@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

okay bye bestie — this was Text::Roman(3) from perl v5.42.0, dated 2025-02-10 💖✨