num2words 0.3.0 → 0.3.1

data/docs/api.ru.md

@@ -0,0 +1,422 @@
+# Справочник API
+
+Этот документ описывает публичный API `num2words`.
+
+## Подключение
+
+```ruby
+require "num2words"
+```
+
+Это подключает модульный API и core extensions для поддерживаемых Ruby-классов.
+
+## Модульный API
+
+### `Num2words.to_words`
+
+```ruby
+Num2words.to_words(value, locale = I18n.default_locale, only = nil, short = false, **options)
+```
+
+Преобразует числа, даты, время и дату-время в слова.
+
+Примеры:
+
+```ruby
+Num2words.to_words(123, :ru)
+# => "сто двадцать три"
+
+Num2words.to_words("3,5", :ru)
+# => "три целых пять десятых"
+
+Num2words.to_words("2024-08-21", :en)
+# => "the twenty-first of August, two thousand twenty four"
+
+Num2words.to_words("14:35:42", :fr)
+# => "quatorze heures trente cinq minutes quarante deux secondes"
+```
+
+Также поддерживается передача локали через keyword-аргумент:
+
+```ruby
+Num2words.to_words(123, locale: :en)
+# => "one hundred twenty three"
+```
+
+### `Num2words.to_currency`
+
+```ruby
+Num2words.to_currency(amount, locale = I18n.default_locale, **options)
+```
+
+Преобразует денежную сумму в слова с учетом выбранной локали и валюты.
+
+Примеры:
+
+```ruby
+Num2words.to_currency("21,05", :ru)
+# => "двадцать один рубль пять копеек"
+
+Num2words.to_currency(12.50, :en, code: :EUR)
+# => "twelve euros fifty cents"
+
+Num2words.to_currency(BigDecimal("21.05"), :ru)
+# => "двадцать один рубль пять копеек"
+```
+
+## Core Extensions
+
+`num2words` добавляет удобные методы в стандартные классы Ruby.
+
+### `Integer#to_words`
+
+```ruby
+123.to_words(:ru)
+# => "сто двадцать три"
+```
+
+### `Integer#to_currency`
+
+```ruby
+123.to_currency(:en, code: :USD)
+# => "one hundred twenty three dollars zero cents"
+```
+
+### `Float#to_words`
+
+```ruby
+45.67.to_words(:ru)
+# => "сорок пять целых шестьдесят семь сотых"
+```
+
+### `Float#to_currency`
+
+```ruby
+12.5.to_currency(:ru, code: :USD)
+# => "двенадцать долларов пятьдесят центов"
+```
+
+### `String#to_words`
+
+```ruby
+"007".to_words(:en)
+# => "seven"
+
+"3,5".to_words(:ru)
+# => "три целых пять десятых"
+
+"2024-08-21 14:35:42".to_words(:ru)
+# => "двадцать первое августа две тысячи двадцать четвёртого года, четырнадцать часов тридцать пять минут сорок две секунды"
+```
+
+`String#to_currency` сейчас не определен. Для строковых сумм используй `Num2words.to_currency("12.50", :en)`.
+
+### `Date#to_words`
+
+```ruby
+Date.new(2024, 8, 21).to_words(:ru)
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+```
+
+### `Time#to_words`
+
+```ruby
+Time.new(2024, 8, 21, 14, 35, 42).to_words(:en)
+# => "fourteen hours thirty five minutes forty two seconds"
+```
+
+### `DateTime#to_words`
+
+```ruby
+DateTime.parse("2024-08-21 14:35:42").to_words(:en)
+# => "the twenty-first of August, two thousand twenty four at fourteen hours thirty five minutes forty two seconds"
+```
+
+## Поддерживаемые типы входных данных
+
+`to_words` поддерживает:
+
+- `Integer`
+- `Float`
+- `Date`
+- `Time`
+- `DateTime`
+- строки с целыми числами, например `"007"` или `"-42"`
+- строки с дробными числами через точку или запятую, например `"3.5"` или `"3,5"`
+- строки с датами, например `"2024-08-21"` или `"21.08.2024"`
+- строки со временем, например `"14:35"` или `"14:35:42"`
+- строки с датой и временем, например `"2024-08-21 14:35:42"`
+
+`to_currency` поддерживает:
+
+- `Integer`
+- `Float`
+- `String`
+- `BigDecimal`
+
+Строковые денежные суммы могут использовать точку или запятую как десятичный разделитель.
+
+## Опции
+
+### `locale`
+
+Выбирает локаль.
+
+```ruby
+Num2words.to_words(123, :ru)
+Num2words.to_words(123, locale: :ru)
+```
+
+Если локаль не передана, используется `I18n.default_locale`.
+
+### `style`
+
+Управляет выводом дробной части в `to_words`.
+
+Поддерживаемые значения:
+
+- `:fraction` - стиль дробей по умолчанию.
+- `:decimal` - чтение дробной части по цифрам, если локаль поддерживает такой стиль.
+
+```ruby
+Num2words.to_words(12.12, :en)
+# => "twelve and twelve hundredths"
+
+Num2words.to_words(12.12, :en, style: :decimal)
+# => "twelve point one two"
+```
+
+### `joiner`
+
+Управляет соединителем для дробей в стиле `:fraction`.
+
+Поддерживаемые значения:
+
+- `:default`
+- `:and`
+
+```ruby
+Num2words.to_words(0.5, :ru)
+# => "ноль целых пять десятых"
+
+Num2words.to_words(0.5, :ru, joiner: :and)
+# => "ноль и пять десятых"
+```
+
+Некорректные значения вызывают `ArgumentError`.
+
+### `date_case`
+
+Управляет падежом дня в датах для локалей, которые это поддерживают.
+
+Поддерживаемые значения:
+
+- `:default`
+- `:genitive`
+
+```ruby
+Num2words.to_words("2024-08-21", :ru)
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+
+Num2words.to_words("2024-08-21", :ru, date_case: :genitive)
+# => "двадцать первого августа две тысячи двадцать четвёртого года"
+```
+
+Некорректные значения вызывают `ArgumentError`.
+
+### `short`
+
+Включает короткий вывод для времени или даты-времени.
+
+```ruby
+Num2words.to_words("14:35:42", :ru, short: true)
+# => "четырнадцать часов тридцать пять минут"
+```
+
+Для даты-времени `short: true` возвращает сокращенную строку даты-времени, если не используется `only`.
+
+### `only`
+
+Выбирает часть значения дата-время.
+
+```ruby
+Num2words.to_words("2024-08-21 14:35:42", :ru, only: :date)
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+
+Num2words.to_words("2024-08-21 14:35:42", :ru, only: :time)
+# => "четырнадцать часов тридцать пять минут сорок две секунды"
+```
+
+Также поддерживается старый позиционный вариант:
+
+```ruby
+"2024-08-21 14:35:42".to_words(:ru, :date)
+"2024-08-21 14:35:42".to_words(:ru, :time)
+```
+
+### `format`
+
+Используется при преобразовании дат и времени.
+
+Для дат:
+
+- `:default`
+- `:nominative`, если формат есть в данных локали.
+- `:short` возвращает числовой формат даты `DD.MM.YYYY`.
+
+Для времени:
+
+- `:default`
+- `:hours_only`
+- `:hours_minutes`
+- `:hours_minutes_seconds`
+
+```ruby
+Num2words.to_words("14:35:42", :ru, format: :hours_minutes)
+# => "четырнадцать часов тридцать пять минут"
+```
+
+Неподдерживаемые форматы времени вызывают `ArgumentError`.
+
+### `word_case`
+
+Меняет регистр результата.
+
+Поддерживаемые значения:
+
+- `:default`
+- `:upper`
+- `:downcase`
+- `:capitalize`
+- `:title`
+
+```ruby
+Num2words.to_words(21, :en, word_case: :upper)
+# => "TWENTY ONE"
+
+Num2words.to_words(21, :en, word_case: :title)
+# => "Twenty One"
+```
+
+### `feminine`
+
+Для локалей с грамматическим родом включает женские формы там, где они поддерживаются.
+
+```ruby
+Num2words.to_words(1, :ru, feminine: true)
+# => "одна"
+```
+
+### `code`
+
+Выбирает код валюты в `to_currency`.
+
+```ruby
+Num2words.to_currency(12.50, :ru, code: :USD)
+# => "двенадцать долларов пятьдесят центов"
+```
+
+Если валюта недоступна для локали, `num2words` использует валюту локали по умолчанию и может вывести warning в зависимости от настроек.
+
+### `minor`
+
+Управляет выводом младшей денежной единицы.
+
+Поддерживаемые значения:
+
+- `:always` - всегда выводить младшую единицу.
+- `:nonzero` - выводить младшую единицу только когда она больше нуля.
+- `:never` - не выводить младшую единицу.
+
+```ruby
+Num2words.to_currency(12, :ru)
+# => "двенадцать рублей ноль копеек"
+
+Num2words.to_currency(12, :ru, minor: :nonzero)
+# => "двенадцать рублей"
+
+Num2words.to_currency(12.50, :ru, minor: :never)
+# => "двенадцать рублей"
+```
+
+Некорректные значения вызывают `ArgumentError`.
+
+## Конфигурация
+
+### `Num2words.default_currency`
+
+Получает или задает валюту по умолчанию.
+
+```ruby
+Num2words.default_currency(:ru)
+# => :RUB
+
+Num2words.default_currency(:ru, :USD)
+# => :USD
+```
+
+### `Num2words.available_currencies`
+
+Возвращает коды валют, доступные для локали.
+
+```ruby
+Num2words.available_currencies(:ru)
+# => [:RUB, :USD, :EUR, ...]
+```
+
+### `Num2words.currency_warnings`
+
+Управляет warning при запросе валюты, недоступной для локали.
+
+```ruby
+Num2words.currency_warnings = false
+```
+
+## Локали и валюты
+
+Поддерживаемые локали:
+
+```text
+ar be bg bn cs da de el en es et fa fi fr gu he hi hr hu id it ja kn ko
+kz lt lv ml mr ms nb nl pa pl pt ro ru sk sl sr sv sw ta te th tr uk ur
+vi zh
+```
+
+Каждая завершенная локаль поддерживает один и тот же набор из 32 валют:
+
+```text
+BDT BGN BRL BYN CNY CZK DKK EUR GBP HUF IDR ILS INR IRR JPY KES KRW
+KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
+```
+
+## Ошибки
+
+Неподдерживаемый тип входных данных:
+
+```ruby
+Num2words.to_words(Object.new, :en)
+# raises ArgumentError: Unsupported input type: ...
+```
+
+Неподдерживаемые опции:
+
+```ruby
+Num2words.to_words(0.5, :ru, joiner: :plus)
+# raises ArgumentError: Unsupported joiner option: :plus
+
+Num2words.to_currency(12, :ru, minor: :sometimes)
+# raises ArgumentError: Unsupported minor option: :sometimes
+```
+
+Некорректная денежная сумма:
+
+```ruby
+Num2words.to_currency("abc", :en)
+# raises ArgumentError: Unsupported currency amount: "abc"
+```
+
+## Документация для разработки
+
+- [Числовые ограничения](limits.ru.md)
+- [Locale development guide](locale_development.md)
+- [Русская инструкция по разработке локалей](locale_development.ru.md)

