num2words 0.3.0 → 0.4.0

data/docs/api.md

@@ -0,0 +1,478 @@
+# 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_available?`
+
+Checks whether a currency is available for a locale.
+
+```ruby
+Num2words.currency_available?(:ru, :RUB)
+# => true
+
+Num2words.currency_available?(:ru, "usd")
+# => true
+
+Num2words.currency_available?(:ru, :XYZ)
+# => false
+```
+
+### `Num2words.currency_info`
+
+Returns currency metadata for a locale or `nil` when the currency is unavailable.
+
+```ruby
+Num2words.currency_info(:ru, :RUB)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+
+Num2words.currency_info(:ru, :XYZ)
+# => nil
+```
+
+### `Num2words.default_currency_info`
+
+Returns metadata for the locale default currency.
+
+```ruby
+Num2words.default_currency_info(:ru)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+```
+
+### `Num2words.available_locales`
+
+Returns supported locale codes.
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+```
+
+### `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)
+- [Rails integration](rails.md)
+- [Locale development guide](locale_development.md)
+- [Russian locale development guide](locale_development.ru.md)