/ 
Lingua-RU-Numeral-0.031
River stage zero No dependents
/ Lingua::RU::Numeral

NAME

Lingua::RU::Numeral - Perl extension for generate Russian wording of numerals from the natural numbers and 0 (zero).

SYNOPSIS

Activate the module:

use Lingua::RU::Numeral qw( num2cardinal );

Usage examples:

  1. Using with default options, i.e. 'nominative' case (Именительный падеж), 'masculine' gender (Мужской род), numeral in 'singular' (единственное число), 'inanimate' object (неодушевлённый предмет):

    say num2cardinal('930651342187216');

    Will print the result:

    девятьсот тридцать триллионов шестьсот пятьдесят один миллиард триста сорок два миллиона сто восемьдесят семь тысяч двести шестнадцать

  2. Using 'feminine' gender (Женский род), and with other default options:

    say num2cardinal('101101102101101', 'gender'=>'feminine');

    Will print the result:

    сто один триллион сто один миллиард сто два миллиона сто одна тысяча сто одна

  3. Using 'neuter' gender (Средний род), and with other default options:

    say num2cardinal('101101102101101', 'gender'=>'neuter');

    Will print the result:

    сто один триллион сто один миллиард сто два миллиона сто одна тысяча сто одно

  4. Using 'genitive' case (Родительный падеж), and with other default options:

    say num2cardinal( 1000003, 'case'=>'genitive');

    or abbreviated form

    say num2cardinal( 1000003, 'case'=>'g');

    Will print the result:

    одного миллиона трёх

  5. Using 'accusative' case (Винительный падеж), 'feminine' gender (Женский род, abbreviated form), 'animate' object (одушевлённый предмет), and with other default option, i.e. 'singular' (единственное число):

    say num2cardinal( 2, 'case'=>'accusative', 'gender'=>'f', 'object'=>'animate');

    Will print the result:

    двух

  6. Using 'accusative' case (Винительный падеж, abbreviated form), 'plural' (множественное число), 'inanimate' object (неодушевлённый предмет, by default), and with other default options:

    say num2cardinal( 1000, 'case'=>'a', 'multi'=>'plural');

    Will print the result:

    одни тысячи

  7. Using 'accusative' case (Винительный падеж, abbreviated form), 'plural' (множественное число, abbreviated form), 'animate' object (одушевлённый предмет), and with other default options:

    say num2cardinal( 1000, 'case'=>'a', 'multi'=>'p', 'object'=>'animate');

    Will print the result:

    одних тысяч

  8. Using reference 'epilog' with other default options:

    say num2cardinal( 1000, 'epilog'=>'RUB');	# add Российский 'рубль', using an alphabetic currency code
say num2cardinal( 1000, 'epilog'=> 643 );	# the same, using a digital currency code
say num2cardinal( 2000, 'epilog'=>'rub');	# add Российская 'копейка'
say num2cardinal( 2000, 'epilog'=> -643);	# the same

    Will print the results:

    одна тысяча рублей
одна тысяча рублей
две тысячи копеек
две тысячи копеек

  9. Using 'prolog' and 'epilog' with other explicit and implicit options:

    say num2cardinal( 11,
                 'case'   => 'p',	# Предложный: о ком? о чём?
                 'prolog' => 'о',
                 'epilog' => 'stamp',
                );

    OR the same with details:

    my $epilog = {
             'object' => 'inanimate',
             'gender' => 'feminine',
             'root'   => 'печат',
             'ends'   => ['ях','и', ('ях') x 8 ],
            };

say num2cardinal( 11,
                 'case'   => 'prepositional',	# Предложный: о ком? о чём?
                 'prolog' => ['о','об=од'],
                 'epilog' => $epilog,
                );

    Will print the result:

    об одиннадцати печатях

  10. Using 'alt' (alternate form) with other default options:

    say num2cardinal( 0 );
say num2cardinal( 0, alt => { 0=>'TRUE'} );

    Will print the results:

    ноль
