1Text::Roman(3)        User Contributed Perl Documentation       Text::Roman(3)
2
3
4

NAME

6       Text::Roman - Allows conversion between Roman and Arabic algarisms.
7

VERSION

9       version 3.5
10

SYNOPSIS

12           #!/usr/bin/env perl
13           use strict;
14           use warnings;
15           use Text::Roman qw(:all);
16
17           print int2roman(123), "\n";
18
19           my $roman = "XXXV";
20           print roman2int($roman), "\n" if isroman($roman);
21
22           my $milhar = 'L_X_XXIII'; # = 60,023
23           print milhar2int($milhar), "\n" if ismilhar($milhar);
24

DESCRIPTION

26       This package supports both conventional Roman algarisms (which range
27       from 1 to 3999) and Milhar Romans, a variation which uses a bar across
28       the algarism to indicate multiplication by 1_000.  For the purposes of
29       this module, acceptable syntax consists of an underscore suffixed to
30       the algarism e.g. IV_V = 4_005.  The term Milhar apparently derives
31       from the Portuguese word for "thousands" and the range of this notation
32       extends the range of Roman numbers to 3999 * 1000 + 3999 = 4_002_999.
33
34       Note: the functions in this package treat Roman algarisms in a case-
35       insensitive manner such that "VI" == "vI" == "Vi" == "vi".
36
37       The following functions may be imported into the caller package by
38       name:
39

FUNCTIONS

41   isroman
42       Tests a string to be a valid Roman algarism.  Returns a boolean value.
43
44   int2roman
45       Converts an integer expressed in Arabic numerals, to its corresponding
46       Roman algarism.  If the integer provided is out of the range
47       expressible in Roman notation, an undef is returned.
48
49   roman2int
50       Does the converse of "int2roman", converting a Roman algarism to its
51       integer value.
52
53   ismilhar
54       Determines whether a string qualifies as a Milhar Roman algarism.
55
56   milhar2int
57       Converts a Milhar Roman algarism to an integer.
58
59   ismroman/mroman2int/roman
60       These functions belong to the module's old interface and are considered
61       deprecated.  Do not use them in new code and they will eventually be
62       discontinued; they map as follows:
63
64       •   ismroman      => ismilhar
65
66       •   mroman2int    => milhar2int
67
68       •   roman         => int2roman
69

CHANGES

71       Some changes worth noting from this module's previous incarnation:
72
73       namespace imports
74           The call to use must now explicitly request function names imported
75           into it's namespace.
76
77       argument defaults/void context
78           All functions now will operate on $_ when no arguments are passed,
79           and will set $_ when called in a void context.  This allows for
80           writing code like:
81
82               @x = qw/V III XI IV/;
83               roman2int() for @x;
84               print join("-", @x);
85
86           instead of the uglier:
87
88               @x = qw/V III XI IV/;
89               $_ = roman2int($_) for @x;
90               print join("-", @x);
91

SPECIFICATION

93       Roman algarisms may be described using the following BNF-like formula:
94
95           a   = I{1,3}
96           b   = V\a?|IV|\a
97           e   = X{1,3}\b?|X{0,3}IX|\b
98           ee  = IX|\b
99           f   = L\e?|XL\ee?|\e
100           g   = C{1,3}\f?|C{0,3}XC\ee?|\f
101           gg  = XC\ee?|\f
102           h   = D\g?|CD\gg?|\g
103           j   = M{1,3}\h?|M{0,3}CM\gg?|\h
104

REFERENCES

106       For a description of the Roman numeral system see:
107       <http://www.novaroma.org/via_romana/numbers.html>.  A reference to
108       Milhar Roman alagarisms (in Portuguese) may be found at:
109       <http://web.archive.org/web/20020819094718/http://www.estado.com.br/redac/norn-nro.html>.
110

ACKNOWLEDGEMENTS

112       This module was originally written by Peter de Padua Krauss and
113       submitted to CPAN by Stanislaw Pusep <https://metacpan.org/author/SYP>
114       who has relinquished control to Erick Calder
115       <https://metacpan.org/author/ECALDER> since the original author has
116       never maintained it and can no longer be reached.
117
118       Erick have completely rewritten the module, implementing simpler
119       algorithms to perform the same functionality, adding a test suite, a
120       Changes file, etc. and providing more comprehensive documentation.
121
122       Ten years later, Stanislaw returned as a maintainer.
123

AUTHOR

125       Stanislaw Pusep <stas@sysd.org>
126
128       This software is copyright (c) 2003 by Erick Calder <ecalder@cpan.org>.
129
130       This is free software; you can redistribute it and/or modify it under
131       the same terms as the Perl 5 programming language system itself.
132
133
134
135perl v5.38.0                      2023-07-21                    Text::Roman(3)
Impressum