Provided by: liblingua-es-numeros-perl_0.09-3_all bug

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