нуль

  11. Using 'ucfirst' with other explicit and implicit options:

    say num2cardinal( 11, 'ucfirst' => 'TRUE');
say num2cardinal( 11, case => 'p', prolog => 'о' );
say num2cardinal( 11, case => 'p', prolog => 'о', 'ucfirst' => 1 );
say num2cardinal( 11, case => 'p', prolog => 'о', epilog => 'RUB', 'ucfirst' => 1 );

    Will print the results:

    Одиннадцать
об одиннадцати
об Одиннадцати
об Одиннадцати рублях

LIMITATIONS

num2cardinal() subroutine generates Russian cardinal numbers for the natural numbers and 0 (zero), i.e. from 0 to 999_999_999_999_999, e.g.:

say num2cardinal( 0 );
say num2cardinal( 0, 'case' => 'instrumental');
say num2cardinal('999999999999999');
say num2cardinal('1000000000000000');

Will print the results:

ноль
нолём
девятьсот девяносто девять триллионов девятьсот девяносто девять миллиардов девятьсот девяносто девять миллионов девятьсот девяносто девять тысяч девятьсот девяносто девять
1000000000000000 > 999_999_999_999_999 !

The target Cyrillic character set (returns) is UTF-8 (use utf8).

This module have reason only for perl 5.10 and higher.

ABSTRACT

This module provides function that can be used to generate Russian verbiage for the natural numbers (unsigned integer) and 0 (zero). The methods implemented in this module, are all focused on knowledge of Russian grammar.

DESCRIPTION

This module provides function that can be used to generate Russian verbiage for the natural numbers (unsigned integer) and 0 (zero). The methods implemented in this module, are all focused on knowledge of Russian grammar.

This module makes verbiage in "short scales" (1,000,000,000 is "один миллиард" rather than "одна тысяча миллионов"). For details see this Wikipedia russian article:

https://ru.wikipedia.org/wiki/Системы_наименования_чисел

SUBROUTINES

Lingua::RU::Numeral provides this subroutine:

num2cardinal( $number [, %facultative_options ] );

num2cardinal( $number [, %facultative_options ] )

