NAME

Lingua::Num2Word - Multi-language number to word conversion wrapper

VERSION

version 0.2603300

Lingua::Num2Word is a wrapper for modules for converting numbers into their equivalent in written representation.

This is a wrapper for various Lingua::XXX::Num2Word modules that do the conversions for specific languages. Output encoding is utf-8.

For further information about various limitations of the specific modules see their documentation.

SYNOPSIS

use Lingua::Num2Word;

my $numbers = Lingua::Num2Word->new;

# try to use czech module (Lingua::CES::Num2Word) for conversion to text
my $text = $numbers->cardinal( 'ces', 123 );

# or procedural usage if you dislike OO
my $text = Lingua::Num2Word::cardinal( 'ces', 123 );

print $text || "sorry, can't convert this number into czech language.";

# check if number is in supported interval before conversion
my $number = 999_999_999_999;
my $limit  = $numbers->get_interval('ces');
if ($limit) {
  if ($number > $$limit[1] || $number < $$limit[0]) {
    print "Number is outside of supported range
             - <$$limit[0], $$limit[1]>.";
  }
  else {
    print Lingua::Num2Word::cardinal( 'ces', $number );
  }
}
else {
  print "Unsupported language.";
}

Functions Reference

cardinal (positional)

1   str    target language
2   num    number to convert
=>  str    converted string
=>  undef  if input number is not supported

Conversion from number to text representation in specified language.

get_interval (positional)

1   str    language specification
=>  any    an array/arref - list with min max values
=>  undef  if specified language is not known

Returns the minimal and maximal number (inclusive) supported by the conversion in a specified language. The returned value is a list of two elements (low,high) or reference to this list depending on calling context. In case a unsupported language is passed undef is returned.

known_langs (void)

=>  any  an array/arref - list of supported languages

List of all currently supported languages. Return value is a list or a reference to a list depending on calling context.

langs (void)

=>  any  an array/arref - list of languages known by ISO 639-3 list

List of all known language codes from iso639. Return value is list or reference to list depending on calling context.

new (void)

=>  obj  returns new object

Constructor.

ordinal (positional)

1   str    target language (ISO 639-3 or 639-1)
2   num    number to convert
=>  str    ordinal text representation
=>  ''     if language has no ordinal support or input is out of range

Conversion from number to ordinal text representation in specified language. Requires the language module to export a num2XXX_ordinal function and to declare ordinal => 1 in its capabilities().

capabilities (positional)

1   str    language (ISO 639-3 or 639-1)
=>  href   hashref of capabilities
=>  undef  if language is not known

Query what a language module can do. The returned hashref contains keys cardinal, ordinal, negative, decimal, currency, and range (an arrayref [$lo, $hi]).

has_capability (positional)

1   str    language (ISO 639-3 or 639-1)
2   str    feature name (e.g. 'ordinal', 'cardinal')
=>  bool   1 if the language supports the feature, 0 otherwise

preprocess_code (void)

=>  undef  if lang is not specified
=>  str    a template

Private function.

EXPORT_OK

cardinal

ordinal

capabilities

has_capability

get_interval

known_langs

langs

Supported languages

Languages are auto-discovered at load time from installed Lingua::*::Num2Word modules. Use known_langs() to obtain the current list programmatically.

Each language is identified by its ISO 639-3 code (e.g. deu, eng, fra). ISO 639-1 two-letter codes (de, en, fr) are accepted as aliases and mapped automatically.

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