bionic (3) Lingua::ES::Numeros.3pm.gz
NAME
Lingua::ES::Numeros - Translates numbers to spanish text
SYNOPSIS
use Lingua::ES::Numeros ":constants";
my $obj = new Lingua::ES::Numeros ('MAYUSCULAS' => 1);
print $obj->cardinal(124856), "\n";
print $obj->real(124856.531), "\n";
$obj->{GENERO} = FEMALE;
print $obj->ordinal(124856), "\n";
DESCRIPTION
This module supports the translation of cardinal, ordinal and, real numbers, the module handles integer
numbers up to vigintillions (that's 1e120), since Perl does not handle such numbers natively, numbers are
kept as text strings because processing does not justify using bigint.
Currently Lingua::ES::Numeros handles numbers up to 1e127-1 (999999 vigintillions).
METHODS
CONSTRUCTOR: new
To create a new Lingua::ES::Numeros, use the new class method. This method can receive as parameters any
of the above mentioned fields.
Examples:
use Lingua::ES::Numeros ':constants';
# Use the fields' default values
$obj = new Lingua::ES::Numeros;
# Specifies the values of some of them
$obj = Lingua::ES::Numeros->new( ACENTOS => 0,
MAYUSCULAS => 1, GENERO => FEMALE,
DECIMAL => ',', SEPARADORES=> '"_' );
DECIMAL
Specifies the character string that will be used to separate the integer from the fractional part of
the number to convert. The default value for DECIMAL is '.'
SEPARADORES
Character string including all of the format characters used when representing a number. All of the
characters in this string will be ignored by the parser when analyzing the number. The default value
for SEPARADORES is '_'
ACENTOS
Affects the way in which the generated string for the translated numbers is given; if it is false,
the textual representation will not have any accented characters. The default value for this field is
true (with accents).
MAYUSCULAS
If this is a true value, the textual representation of the number will be an uppercase character
string. The default value for this field is false (lowercase).
HTML
If this is a true value, the textual representation of the number will be a HTML-valid string
character (accents will be represented by their respective HTML entities). The default value is 0
(text).
GENERO
The gender of the numbers can be MALE, FEMALE or NEUTRAL, respectively for femenine, masculine or
neutral numbers. The default value is MALE.
The following table shows the efect of GENDER on translation of Cardinal and Ordinal numbers:
+---+---------------------+-----------------------------+
| N | CARDINAL | ORDINAL |
| u +------+------+-------+---------+---------+---------+
| m | MALE |FEMALE|NEUTRAL| MALE | FEMALE | NEUTRAL |
+---+------+------+-------+---------+---------+---------+
| 1 | uno | una | un | primero | primera | primer |
| 2 | dos | dos | dos | segundo | segunda | segundo |
| 3 | tres | tres | tres | tercero | tercera | tercer |
+---+------+------+-------+---------+---------+---------+
The constants MALE, FEMALE and NEUTRAL and their spanish counterparts MASCULINO, FEMENINO and NEUTRO,
may be imported with the tag ":constants" on module use.
SEXO
Deprecated option only for backward compatibility, use GENERO instead.
UNMIL
This field affects only the translation of cardinal numbers. When it is a true value, the number 1000
is translated to 'un mil' (one thousand), otherwise it is translated to the more colloquial 'mil'
(thousand). The default value is 1.
NEGATIVO
Contains the character string with the text to which the negative sign (-) will be translated with.
Defaults to 'menos'.
For example: default translation of -5 will yield "menos cinco".
POSITIVO
Contains the character string with the text to which the positive sign will be translated with.
Defaults to ''.
For example: default translation of 5 will yield "cinco".
FORMATO
A character string specifying how the decimals of a real number are to be translated. Its default
value is 'con %2d ctms.' (see the real method)
Aliases
All the options have the following english aliases.
English Option name
--------------------------
ACCENTS ACENTOS
UPPERCASE MAYUSCULAS
SEPARATORS SEPARADORES
GENDER GENERO
POSITIVE POSITIVO
NEGATIVE NEGATIVO
FORMAT FORMATO
cardinal
SYNOPSIS:
$text = $obj->cardinal($num)
Parameters
$num
the number.
Description
Translates a cardinal number ($num) to spanish text, translation is performed according to the following
object ($obj) settings: DECIMAL, SEPARADORES, SEXO, ACENTOS, MAYUSCULAS, POSITIVO and NEGATIVO.
This method ignores any fraction part of the number ($num).
Return Value
Textual representation of the number as a string
real
SYNOPSIS:
$text = real($n; $genf, $genm)
Translates the real number ($n) to spanish text.
The optional $genf and $genm parameters are used to specify gender of the fraction part and fraction part
magnitude in that order. If $genf is missing it will default to the GENDER option, and $genm will
default to the $genf's value.
This translation is affected by the options: DECIMAL, SEPARADORES, GENDER, ACENTOS, MAYUSCULAS, POSITIVO,
NEGATIVO and FORMATO.
Fraction format (FORMATO)
FORMAT option is a formatting string like printf, it is used to format the fractional part before
appending it to the integer part. It has the following format specifiers:
%Ns Formats the fractional part as text with precisiA~Xn of N digits, for example: number '124.345'
formated with string 'CON %s.' will yield the text 'ciento veinticuatro CON trescientas cuarenta y
cinco milesimas', and formatted with string 'CON %2s.' will yield 'ciento veinticuatro CON treinta y
cuatro centesimas'.
%Nd Formats the fractional part as a number (no translation), with precision of N digits, veri similar to
sprintf's %d format, for example: number '124.045' formated with 'CON %2d ctms.' will yield: 'ciento
veinticuatro CON 04 ctms.'
ordinal
SYNOPSIS:
$text = $obj->ordinal($num)
Parameters
$num
the number.
Description
Translates an ordinal number ($num) to spanish text, translation is performed according to the following
object ($obj) settings: DECIMAL, SEPARADORES, GENERO, ACENTOS, MAYUSCULAS, POSITIVO and NEGATIVO.
This method croacks if $num <= 0 and carps if $num has a fractional part.
Return Value
Textual representation of the number as a string
Accessors
Each of the options has a setter/getter with the name of the option in lowercase, all the accessors have
the following sintax:
Getters
$obj->name_of_option()
Returns the current value of the option.
Setters
$obj->name_of_option( $value )
Sets the option to $value and returns $obj
List of accessors
$obj->accents
$obj->acentos
$obj->uppercase
$obj->mayusculas
$obj->unmil
$obj->html
$obj->decimal
$obj->separators
$obj->separadores
$obj->gender
$obj->genero
$obj->positive
$obj->positivo
$obj->negative
$obj->negativo
$obj->format
$obj->formato
INTERNALS
Functions in this secction are generally not used, but are docummented here for completeness.
This is not part of the module's API and is subject to change.
CARDINAL SUPPORT
Construction of cardinal numbers
cardinal_e2
SYNOPSIS
cardinal_e2($n, $nn)
PARAMETERS
$n the number.
$nn word stack.
DESCRIPTION
This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text
translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.
cardinal_e3
SYNOPSIS
cardinal_e3($n, $nn)
PARAMETERS
$n the number.
$nn word stack.
DESCRIPTION
This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text
translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.
cardinal_e6
SYNOPSIS
cardinal_e6($n, $nn, $mag, $un_mil, $postfix)
PARAMETERS
$n the number.
$nn word stack.
$mag
magnitude of the number 1 for millions, 2 for billions, etc.
$un_mil
if true 1000 is translated as "un mil" otherwise "mil"
$postfix
array representing plural & singular magnitude of the number, in this order.
DESCRIPTION
This procedure takes $n, and pushes the numbers text translation into $nn, on a word by word basis,
with the proper translated magnitude. If $n == 0 nothing is pushed into $nn.
cardinal_generic
SYNOPSIS
cardinal_generic($n, $exp, $fmag, $gen)
PARAMETERS
$n the number.
$exp
exponent.
$fmag
closure to format the 6 digits groups.
$gen
gender of the magnitude (optional defaults to NEUTRAL):
FEMALE for female gender (1 -> una).
MALE for male gender (1 -> uno).
NEUTRAL for neutral gender (1 -> un).
DESCRIPTION
This function translate the natural number $n to spanish words, adding gender where needed.
RETURN VALUE
Translation of $n to spanish text as a list of words.
cardinal_simple
SYNOPSIS
cardinal_simple($n, $exp, $un_mil; $gen)
PARAMETERS
$n the number.
$exp
exponent.
$un_mil
if true 1000 is translated as "un mil" otherwise "mil"
$gen
gender of the magnitude (optional defaults to NEUTRAL):
FEMALE for female gender (1 -> una).
MALE for male gender (1 -> uno).
NEUTRAL for neutral gender (1 -> un).
DESCRIPTION
This function translate the natural number $n to spanish words, adding gender where needed.
This procedure just builds a closure with format information, to call cardinal_e6, and then calls
cardinal_generic to do the work.
RETURN VALUE
Translation of $n to spanish text as a list of words.
fraccion_mag_prefix
SYNOPSIS
fraccion_mag_prefix($mag, $gp)
PARAMETERS
$n the number.
$exp
exponent.
$mag
magnitude of the number 1 for millionths, 2 for billionths, etc.
$gp gender and plural of the number, is the concatenation of gender and plural gender must be one of
FEMALE, MALE or NEUTRAL, and plural must be '' for singular and 's' for plural.
Note that NEUTRAL + plural is a nonsense.
$ngen
gender of the number (same values as $gen).
DESCRIPTION
This function returns the name of the magnitude of a fraction, $mag is the number of decimal digits.
For example 0.001 has $mag == 3 and translates to "milesimos" if $gp is (MALE . 's').
RETURN VALUE
Translation of $n to spanish text as a string.
fraccion_simple
SYNOPSIS
fraccion_simple($n, $exp, $un_mil, $gen; $ngen)
PARAMETERS
$n the number.
$exp
exponent.
$un_mil
if true 1000 is translated as "un mil" otherwise "mil"
$gen
gender of the magnitude (optional defaults to NEUTRAL):
FEMALE for female gender (1 -> primera).
MALE for male gender (1 -> primero).
NEUTRAL for neutral gender (1 -> primer).
$ngen
gender of the number (same values as $gen).
DESCRIPTION
This function translate the fraction $n to spanish words, adding gender where needed.
This procedure just builds a closure with format information, to call cardinal_e6, and then calls
cardinal_generic to do the work.
RETURN VALUE
Translation of $n to spanish text as a list of words.
ORDINAL SUPPORT
Construction of ordinal numbers
ordinal_e2
SYNOPSIS
ordinal_e2($n, $nn)
PARAMETERS
$n the number.
$nn word stack.
DESCRIPTION
This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text
translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.
ordinal_e3
SYNOPSIS
ordinal_e3($n, $nn)
Parameters
$n the number.
$nn word stack.
DESCRIPTION
This procedure takes $n (an integer in the range [0 .. 999], not verified) and adds the numbers text
translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.
ordinal_e6
SYNOPSIS
ordinal_e6($n, $nn, $mag, $un_mil, $postfix)
PARAMETERS
$n the number.
$nn word stack.
$mag
magnitude of the number 1 for millions, 2 for billions, etc.
DESCRIPTION
This procedure takes $n, and pushes the numbers text translation into $nn, on a word by word basis,
with the proper translated magnitude. If $n == 0 nothing is pushed into $nn.
ordinal_simple
SYNOPSIS
ordinal_simple($n, $exp; $gen)
PARAMETERS
$n the number.
$exp
exponent.
$un_mil
if true 1000 is translated as "un mil" otherwise "mil"
$gen
gender of the magnitude (optional defaults to NEUTRAL):
FEMALE for female gender (1 -> primera).
MALE for male gender (1 -> primero).
NEUTRAL for neutral gender (1 -> primer).
DESCRIPTION
This function translate the fraction $n to spanish words, adding gender where needed.
This procedure just builds a closure with format information, to call ordinal_e6, and then calls
ordinal_generic to do the work.
RETURN VALUE
Translation of $n to spanish text as a list of words.
MISCELANEOUS
Everithing not fitting elsewere
parse_num
SYNOPSIS
parse_num($num, $dec, $sep)
Decomposes the number in its constitutive parts, and returns them in a list:
use Lingua::ES::Numeros;
($sgn, $ent, $frc, $exp) = parse_num('123.45e10', '.', '",');
PARAMETERS
$num
the number to decompose
$dec
decimal separator (tipically ',' or '.').
$sep
separator characters ignored by the parser, usually to mark thousands, millions, etc..
RETURN VALUE
This function parses a general number and returns a list of 4 elements:
$sgn
sign of the number: -1 if negative, 1 otherwise
$int
integer part of the number
$frc
decimal (fraction) part of the number
$exp
exponent of the number
Croaks if there is a syntax error.
retval
SYNOPSIS
$obj->retval($value)
DESCRIPTION
Utility method to adjust return values, transforms text following the options: ACENTOS, MAYUSCULAS y
HTML.
Returns the adjusted $value.
DEPENDENCIES
Perl 5.006, Exporter, Carp
SEE ALSO
http://roble.pntic.mec.es/~msanto1/ortografia/numeros.htm
AUTHOR
Jose Rey, <jrey@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2001-2009 by Jose Rey
This library is free software; you can redistribute it and/or modify it under the same terms as Perl
itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.