Convert a $number (natural numbers or 0) to Russian text (string), using explicitly specified %facultative_options, otherwise - default options. The following can be %facultative_options:

  • 'case' option — case of a numeral can take the following meanings (case names can be abbreviated to one first letter):

    1. 'n'|'nominative' (Именительный падеж: есть кто? что? is default),
    2. 'g'|'genitive' (Родительный падеж: нет кого? чего?),
    3. 'd'|'dative' (Дательный падеж: рад кому? чему?),
    4. 'a'|'accusative' (Винительный падеж: вижу кого? что?),
    5. 'i'|'instrumental' (Творительный падеж: оплачу кем? чем?),
    6. 'p'|'prepositional' (Предложный падеж: думаю о ком? о чём?).

  • 'gender' option — 'm'|'masculine' (Мужской род, by default) or 'f'|'feminine' (Женский род) or 'n'|'neuter' (Средний род). Gender names can be abbreviated to one first letter also.

  • 'multi' option — word(s) in the plural ('1'|'plural', множественное число) or 'undef'|'0'|'singular' (единственное число, by default).

  • 'object' option — 'inanimate' (неодушевлённый предмет, by default) or 'animate' (одушевлённый предмет) object. Object names can be abbreviated to one first letter also.

  • 'prolog' option — PREPosition(s) of the numeral is the REF to ARRAY, where 0th element ('PREP_0') — the preposition for all numerals, except for those indicated by subsequent array elements ('PREP_x') as ['PREP_0','PREP_1=REGEX',...].

    Here REGEX — the regular expression that is used to find a match at the beginning of a numeric string like: numeral =~/^REGEX/. For example:

    'prolog' => ['о','об=од']

    If 'prolog' is SCALAR value (e.g. 'prolog'=>'о') then it is used from internal reference list of prologs. Now internal reference list of prologs contains the following preconfigured phrase structures:

    • 'o' — equivalent to ['о','об=од']

    • 'c' — equivalent to ['с','со=с']

    • 'в' — equivalent to ['в']

  • 'epilog' option — final word (phrase) of the numeral is SCALAR value (name) from internal reference list of epilogs or the REF to HASH to create a custom phrase.

    Internal reference list of epilogs contains the following preconfigured phrase structures:

    • 'RUB'|643 — for Russian ruble (Российский рубль); 'rub'|-643 — for Russian kopek (Российская копейка).

    • 'CNY'|156 — Chinese yuan.

    • 'USD'|840 — for United States dollar; 'usd'|-840 — for US cent.

    • Time measures: 'year' — for год, лет; 'month' — месяц; 'day' — день; 'hour' — час; 'min.' — minute (минута); 'sec.' — second (секунда).

    • 'meter' — метр.

    • 'stamp' — печать.

    The custom 'epilog' presents the REF to HASH with complex structure of SCALAR values and ARRAY. For example, год, лет (abbreviation equivalent is $epilog = 'year' for 'nominative' case (Именительного падежа):

    my $epilog = {
             'object' => 'inanimate', # неодушевлённый предмет
             'gender' => 'masculine', # Мужской род
             'root'   => '',
             'ends'   => ['лет','год', ('года') x 3, ('лет') x 3 ],
            };

    or for секунда (abbreviation equivalent is $epilog = 'sec.' for 'accusative' case (Винительного падежа)):

    my $epilog = {
             'object' => 'inanimate',
             'gender' => 'feminine', # Женский род
             'root'   => 'секунд',
             'ends'   => ['','у', ('ы') x 3, ('') x 3 ],
            };

    or for рубль (abbreviation equivalent is $epilog = 'RUB' for 'genitive' case (Родительного падежа)):

    my $epilog = {
             'object' => 'inanimate',
             'gender' => 'masculine', # Мужской род
             'root'   => 'рубл',
             'ends'   => ['ям','ю', ('ям') x 4, ('ей') x 2 ],
            };

    Here are:

    • already known 'object' and 'gender' options. These options are recommended but not required. WARNING! These options take precedence over the global options('object', 'gender'), i.e. override them.

    • 'root' option means the 'epilog' root, i.e. common invariable part of the custom 'epilog' words (or its absence in the form of "").

    • 'ends' option means the 'epilog' word endings for numerals: 0, 1, 2, 3, 4, 5, 1000 (thousand), 1_000_000 (million) respectively.

  • 'alt' option — REF to HASH of alternative word forms. Currently available for zero only (ноль, by default; 'alt' => {0=>1}, to obtain нуль).

  • 'ucfirst' option — Returns the numeral with the first character capitalized (upper case). WARNING! does not affect the 'prolog'.

EXPORT

Lingua::RU::Numeral exports nothing by default. Each of the subroutines can be exported on demand, as in

use Lingua::RU::Numeral qw( num2cardinal );

and the tag all exports them all:

use Lingua::RU::Numeral qw( :all );

DEPENDENCIES

Lingua::RU::Numeral is known to run under perl 5.10.0 on Linux.

SEE ALSO

Igor' A. Mel'čuk. THE SURFACE SYNTAX OF RUSSIAN NUMERAL EXPRESSIONS. -Wien: Volume 16 of Wiener slawistischer Almanach, Institut für Slavistik der Universität, -1985. — 514 p. ISSN 0258-6819.

Мельчук, И.А. Поверхностный синтаксис русских числовых выражений. -Wien: Volume 16 of Wiener slawistischer Almanach, Institut für Slavistik der Universität, -1985. — 514 c. ISSN 0258-6819.

Lingua::RU::Number is a Perl module that offers some similar functionality.

AUTHOR

Alessandro N. Gorohovski, <an.gorohovski@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2022-2023 by Alessandro N. Gorohovski

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.