debian man page for text::roman

Roman(3pm)						User Contributed Perl Documentation						Roman(3pm)

NAME
       Text::Roman - Allows conversion between Roman and Arabic algarisms.

SYNOPSIS
	use Text::Roman qw/
	   isroman roman2int int2roman ismilhar milhar2int
	   roman mroman2int ismroman
	   /;

	print int2roman(123);

	$roman = "XXXV";
	print roman2int($roman) if isroman($roman);

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

DESCRIPTION
       This package supports both conventional Roman algarisms (which range from 1 to 3999) and Milhar Romans, a variation which 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 the range of this notation
       extends the range of Roman numbers to 3999 x 1000 + 3999 = 4,002,999.

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

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

       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 and 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 function names imported into its namespace.

       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   = Va?|IV|a
	   e   = X{1,3}?|X{0,3}IX|
	   ee  = IX|
	   f   = Le?|XLee?|e
	   g   = C{1,3}f?|C{0,3}XCee?|f
	   gg  = XCee?|f
	   h   = Dg?|CDgg?|g
	   j   = M{1,3}h?|M{0,3}CMgg?|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://www.estado.estadao.com.br/redac/norn-nro.html.

AUTHOR
       Erick Calder <ecalder@cpan.org>

ACKNOWLEDGEMENTS
       This module was originally written by Peter de Padua Krauss <krauss@ifqsc.sc.usp.br> and submitted to CPAN by Stanislaw Pusep <stanis@lin-
       uxmail.org> who has relinquished control to me since the original author has never maintained it and can no longer be reached.

       I 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.

AVAILABILITY + SUPPORT
       For questions, comments and support please feel free to e-mail me.  This module may be found on the CPAN.  Additionally, both the module
       and its RPM package are available from:

       http://perl.arix.com

DATE
       $Date: 2003/01/16 01:56:34 $

VERSION
       $Revision: 3.3 $

perl v5.8.8							    2007-06-15								Roman(3pm)