num2words 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82267cd5645c3767f5b34c5c7c54d6f997ee26f19425b86937ee021f747f19f4
-  data.tar.gz: 33da5152ce64b117d4d9e59f2f33a63331b037cea6562f3c6fafc77d6b9f9f71
+  metadata.gz: 78f705a73f571176b4d920dfe220590d2bd217ea513fb817028a0ae2c22221cd
+  data.tar.gz: 1e8726b93feee82a3b87143ae8a25edf388d726f65ecf424ec713fcc4323ea08
 SHA512:
-  metadata.gz: 9808bb66c09d3acecb944d1c1b37a3af17e46f758f6f500d5f618eecca798b3bf1e5b8bff415e23f9eb0d47804b672c1b509de2d89e77861dbc2fec2e88a8775
-  data.tar.gz: fac35c5117774db5619fc82d4153f8ce0495dcb13e27fdba3b4726e211f6a155788f4b1a035987f4a083ec7035ea0b6429bb8d3549d03c8c64906d1325731f81
+  metadata.gz: d8a078fef78bc1e26fc28d90c6604e6a3a09aa05e3b716df2faea6d7423bb91a4de1c907eaa7d7e9c85b0d3019fa98257f6b499113f1987d646c902680bcdd66
+  data.tar.gz: a87e663b01668bdf114cba5eb2c2f9f55b453b4aae314b5ceceac78047574e1fc5917a46d97fddaf60cea2a64333c2b1f0901694daed5aade3beff7d6682c1b9

data/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-22.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "2.7"
+          - "3.0"
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "3.4"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec
+
+      - name: Build gem
+        run: gem build num2words.gemspec

data/CHANGELOG.md

@@ -11,6 +11,24 @@
 
 ---
 
+## [0.3.1] - 2026-07-04
+
+### Added
+- Набор benchmark-проверок: `benchmark/converter_benchmark.rb` и `bundle exec rake benchmark`.
+- Справочник API: `docs/api.md` и `docs/api.ru.md`.
+- Документация по числовым лимитам: `docs/limits.md` и `docs/limits.ru.md`.
+- Rake-задачи для разработки и релизной проверки:
+  - `bundle exec rake spec`
+  - `bundle exec rake build`
+  - `bundle exec rake release:check`
+  - `bundle exec rake locales`
+  - `bundle exec rake currencies`
+
+### Fixed
+- Добавлена runtime-зависимость `bigdecimal` для совместимости с Ruby 3.4+.
+
+---
+
 ## [0.3.0] - 2026-06-27
 
 ### Added

data/README.md

@@ -143,6 +143,16 @@ Num2words.to_currency(BigDecimal("21.05"), :ru)
 - `minor: :always | :nonzero | :never` — вывод младшей денежной единицы.
 - `code: :USD` — выбор валюты для `to_currency`.
 
+Полная справка по API:
+
+- [English](docs/api.md)
+- [Русский](docs/api.ru.md)
+
+Ограничения числовых разрядов:
+
+- [English](docs/limits.md)
+- [Русский](docs/limits.ru.md)
+
 ---
 
 ## Консоль
@@ -203,6 +213,11 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 
 После добавления локали стоит покрыть ее отдельным spec и добавить в `spec/currency_catalog_spec.rb`.
 
+Подробная инструкция:
+
+- [English](docs/locale_development.md)
+- [Русский](docs/locale_development.ru.md)
+
 ---
 
 ## Тестирование
