NAME

Lingua::Word2Num - Multi-language word to number conversion with numeral arithmetic

VERSION

version 0.2603270

DESCRIPTION

Lingua::Word2Num converts number words in natural language text into their numeric values. It supports 44 languages via auto-discovered Lingua::XXX::Word2Num modules and accepts both ISO 639-1 (de) and ISO 639-3 (deu) language codes.

The module also provides overloaded numeral objects that support arithmetic across languages with on-demand rendering into any supported language.

SYNOPSIS

Procedural Interface

use Lingua::Word2Num qw(cardinal);

# convert with explicit language code
my $num = cardinal('de', 'zweiundvierzig');    # 42
my $num = cardinal('cs', 'sto dvacet');        # 120

# auto-detect language
my $num = cardinal('*', 'quarante-deux');       # 42

Language Detection

use Lingua::Word2Num qw(cardinal_detect);

my ($value, $lang) = cardinal_detect('zwanzig');
# $value = 20, $lang = 'deu'

Object Interface with Numeral Arithmetic

use Lingua::Word2Num;

my $a = Lingua::Word2Num->new("zwanzig");      # German 20
my $b = Lingua::Word2Num->new("šestnáct");     # Czech 16

say $a + $b;                # 36
say ($a + $b)->as('de');    # sechsunddreissig
say ($a + $b)->as('cs');    # třicet šest
say ($a + $b)->as('fr');    # trente-six

$a++;
say $a->as('de');           # einundzwanzig
say $a->value;              # 21
say $a->lang;               # deu

# construct from number
my $c = Lingua::Word2Num->new(100);
say ($c - $b)->as('ja');    # hachi ju yon

METHODS

new (positional)

1   str|num  text in any language, or a number
=>  obj      Lingua::Word2Num object

Constructor. If given text, auto-detects the language and converts to a number. If given a number, stores it directly. The detected language is available via ->lang.

cardinal (positional)

1   str    language code (ISO 639-1 or 639-3, or '*' for auto-detect)
2   str    text to convert
=>  num    converted number
=>  ''     if the input string is not recognized

Procedural conversion from text in the specified language to a number.

cardinal_detect (positional)

1   str    text to convert (any language)
=>  (num, str)  in list context: (value, iso639-3 code)
=>  num         in scalar context: just the value
=>  undef       if no language matched

Auto-detects the language and converts to number.

as (positional)

1   str    language code (ISO 639-1 or 639-3)
=>  str    number rendered as words in the requested language

Converts the object's numeric value to word form. If no language is given, uses the originally detected language.

value (void)

=>  num    the numeric value stored in the object

lang (void)

=>  str    the ISO 639-3 code of the detected source language
=>  undef  if constructed from a number

known_langs (void)

=>  lref   sorted list of all supported ISO 639-3 codes

OVERLOADED OPERATORS

Lingua::Word2Num objects support the following operators. All arithmetic operations return new Lingua::Word2Num objects.

+   addition          $a + $b, $a + 5
-   subtraction       $a - $b
*   multiplication    $a * $b
/   integer division  $a / $b
%   modulo            $a % $b
++  increment         $a++
--  decrement         $a--
0+  numification      0 + $a, int($a)
""  stringification   "$a" (returns the number)
<=> numeric compare   $a <=> $b, sort

EXPORT_OK

cardinal

cardinal_detect

known_langs

SEE ALSO

Lingua::Num2Word — the reverse direction (number to words).

Task::Lingua::PetaMem — install all supported languages.

AUTHORS

specification, maintenance:
  Richard C. Jelinek E<lt>rj@petamem.comE<gt>
coding (until 2005):
  Roman Vasicek E<lt>info@petamem.comE<gt>
maintenance, coding (2025-present):
  PetaMem AI Coding Agents

COPYRIGHT

Copyright (c) PetaMem, s.r.o. 2004-present

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as the Artistic License 2.0 or the BSD 2-Clause License. See the LICENSE file in the distribution for details.