data/docs/limits.md

@@ -0,0 +1,140 @@
+# Numeric Limits
+
+This document describes the currently documented numeric scale limits for `Num2words.to_words`.
+
+These limits are documentation-only. Runtime validation is not enforced yet, so values above the documented range may produce incomplete, unnatural or locale-dependent output. A future release may add strict validation for numbers that exceed locale limits.
+
+## Summary
+
+| Locale group | Locales | Guaranteed integer range |
+| --- | --- | --- |
+| Western 3-digit scales | Most locales | `-(10^15 - 1)` to `10^15 - 1` |
+| Indian scales | `bn gu hi kn ml mr pa ta te ur` | `-(10^12 - 1)` to `10^12 - 1` |
+| East Asian 4-digit scales | `ja ko zh` | `-(10^20 - 1)` to `10^20 - 1` |
+
+The guaranteed range means that the locale has named scale data for every group required inside that interval.
+
+## Western 3-Digit Scale Locales
+
+Most locales use 3-digit grouping:
+
+```text
+thousand, million, billion, trillion
+```
+
+The highest named group is the `10^12` group, so the documented maximum is:
+
+```ruby
+999_999_999_999_999
+```
+
+That is `999 trillion` plus lower groups.
+
+Examples:
+
+```ruby
+Num2words.to_words(999_999_999_999_999, :en)
+Num2words.to_words(999_999_999_999_999, :ru)
+Num2words.to_words(-999_999_999_999_999, :fr)
+```
+
+Values at `10^15` and above require a named `10^15` group, which is not currently part of the common scale catalog.
+
+## Indian Scale Locales
+
+These locales use Indian-style grouping in their Ruby locale modules:
+
+```text
+bn gu hi kn ml mr pa ta te ur
+```
+
+The implemented named groups are:
+
+```text
+thousand, lakh, crore, arab
+```
+
+The highest primary named group is `arab`, equal to `10^9`, so the documented maximum is:
+
+```ruby
+999_999_999_999
+```
+
+That is `999 arab` plus lower groups.
+
+Examples:
+
+```ruby
+Num2words.to_words(999_999_999_999, :hi)
+Num2words.to_words(999_999_999_999, :ur)
+Num2words.to_words(-999_999_999_999, :bn)
+```
+
+Values at `10^12` and above may still produce output through recursive composition, but that output is not currently guaranteed as idiomatic or stable.
+
+## East Asian 4-Digit Scale Locales
+
+These locales use 4-digit grouping:
+
+```text
+ja ko zh
+```
+
+The Ruby locale modules define five 4-digit groups:
+
+| Locale | Groups |
+| --- | --- |
+| `ja` | `万`, `億`, `兆`, `京` |
+| `ko` | `만`, `억`, `조`, `경` |
+| `zh` | `万`, `亿`, `兆`, `京` |
+
+The highest named group is the `10^16` group, so the documented maximum is:
+
+```ruby
+99_999_999_999_999_999_999
+```
+
+That is `10^20 - 1`.
+
+Examples:
+
+```ruby
+Num2words.to_words(99_999_999_999_999_999_999, :ja)
+Num2words.to_words(99_999_999_999_999_999_999, :ko)
+Num2words.to_words(99_999_999_999_999_999_999, :zh)
+```
+
+Values at `10^20` and above require another 4-digit scale name and are not currently guaranteed.
+
+## Fractions and Currency
+
+The integer part of a decimal or currency amount follows the same locale limit.
+
+Examples:
+
+```ruby
+Num2words.to_words("999999999999999.99", :en)
+Num2words.to_currency("999999999999.99", :hi, code: :INR)
+```
+
+Fraction denominators are currently defined up to `1_000_000_000`. Very long decimal strings may fall back to a locale default fraction word once the denominator is outside the defined fraction catalog.
+
+## Current Behavior Above Limits
+
+Above the documented range, behavior is currently unspecified:
+
+- some locales may raise an exception;
+- some locales may omit a scale name;
+- some locales may compose a technically readable but unnatural phrase;
+- output may change in a future release.
+
+Applications that process user-supplied large numbers should validate input before calling `num2words`.
+
+## Future Direction
+
+A future release may add:
+
+- `Num2words.locale_limits(locale)`;
+- strict validation for values above the locale limit;
+- `strict: true` and `strict: false` behavior;
+- specs that pin the maximum supported value for every locale.