@@ -211,6 +226,17 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 bundle exec rspec
 ```
 
+## Rake tasks
+
+```bash
+bundle exec rake spec
+bundle exec rake build
+bundle exec rake release:check
+bundle exec rake locales
+bundle exec rake currencies
+bundle exec rake benchmark
+```
+
 ---
 
 ## Roadmap

data/Rakefile

@@ -2,9 +2,45 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yaml"
 
-# таска для запуска тестов
 RSpec::Core::RakeTask.new(:spec)
 
-# по умолчанию запускаем тесты
+task build: "build:clean"
+
+namespace :build do
+  task :clean do
+    Dir.glob("num2words-*.gem").each { |file| File.delete(file) }
+  end
+end
+
+namespace :release do
+  desc "Run tests and build the gem"
+  task check: [:spec, :build]
+end
+
+desc "Print supported locale codes"
+task :locales do
+  locales = Dir[File.expand_path("config/locales/*.yml", __dir__)]
+            .map { |file| File.basename(file, ".yml") }
+            .sort
+
+  puts locales.join(" ")
+end
+
+desc "Print supported currency codes"
+task :currencies do
+  currencies = YAML.load_file(File.expand_path("config/locales/ru.yml", __dir__))
+                   .dig("ru", "num2words", "currencies")
+                   .keys
+                   .sort
+
+  puts currencies.join(" ")
+end
+
+desc "Run converter benchmark"
+task :benchmark do
+  sh "ruby benchmark/converter_benchmark.rb"
+end
+
 task default: :spec

data/benchmark/converter_benchmark.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require_relative "../lib/num2words"
+
+DEFAULT_ITERATIONS = 100
+
+def all_locales
+  Dir[File.expand_path("../config/locales/*.yml", __dir__)]
+    .map { |file| File.basename(file, ".yml").to_sym }
+    .sort
+end
+
+def selected_locales
+  requested = ENV.fetch("LOCALES", "").split(",").map(&:strip).reject(&:empty?).map(&:to_sym)
+  return all_locales if requested.empty?
+
+  unknown = requested - all_locales
+  abort "Unknown locales: #{unknown.join(', ')}" unless unknown.empty?
+
+  requested
+end
+
+def iterations
+  Integer(ENV.fetch("ITERATIONS", DEFAULT_ITERATIONS.to_s))
+rescue ArgumentError
+  abort "ITERATIONS must be an integer"
+end
+
+SCENARIOS = {
+  integer: ->(locale) { Num2words.to_words(123_456_789, locale) },
+  decimal: ->(locale) { Num2words.to_words("12345.67", locale) },
+  date: ->(locale) { Num2words.to_words("2024-08-21", locale) },
+  time: ->(locale) { Num2words.to_words("14:35:42", locale) },
+  datetime: ->(locale) { Num2words.to_words("2024-08-21 14:35:42", locale) },
+  currency: ->(locale) { Num2words.to_currency("12345.67", locale) }
+}.freeze
+
+def measure_scenarios(locales, iterations_count)
+  SCENARIOS.map do |name, callable|
+    calls = locales.size * iterations_count
+    elapsed = Benchmark.realtime do
+      iterations_count.times do
+        locales.each { |locale| callable.call(locale) }
+      end
+    end
+
+    [name, calls, elapsed]
+  end
+end
+
+def measure_slowest_locales(locales, iterations_count)
+  locales.map do |locale|
+    calls = SCENARIOS.size * iterations_count
+    elapsed = Benchmark.realtime do
+      iterations_count.times do
+        SCENARIOS.each_value { |callable| callable.call(locale) }
+      end
+    end
+
+    [locale, calls, elapsed]
+  end.sort_by { |(_, _, elapsed)| -elapsed }.first(10)
+end
+
+def print_table(headers, rows)
+  widths = headers.each_with_index.map do |header, index|
+    ([header.length] + rows.map { |row| row[index].to_s.length }).max
+  end
+
+  puts headers.each_with_index.map { |header, index| header.ljust(widths[index]) }.join("  ")
+  puts widths.map { |width| "-" * width }.join("  ")
+  rows.each do |row|
+    puts row.each_with_index.map { |value, index| value.to_s.ljust(widths[index]) }.join("  ")
+  end
+end
+
+locales = selected_locales
+iterations_count = iterations
+
+puts "num2words benchmark"
+puts "Locales: #{locales.join(', ')}"
+puts "Iterations per locale: #{iterations_count}"
+puts
+
+scenario_rows = measure_scenarios(locales, iterations_count).map do |name, calls, elapsed|
+  [name, calls, format("%.4f", elapsed), format("%.4f", (elapsed / calls) * 1000)]
+end
+
+print_table(["Scenario", "Calls", "Total, s", "ms/call"], scenario_rows)
+puts
+
+slowest_rows = measure_slowest_locales(locales, iterations_count).map do |locale, calls, elapsed|
+  [locale, calls, format("%.4f", elapsed), format("%.4f", (elapsed / calls) * 1000)]
+end
+
+print_table(["Slowest locale", "Calls", "Total, s", "ms/call"], slowest_rows)

data/docs/api.md

@@ -0,0 +1,422 @@
+# API Reference
+
+This document describes the public API of `num2words`.
+
+## Loading
+
+```ruby
+require "num2words"
+```
+
+This loads the module API and core extensions for supported Ruby classes.
+
+## Module API
+
+### `Num2words.to_words`
+
+```ruby
+Num2words.to_words(value, locale = I18n.default_locale, only = nil, short = false, **options)
+```
+
+Converts numbers, dates, times and date-times to words.
+
+Examples:
+
+```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 locale form is also supported:
+
+```ruby
+Num2words.to_words(123, locale: :en)
+# => "one hundred twenty three"
+```
+
+### `Num2words.to_currency`
+
+```ruby
+Num2words.to_currency(amount, locale = I18n.default_locale, **options)
+```
+
+Converts a numeric amount to words using the selected locale and currency.
+
+Examples:
+
+```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` adds convenience methods to common classes.
+
+### `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` is not currently defined. Use `Num2words.to_currency("12.50", :en)` for string amounts.
+
+### `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"
+```
+
+## Supported Input Types
+
+`to_words` supports:
+
+- `Integer`
+- `Float`
+- `Date`
+- `Time`
+- `DateTime`
+- integer strings, for example `"007"` or `"-42"`
+- decimal strings with dot or comma, for example `"3.5"` or `"3,5"`
+- date strings, for example `"2024-08-21"` or `"21.08.2024"`
+- time strings, for example `"14:35"` or `"14:35:42"`
+- date-time strings, for example `"2024-08-21 14:35:42"`
+
+`to_currency` supports:
+
+- `Integer`
+- `Float`
+- `String`
+- `BigDecimal`
+
+String currency amounts may use dot or comma as decimal separator.
+
+## Options
+
+### `locale`
+
+Selects the locale.
+
+```ruby
+Num2words.to_words(123, :ru)
+Num2words.to_words(123, locale: :ru)
+```
+
+If no locale is passed, `I18n.default_locale` is used.
+
+### `style`
+
+Controls fractional output in `to_words`.
+
+Supported values:
+
+- `:fraction` - default fraction style.
+- `:decimal` - reads fractional digits one by one when the locale supports decimal digit style.
+
+```ruby
+Num2words.to_words(12.12, :en)
+# => "twelve and twelve hundredths"
+
+Num2words.to_words(12.12, :en, style: :decimal)
+# => "twelve point one two"
+```
+
+### `joiner`
+
+Controls the connector for fraction style.
+
+Supported values:
+
+- `:default`
+- `:and`
+
+```ruby
+Num2words.to_words(0.5, :ru)
+# => "ноль целых пять десятых"
+
+Num2words.to_words(0.5, :ru, joiner: :and)
+# => "ноль и пять десятых"
+```
+
+Invalid values raise `ArgumentError`.
+
+### `date_case`
+
+Controls date day case for locales that support it.
+
+Supported values:
+
+- `:default`
+- `:genitive`
+
+```ruby
+Num2words.to_words("2024-08-21", :ru)
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+
+Num2words.to_words("2024-08-21", :ru, date_case: :genitive)
+# => "двадцать первого августа две тысячи двадцать четвёртого года"
+```
+
+Invalid values raise `ArgumentError`.
+
+### `short`
+
+Enables short output for time or date-time values.
+
+```ruby
+Num2words.to_words("14:35:42", :ru, short: true)
+# => "четырнадцать часов тридцать пять минут"
+```
+
+With date-time values, `short: true` returns a shortened date-time string unless `only` is used.
+
+### `only`
+
+Selects a part of a date-time value.
+
+```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)
+# => "четырнадцать часов тридцать пять минут сорок две секунды"
+```
+
+The legacy positional form is also supported:
+
+```ruby
+"2024-08-21 14:35:42".to_words(:ru, :date)
+"2024-08-21 14:35:42".to_words(:ru, :time)
+```
+
+### `format`
+
+Used by date and time conversion.
+
+For dates:
+
+- `:default`
+- `:nominative` when provided by locale data.
+- `:short` returns numeric date format `DD.MM.YYYY`.
+
+For times:
+
+- `:default`
+- `:hours_only`
+- `:hours_minutes`
+- `:hours_minutes_seconds`
+
+```ruby
+Num2words.to_words("14:35:42", :ru, format: :hours_minutes)
+# => "четырнадцать часов тридцать пять минут"
+```
+
+Unsupported time formats raise `ArgumentError`.
+
+### `word_case`
+
+Changes result casing.
+
+Supported values:
+
+- `: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`
+
+For locales with grammatical gender, selects feminine forms where supported.
+
+```ruby
+Num2words.to_words(1, :ru, feminine: true)
+# => "одна"
+```
+
+### `code`
+
+Selects currency code in `to_currency`.
+
+```ruby
+Num2words.to_currency(12.50, :ru, code: :USD)
+# => "двенадцать долларов пятьдесят центов"
+```
+
+If the currency is not available for the locale, `num2words` falls back to the locale default currency and may emit a warning depending on configuration.
+
+### `minor`
+
+Controls minor currency unit output.
+
+Supported values:
+
+- `:always` - always include minor units.
+- `:nonzero` - include minor units only when the minor value is greater than zero.
+- `:never` - do not include minor units.
+
+```ruby
+Num2words.to_currency(12, :ru)
+# => "двенадцать рублей ноль копеек"
+
+Num2words.to_currency(12, :ru, minor: :nonzero)
+# => "двенадцать рублей"
+
+Num2words.to_currency(12.50, :ru, minor: :never)
+# => "двенадцать рублей"
+```
+
+Invalid values raise `ArgumentError`.
+
+## Configuration
+
+### `Num2words.default_currency`
+
+Gets or sets default currency.
+
+```ruby
+Num2words.default_currency(:ru)
+# => :RUB
+
+Num2words.default_currency(:ru, :USD)
+# => :USD
+```
+
+### `Num2words.available_currencies`
+
+Returns currency codes available for a locale.
+
+```ruby
+Num2words.available_currencies(:ru)
+# => [:RUB, :USD, :EUR, ...]
+```
+
+### `Num2words.currency_warnings`
+
+Controls warnings when requested currency is unavailable.
+
+```ruby
+Num2words.currency_warnings = false
+```
+
+## Locales and Currencies
+
+Supported locales:
+
+```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
+```
+
+Each completed locale supports the same 32 currency codes:
+
+```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
+```
+
+## Errors
+
+Unsupported input type:
+
+```ruby
+Num2words.to_words(Object.new, :en)
+# raises ArgumentError: Unsupported input type: ...
+```
+
+Unsupported options:
+
+```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
+```
+
+Unsupported currency amount:
+
+```ruby
+Num2words.to_currency("abc", :en)
+# raises ArgumentError: Unsupported currency amount: "abc"
+```
+
+## Development References
+
+- [Numeric limits](limits.md)
+- [Locale development guide](locale_development.md)
+- [Russian locale development guide](locale_development.ru.md)