--- name: "Lingua::ES::Numeros" section: "3pm" platform: "linux" package: "liblingua-es-numeros-perl" version: "0.09-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Lingua::ES::Numeros" --- # Lingua::ES::Numeros(3pm) Translates numbers to spanish text ## 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 precisión of N digits, for example: number '124.345' formatted with string 'CON `%s`.' will yield the text 'ciento veinticuatro CON trescientas cuarenta y cinco milésimas', and formatted with string 'CON `%2s`.' will yield 'ciento veinticuatro CON treinta y cuatro centésimas'. - %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' formatted 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 (typically ',' 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, \ ## 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.