data/docs/limits.ru.md

@@ -0,0 +1,140 @@
+# Числовые ограничения
+
+Этот документ описывает текущие документированные пределы числовых разрядов для `Num2words.to_words`.
+
+Эти ограничения пока только документируют гарантированный диапазон. Runtime validation еще не добавлен, поэтому значения выше указанного диапазона могут давать неполный, неестественный или зависящий от локали результат. В будущей версии может появиться строгая проверка чисел, превышающих лимит локали.
+
+## Кратко
+
+| Группа локалей | Локали | Гарантированный диапазон целых чисел |
+| --- | --- | --- |
+| Западные 3-значные разряды | Большинство локалей | `-(10^15 - 1)` .. `10^15 - 1` |
+| Индийские разряды | `bn gu hi kn ml mr pa ta te ur` | `-(10^12 - 1)` .. `10^12 - 1` |
+| Восточноазиатские 4-значные разряды | `ja ko zh` | `-(10^20 - 1)` .. `10^20 - 1` |
+
+Гарантированный диапазон означает, что у локали есть именованные разряды для всех групп внутри этого интервала.
+
+## Локали с западными 3-значными разрядами
+
+Большинство локалей используют группировку по 3 цифры:
+
+```text
+тысяча, миллион, миллиард, триллион
+```
+
+Старшая именованная группа находится на уровне `10^12`, поэтому документированный максимум:
+
+```ruby
+999_999_999_999_999
+```
+
+То есть `999 триллионов` плюс младшие группы.
+
+Примеры:
+
+```ruby
+Num2words.to_words(999_999_999_999_999, :en)
+Num2words.to_words(999_999_999_999_999, :ru)
+Num2words.to_words(-999_999_999_999_999, :fr)
+```
+
+Значения `10^15` и выше требуют именованной группы `10^15`, которой сейчас нет в общем каталоге разрядов.
+
+## Локали с индийскими разрядами
+
+Эти локали используют индийскую систему разрядов в Ruby-модулях локалей:
+
+```text
+bn gu hi kn ml mr pa ta te ur
+```
+
+Реализованные именованные группы:
+
+```text
+тысяча, lakh, crore, arab
+```
+
+Старшая основная группа - `arab`, то есть `10^9`, поэтому документированный максимум:
+
+```ruby
+999_999_999_999
+```
+
+То есть `999 arab` плюс младшие группы.
+
+Примеры:
+
+```ruby
+Num2words.to_words(999_999_999_999, :hi)
+Num2words.to_words(999_999_999_999, :ur)
+Num2words.to_words(-999_999_999_999, :bn)
+```
+
+Значения `10^12` и выше могут все еще выводиться через рекурсивную композицию, но такой результат сейчас не гарантируется как идиоматичный или стабильный.
+
+## Восточноазиатские 4-значные разряды
+
+Эти локали используют группировку по 4 цифры:
+
+```text
+ja ko zh
+```
+
+Ruby-модули локалей определяют пять 4-значных групп:
+
+| Локаль | Разряды |
+| --- | --- |
+| `ja` | `万`, `億`, `兆`, `京` |
+| `ko` | `만`, `억`, `조`, `경` |
+| `zh` | `万`, `亿`, `兆`, `京` |
+
+Старшая именованная группа находится на уровне `10^16`, поэтому документированный максимум:
+
+```ruby
+99_999_999_999_999_999_999
+```
+
+То есть `10^20 - 1`.
+
+Примеры:
+
+```ruby
+Num2words.to_words(99_999_999_999_999_999_999, :ja)
+Num2words.to_words(99_999_999_999_999_999_999, :ko)
+Num2words.to_words(99_999_999_999_999_999_999, :zh)
+```
+
+Значения `10^20` и выше требуют следующего имени 4-значного разряда и сейчас не гарантируются.
+
+## Дроби и валюты
+
+Целая часть дробного числа или денежной суммы подчиняется тому же лимиту локали.
+
+Примеры:
+
+```ruby
+Num2words.to_words("999999999999999.99", :en)
+Num2words.to_currency("999999999999.99", :hi, code: :INR)
+```
+
+Дробные знаменатели сейчас определены до `1_000_000_000`. Очень длинные десятичные строки могут перейти на дефолтное слово дроби локали, если знаменатель выходит за пределы каталога дробей.
+
+## Текущее поведение выше лимитов
+
+Выше документированного диапазона поведение сейчас не специфицировано:
+
+- часть локалей может выбросить исключение;
+- часть локалей может пропустить имя разряда;
+- часть локалей может составить технически читаемую, но неестественную фразу;
+- результат может измениться в будущей версии.
+
+Приложения, которые обрабатывают очень большие числа от пользователя, должны валидировать ввод до вызова `num2words`.
+
+## Возможное развитие
+
+В будущей версии можно добавить:
+
+- `Num2words.locale_limits(locale)`;
+- строгую проверку значений выше лимита локали;
+- поведение `strict: true` и `strict: false`;
+- specs, которые фиксируют максимум для каждой локали.