strings-numeral 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c3b788a344901a4da93755096f0c7657e6a28218ad6dc419eafcbc61be0aa98
+  data.tar.gz: 220f0401d2d1c6c4d1f39c01509a9265e142ab418f80a5e6339134c60d2e46ca
+SHA512:
+  metadata.gz: 959a8ccf4432fafb017afe51c8b27fddacd1d4ec8cbe672067ffe74dc15f22ec0c51955403382e8640a2826923044fba78ab894f385f8bb134afda9869934fe2
+  data.tar.gz: 263c41b90e351ffbcb5acc7905fecfff6a63c42d8dbd1b8f8ceaad0854291b7bec76fef55423443b2d54a6f78f7fc3ccd2973965a8ac1993b2b3095d893b928a

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## [v0.1.0] - 2019-12-18
+
+* Initial implementation and release
+
+[v0.1.0]: https://github.com/piotrmurach/strings-numeral/compare/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Piotr Murach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,327 @@
+<div align="center">
+  <img width="225" src="https://github.com/piotrmurach/strings/blob/master/assets/strings_logo.png" alt="strings logo" />
+</div>
+
+# Strings::Numeral
+
+[![Gem Version](https://badge.fury.io/rb/strings-numeral.svg)][gem]
+[![Build Status](https://secure.travis-ci.org/piotrmurach/strings-numeral.svg?branch=master)][travis]
+[![Build status](https://ci.appveyor.com/api/projects/status/494htkcankqegwtg?svg=true)][appveyor]
+[![Maintainability](https://api.codeclimate.com/v1/badges/de0c5ad1cba6715b7135/maintainability)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/strings-numeral/badge.svg?branch=master)][coverage]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/strings-numeral.svg?branch=master)][inchpages]
+
+[gem]: http://badge.fury.io/rb/strings-numeral
+[travis]: http://travis-ci.org/piotrmurach/strings-numeral
+[appveyor]: https://ci.appveyor.com/project/piotrmurach/strings-numeral
+[codeclimate]: https://codeclimate.com/github/piotrmurach/strings-numeral/maintainability
+[coverage]: https://coveralls.io/github/piotrmurach/strings-numeral?branch=master
+[inchpages]: http://inch-ci.org/github/piotrmurach/strings-numeral
+
+> Express numbers as string numerals.
+
+**Strings::Numeral** provides conversions of numbers to numerals component for [Strings](https://github.com/piotrmurach/strings).
+
+## Features
+
+* No monkey-patching String class
+* Functional API that can be easily wrapped by other objects
+* Instance based configuration
+* Highly performant
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'strings-numeral'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install strings-numeral
+
+## Contents
+
+* [1. Usage](#1-usage)
+* [2. API](#2-api)
+  * [2.1 numeralize](#21-numeralize)
+  * [2.2 cardinalize](#22-cardinalize)
+  * [2.3 ordinalize](#23-ordinalize)
+  * [2.4 monetize](#24-monetize)
+  * [2.5 romanize](#25-romanize)
+  * [2.6 configuration](#26-configuration)
+* [3. Extending core classes](#3-extending-core-classes)
+
+## 1. Usage
+
+**Strings::Numeral** helps to express any number as a numeral in words. It exposes few methods to achieve this. For example, you can express a number as a cardinal numeral using `cardinalize`:
+
+```ruby
+Strings::Numeral.cardinalize(1234)
+# => "one thousand, two hundred thirty four"
+```
+
+But you're not limited to converting integers only. It can handle decimals as well:
+
+```ruby
+Strings::Numeral.cardinalize(1234.567)
+# => "one thousand, two hundred thirty four and five hundred sixty seven thousandths"
+```
+
+For more options on how to customize formatting see [configuration](#25-configuration) section.
+
+Similarly, you can convert a number to a ordinal numeral with `ordinalize`:
+
+```ruby
+Strings::Numeral.ordinalize(1234)
+# => "one thousand, two hundred thirty fourth"
+```
+
+You can also convert a number to a short ordinal:
+
+```ruby
+Strings::Numeral.ordinalize(1234, short: true)
+# => "1234th"
+```
+
+Using `monetize` you can convert any number into a monetary numeral:
+
+```ruby
+Strings::Numeral.monetize(1234.567)
+# => "one thousand, two hundred thirty four dollars and fifty seven cents",
+```
+
+To turn a number into a roman numeral use `romanize`:
+
+```ruby
+Strings::Numeral.romanize(2020)
+# => "MMXX"
+```
+
+## 2. API
+
+### 2.1 numeralize
+
+The `normalize` is a wrapping method for the [cardinalize](#22-cardinalize) and [ordinalize](#23-ordinalize) methods. By default it converts a number to cardinal numeral:
+
+```ruby
+Strings::Numeral.numeralize(1234.567)
+# => "one thousand, two hundred thirty four and five hundred sixty seven thousandths"
+```
+
+You can also make it convert to ordinal numerals using `:term` option:
+
+```ruby
+Strings::Numeral.numeralize(1234.567, term: :ord)
+# => "one thousand, two hundred thirty fourth and five hundred sixty seven thousandths"
+```
+
+### 2.2 cardinalize
+
+To express a number as a cardinal numeral use `cardinalize` or `cardinalise`.
+
+```ruby
+Strings::Numeral.cardinalize(1234)
+# => "one thousand, two hundred thirty four"
+```
+
+You're not limited to integers only. You can also express decimal numbers as well:
+
+```ruby
+Strings::Numeral.cardinalize(123.456)
+# => "one hundred twenty three and four hundred fifty six thousandths"
+```
+
+By default the fractional part of a decimal number is expressed as a fraction. If you wish to spell out fractional part digit by digit use `:decimal` option with `:digit` value:
+
+```ruby
+Strings::Numeral.cardinalize(123.456, decimal: :digit)
+# => "one hundred twenty three point four five six"
+```
+
+You may prefer to use a different delimiter for thousand's. You can do use by passing the `:delimiter` option:
+
+```ruby
+Strings::Numeral.cardinalize(1_234_567, delimiter: " and ")
+# => "one million and two hundred thirty four thousand and five hundred sixty seven"
+```
+
+To change word that splits integer from factional part use `:separator` option:
+
+```ruby
+Strings::Numeral.cardinalize(1_234.567, separator: "dot")
+# => "one thousand, two hundred thirty four dot five hundred sixty seven thousandths"
+```
+
+### 2.3 ordinalize
+
+To express a number as a cardinal numeral use `ordinalize` or `ordinalise`.
+
+```ruby
+Strings::Numeral.ordinalize(1234)
+# => "one thousand, two hundred thirty fourth"
+```
+
+You're not limited to integers only. You can also express decimal numbers as well:
+
+```ruby
+Strings::Numeral.ordinalize(123.456)
+# => "one hundred twenty third and four hundred fifty six thousandths"
+```
+
+By default the fractional part of a decimal number is expressed as a fraction. If you wish to spell out fractional part digit by digit use `:decimal` option with `:digit` value:
+
+```ruby
+Strings::Numeral.ordinalize(123.456, decimal: :digit)
+# => "one hundred twenty third point four five six"
+```
+
+You may prefer to use a different delimiter for thousand's. You can do use by passing the `:delimiter` option:
+
+```ruby
+Strings::Numeral.ordinalize(1_234_567, delimiter: " and ")
+# => "one million and two hundred thirty four thousand and five hundred sixty seventh"
+```
+
+To change word that splits integer from factional part use `:separator` option:
+
+```ruby
+Strings::Numeral.ordinalize(1_234.567, separator: "dot")
+# => "one thousand, two hundred thirty fourth dot five hundred sixty seven thousandths"
+```
+
+### 2.4 monetize
+
+To express a number as a monetary numeral use `monetize` or `monetise`.
+
+```ruby
+Strings::Numeral.monetize(123.456)
+# => "one hundred twenty three dollars and forty six cents",
+```
+
+By default `monetize` displays money using `USD` currency. You can change this with the `:currency` option that as value accepts internationally recognised symbols. Currently support currencies are: `EUR`, `GBP`, `JPY`, `PLN` and `USD`.
+
+```ruby
+Strings::Numeral.monetize(123.456, currency: :jpy)
+# => "one hundred twenty three yen and forty six sen"
+```
+
+### 2.5 romanize
+
+To convert a number into a Roman numeral use `romanize`:
+
+```ruby
+Strings::Numeral.romanize(2020)
+# => "MMXX"
+```
+
+### 2.6 configuration
+
+All available configuration options are:
+
+* `currency` - Adds currency words for integer and fractional parts. Supports `EUR`, `GBP`, `JPY`, `PLN` and `USD`. Defaults to `USD`.
+* `decimal` - Formats fractional part of a number. The `:digit` value spells out every digit and the `:fraction` appends divider word. Defaults to `:fraction`.
+* `delimiter` - Sets the thousands delimiter. Defaults to `", "`.
+* `separator` - Sets the separator between the fractional and integer parts. Defaults to `"and"` for `:fraction` and `"point"` for `:digit` option.
+* `trailing_zeros` - If `true` keeps trailing zeros at the end of the fractional part. Defaults to `false`.
+
+The above options can be passed as keyword arguments:
+
+```ruby
+Strings::Numeral.cardinalize("12.100", trailing_zeros: true, decimal: :digit)
+# => "twelve point one zero zero"
+```
+
+Or you can configure the options for an instance:
+
+```ruby
+numeral = Strings::Numeral.new do |config|
+  config.delimiter "; "
+  config.separator "dot"
+  config.decimal :digit
+  config.trailing_zeros true
+end
+```
+
+Once configured, you can use the instance like so:
+
+```ruby
+numeral.cardinalize("1234.56700")
+# => "one thousand; two hundred thirty four dot five six seven zero zero"
+```
+
+## 3. Extending Core Classes
+
+Though it is highly discouraged to pollute core Ruby classes, you can add the required methods to `String`, `Float` and `Integer` classes using refinements.
+
+For example, if you wish to only extend `Float` class with `cardinalize` method do:
+
+```ruby
+module MyFloatExt
+  refine Float do
+    def cardinalize(**options)
+      Strings::Numeral.cardinalize(self, **options)
+    end
+  end
+end
+```
+
+Then `cardinalize` method will be available for any float number where refinement is applied:
+
+```ruby
+using MyFloatExt
+
+12.34.cardinalize
+# => "twelve and thirty four"
+```
+
+However, if you want to include all the **Strings::Numeral** methods in `Float`, `Integer` and `String` classes, you can use provided extensions file:
+
+
+```ruby
+require "strings/numeral/extensions"
+
+using Strings::Numeral::Extensions
+```
+
+Alternatively, you can choose what class you wish to refine with all the methods:
+
+```ruby
+require "bigdecimal"
+require "strings/numeral/extensions"
+
+module MyBigDecimalExt
+  refine BigDecimal do
+    include Strings::Numeral::Extensions::Methods
+  end
+end
+
+using MyBigDecimalExt
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/strings-numeral. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Strings::Numeral project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/strings-numeral/blob/master/CODE_OF_CONDUCT.md).
+
+## Copyright
+
+Copyright (c) 2019 Piotr Murach. See LICENSE for further details.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+FileList["tasks/**/*.rake"].each(&method(:import))
+
+desc "Run all specs"
+task ci: %w[ spec ]
+
+task default: :spec

data/lib/strings-numeral.rb

@@ -0,0 +1 @@
+require "strings/numeral"

data/lib/strings/numeral.rb

@@ -0,0 +1,557 @@
+# frozen_string_literal: true
+
+require_relative "numeral/configuration"
+require_relative "numeral/version"
+
+module Strings
+  class Numeral
+    class Error < StandardError; end
+
+    NEGATIVE = "negative"
+    HUNDRED = "hundred"
+    ZERO = "zero"
+    AND = "and"
+    POINT = "point"
+    SPACE = " "
+
+    CARDINALS = {
+      0 => "",
+      1 => "one",
+      2 => "two",
+      3 => "three",
+      4 => "four",
+      5 => "five",
+      6 => "six",
+      7 => "seven",
+      8 => "eight",
+      9 => "nine",
+      10 => "ten",
+      11 => "eleven",
+      12 => "twelve",
+      13 => "thirteen",
+      14 => "fourteen",
+      15 => "fifteen",
+      16 => "sixteen",
+      17 => "seventeen",
+      18 => "eighteen",
+      19 => "nineteen",
+      20 => "twenty",
+      30 => "thirty",
+      40 => "forty",
+      50 => "fifty",
+      60 => "sixty",
+      70 => "seventy",
+      80 => "eighty",
+      90 => "ninety",
+    }.freeze
+
+    CARDINAL_TO_SHORT_ORDINAL = {
+      0 => "th",
+      1 => "st",
+      11 => "th",
+      2 => "nd",
+      12 => "th",
+      3 => "rd",
+      13 => "th",
+      4 => "th",
+      5 => "th",
+      6 => "th",
+      7 => "th",
+      8 => "th",
+      9 => "th"
+    }.freeze
+
+    CARDINAL_TO_ORDINAL = {
+      "zero" => "zeroth",
+      "one" => "first",
+      "two" => "second",
+      "three" => "third",
+      "four" => "fourth",
+      "five" => "fifth",
+      "six" => "sixth",
+      "seven" => "seventh",
+      "eight" => "eighth",
+      "nine" => "ninth",
+      "ten" => "tenth",
+      "eleven" => "eleventh",
+      "twelve" => "twelfth",
+      "thirteen" => "thirteenth",
+      "fourteen" => "fourteenth",
+      "fifteen" => "fifteenth",
+      "sixteen" =>  "sixteenth",
+      "seventeen" =>  "seventeenth",
+      "eighteen" =>  "eighteenth",
+      "nineteen" =>  "nineteenth",
+      "twenty" =>  "twentieth",
+      "thirty" =>  "thirtieth",
+      "forty" => "fortieth",
+      "fifty" => "fiftieth",
+      "sixty" => "sixtieth",
+      "seventy" => "seventieth",
+      "eighty" => "eightieth",
+      "ninety" => "ninetieth"
+    }.freeze
+
+    CARDINAL_TO_ROMAN = {
+      1 => "I",
+      4 => "IV",
+      5 => "V",
+      9 => "IX",
+      10 => "X",
+      40 => "XL",
+      50 => "L",
+      90 => "XC",
+      100 => "C",
+      400 => "CD",
+      500 => "D",
+      900 => "CM",
+      1000 => "M"
+    }.freeze
+
+    SCALES = [
+      "hundreds-tens-ones",
+      "thousand",
+      "million",
+      "billion",
+      "trillion",
+      "quadrillion",
+      "quintillion",
+      "sextillion",
+      "septillion",
+      "octillion",
+      "nonillion",
+      "decillion",
+      "undecillion",
+      "duodecillion",
+      "tredecillion",
+      "quattuordecillion",
+      "quindecillion",
+      "sexdecillion",
+      "septemdecillion",
+      "octodecillion",
+      "novemdecillion",
+      "vigintillion"
+    ].freeze
+
+    DECIMAL_SLOTS = [
+      "tenths",
+      "hundredths",
+      "thousandths",
+      "ten-thousandths",
+      "hundred-thousandths",
+      "millionths",
+      "ten-millionths",
+      "hundred-millionths",
+      "billionths",
+      "ten-billionths",
+      "hundred-billionths",
+      "trillionths",
+      "quadrillionths",
+      "quintillionths",
+      "sextillionths",
+      "septillionths",
+      "octillionths",
+      "nonillionths",
+      "decillionths",
+      "undecillionths",
+      "duodecillionths",
+      "tredecillionths",
+      "quattuordecillionths",
+      "quindecillionths",
+      "sexdecillionths",
+      "septemdecillionths",
+      "octodecillionths",
+      "novemdecillionths",
+      "vigintillionths"
+    ].freeze
+
+    CURRENCIES = {
+      eur: {
+        unit: "euro",
+        units: "euros",
+        decimal_unit: "cent",
+        decimal_units: "cents"
+      },
+      gbp: {
+        unit: "pound",
+        units: "pounds",
+        decimal_unit: "pence",
+        decimal_units: "pence",
+      },
+      jpy: {
+        unit: "yen",
+        units: "yen",
+        decimal_unit: "sen",
+        decimal_units: "sen",
+      },
+      pln: {
+        unit: "zloty",
+        units: "zlotys",
+        decimal_unit: "grosz",
+        decimal_units: "groszy"
+      },
+      usd: {
+        unit: "dollar",
+        units: "dollars",
+        decimal_unit: "cent",
+        decimal_units: "cents"
+      }
+    }.freeze
+
+    def self.instance
+      @instance ||= Numeral.new
+    end
+
+    class << self
+      def numeralize(num, **options)
+        instance.numeralize(num, **options)
+      end
+      alias :numeralise :numeralize
+
+      def cardinalize(num, **options)
+        instance.cardinalize(num, **options)
+      end
+      alias :cardinalise :cardinalize
+
+      def ordinalize(num, **options)
+        instance.ordinalize(num, **options)
+      end
+      alias :ordinalise :ordinalize
+
+      def ordinalize_short(num)
+        instance.ordinalize_short(num)
+      end
+
+      def monetize(num, **options)
+        instance.monetize(num, **options)
+      end
+      alias :monetise :monetize
+
+      def romanize(num)
+        instance.romanize(num)
+      end
+      alias :romanise :romanize
+    end
+
+    # Create numeral with custom configuration
+    #
+    # @yieldparam [Configuration]
+    #
+    # @return [Numeral]
+    #
+    # @api public
+    def initialize
+      @configuration = Configuration.new
+      if block_given?
+        yield @configuration
+      end
+    end
+
+    # Convert a number to a numeral
+    #
+    # @param [Numeric,String] num
+    #   the number to convert
+    #
+    # @api public
+    def numeralize(num, **options)
+      case options.delete(:term)
+      when /ord/
+        ordinalize(num, **options)
+      else
+        cardinalize(num, **options)
+      end
+    end
+
+    # Convert a number to a cardinal numeral
+    #
+    # @example
+    #   cardinalize(1234)
+    #   # => one thousand, two hundred thirty four
+    #
+    # @param [Numeric,String] num
+    #
+    # @return [String]
+    #
+    # @api public
+    def cardinalize(num, **options)
+      convert_numeral(num, **options)
+    end
+    alias :cardinalise :cardinalize
+
+    # Convert a number to an ordinal numeral
+    #
+    # @example
+    #   ordinalize(1234)
+    #   # => one thousand, two hundred thirty fourth
+    #
+    #   ordinalize(12, short: true) # => 12th
+    #
+    # @param [Numeric,String] num
+    #   the number to convert
+    #
+    # @return [String]
+    #
+    # @api public
+    def ordinalize(num, **options)
+      if options[:short]
+        ordinalize_short(num)
+      else
+        decimals = (num.to_i.abs != num.to_f.abs)
+        sentence = convert_numeral(num, **options)
+        separators = [AND, POINT,
+                      options.fetch(:separator, @configuration.separator)].compact
+
+        if decimals && sentence =~ /(\w+) (#{Regexp.union(separators)})/
+          last_digits = $1
+          separator = $2
+          replacement = CARDINAL_TO_ORDINAL[last_digits]
+          pattern = /#{last_digits} #{separator}/
+          suffix = "#{replacement} #{separator}"
+        elsif sentence =~ /(\w+)$/
+          last_digits = $1
+          replacement = CARDINAL_TO_ORDINAL[last_digits]
+          pattern = /#{last_digits}$/
+          suffix = replacement
+        end
+
+        if replacement
+          sentence.sub(pattern, suffix)
+        else
+          sentence
+        end
+      end
+    end
+    alias :ordinalise :ordinalize
+
+    # Convert a number to a short ordinal form
+    #
+    # @example
+    #   ordinalize_short(123) # => 123rd
+    #
+    # @param [Numeric, String] num
+    #   the number to convert
+    #
+    # @return [String]
+    #
+    # @api private
+    def ordinalize_short(num)
+      num_abs = num.to_i.abs
+
+      num.to_i.to_s + (CARDINAL_TO_SHORT_ORDINAL[num_abs % 100] ||
+        CARDINAL_TO_SHORT_ORDINAL[num_abs % 10])
+    end
+
+    # Convert a number into a monetary numeral
+    #
+    # @example
+    #   monetize(123.45)
+    #   # => "one hundred twenty three dollars and forty five cents"
+    #
+    # @param [Numeric,String] num
+    #   the number to convert
+    #
+    # @return [String]
+    #
+    # @api public
+    def monetize(num, **options)
+      sep = options.fetch(:separator, @configuration.separator)
+      curr_name = options.fetch(:currency, @configuration.currency)
+      n = "%0.2f" % num.to_s
+      decimals = (num.to_i.abs != num.to_f.abs)
+      sentence = convert_numeral(n, **options.merge(trailing_zeros: true))
+      dec_num = n.split(".")[1]
+      curr = CURRENCIES[curr_name.to_s.downcase.to_sym]
+      separators = [AND, POINT, sep].compact
+
+      if decimals
+        regex = /(\w+) (#{Regexp.union(separators)})/
+        sentence.sub!(regex, "\\1 #{curr[:units]} \\2")
+      else
+        sentence += SPACE + (num.to_i == 1 ? curr[:unit] : curr[:units])
+      end
+
+      if decimals
+        slots = Regexp.union(DECIMAL_SLOTS.map { |slot| slot.chomp('s') })
+        regex = /(#{slots})s?/i
+        suffix = dec_num.to_i == 1 ? curr[:decimal_unit] : curr[:decimal_units]
+        if sentence.sub!(regex, suffix).nil?
+          sentence += SPACE + suffix
+        end
+      end
+
+      sentence
+    end
+    alias :monetise :monetize
+
+    # Convert a number to a roman numeral
+    #
+    # @example
+    #   romanize(2020) # => "MMXX"
+    #
+    # @param [Integer] num
+    #   the number to convert
+    #
+    # @return [String]
+    #
+    # @api public
+    def romanize(num)
+      n = num.to_i
+
+      if n < 1 || n > 4999
+        raise Error, "'#{n}' is out of range"
+      end
+
+      CARDINAL_TO_ROMAN.keys.reverse_each.reduce([]) do |word, card|
+        while n >= card
+          n -= card
+          word << CARDINAL_TO_ROMAN[card]
+        end
+        word
+      end.join
+    end
+
+    private
+
+    # Convert a number into a numeral
+    #
+    # @param [Numeric] num
+    #   the number to convert to numeral
+    # @param [String] delimiter
+    #   sets the thousand's delimiter, defaults to `, `
+    # @param [String] decimal
+    #   the decimal word conversion, defaults to `:fraction`
+    # @param [String] separator
+    #   sets the separator between the fractional and integer numerals,
+    #   defaults to `and` for fractions and `point` for digits
+    #
+    # @return [String]
+    #   the number as numeral
+    #
+    # @api private
+    def convert_numeral(num, **options)
+      delimiter = options.fetch(:delimiter, @configuration.delimiter)
+      decimal = options.fetch(:decimal, @configuration.decimal)
+      separator = options.fetch(:separator, @configuration.separator)
+
+      negative = num.to_i < 0
+      n = num.to_i.abs
+      decimals = (n != num.to_f.abs)
+
+      sentence = convert_to_words(n).join(delimiter)
+
+      if sentence.empty?
+        sentence = ZERO
+      end
+
+      if negative
+        sentence = NEGATIVE + SPACE + sentence
+      end
+
+      if decimals
+        sentence = sentence + SPACE +
+          (separator.nil? ? (decimal == :fraction ? AND : POINT) : separator) +
+          SPACE + convert_decimals(num, **options)
+      end
+
+      sentence
+    end
+
+    # Convert decimal part to words
+    #
+    # @param [String] trailing_zeros
+    #   whether or not to keep trailing zeros, defaults to `false`
+    #
+    # @return [String]
+    #
+    # @api private
+    def convert_decimals(num, **options)
+      delimiter = options.fetch(:delimiter, @configuration.delimiter)
+      decimal = options.fetch(:decimal, @configuration.decimal)
+      trailing_zeros = options.fetch(:trailing_zeros, @configuration.trailing_zeros)
+
+      dec_num = num.to_s.split(".")[1]
+      dec_num.gsub!(/0+$/, "") unless trailing_zeros
+
+      case decimal
+      when :fraction
+        unit = DECIMAL_SLOTS[dec_num.to_s.length - 1]
+        unit = unit[0...-1] if dec_num.to_i == 1 # strip off 's'
+        convert_to_words(dec_num.to_i).join(delimiter) + SPACE + unit
+      when :digit
+        dec_num.chars.map do |n|
+          (v = convert_tens(n.to_i)).empty? ? ZERO : v
+        end.join(SPACE)
+      else
+        raise Error, "Unknown decimal option '#{decimal.inspect}'"
+      end
+    end
+
+    # Convert an integer to number words
+    #
+    # @param [Integer] n
+    #
+    # @return [Array[String]]
+    #
+    # @api public
+    def convert_to_words(n)
+      words = []
+
+      SCALES.each_with_index do |scale, i|
+        mod = n % 1000
+
+        word = []
+        word << convert_hundreds(mod)
+        word << scale unless i.zero?
+
+        words.insert(0, word.join(SPACE))
+
+        n /= 1000
+
+        break if n.zero?
+      end
+
+      words
+    end
+
+    # Convert 3 digit number to equivalent word
+    #
+    # @return [String]
+    #
+    # @api private
+    def convert_hundreds(num)
+      word = []
+      hundreds = (num % 1000) / 100
+      tens = num % 100
+
+      if !hundreds.zero?
+        word << convert_tens(hundreds)
+        word << HUNDRED
+      end
+
+      if !tens.zero?
+        word << convert_tens(tens)
+      end
+
+      word.join(SPACE)
+    end
+
+    # Convert number in 0..99 range to equivalent word
+    #
+    # @return [String]
+    #
+    # @api private
+    def convert_tens(num)
+      word = []
+      tens = num % 100
+
+      if tens.to_s.size < 2 || tens <= 20
+        word << CARDINALS[tens]
+      else
+        word << CARDINALS[(tens / 10) * 10]
+        word << CARDINALS[tens % 10] unless (tens % 10).zero?
+      end
+
+      word.join(SPACE)
+    end
+  end # Numeral
+end # Strings

data/lib/strings/numeral/configuration.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Strings
+  class Numeral
+    class Configuration
+      # Initialize a configuration
+      #
+      # @api private
+      def initialize
+        @currency = :usd
+        @delimiter = ", "
+        @decimal = :fraction
+        @separator = nil
+        @trailing_zeros = false
+      end
+
+      def currency(value = (not_set = true))
+        if not_set
+          @currency
+        else
+          @currency = value
+        end
+      end
+
+      def delimiter(value = (not_set = true))
+        if not_set
+          @delimiter
+        else
+          @delimiter = value
+        end
+      end
+
+      def separator(value = (not_set = true))
+        if not_set
+          @separator
+        else
+          @separator = value
+        end
+      end
+
+      def decimal(value = (not_set = true))
+        if not_set
+          @decimal
+        else
+          @decimal = value
+        end
+      end
+
+      def trailing_zeros(value = (not_set = true))
+        if not_set
+          @trailing_zeros
+        else
+          @trailing_zeros = value
+        end
+      end
+    end # Configuration
+  end # Numeral
+end # Strings

data/lib/strings/numeral/extensions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Strings
+  class Numeral
+    module Extensions
+      Methods = Module.new do
+        def numeralize(**options)
+          Strings::Numeral.numeralize(self, **options)
+        end
+
+        def cardinalize(**options)
+          Strings::Numeral.cardinalize(self, **options)
+        end
+
+        def ordinalize(**options)
+          Strings::Numeral.ordinalize(self, **options)
+        end
+
+        def ordinalize_short
+          Strings::Numeral.ordinalize_short(self)
+        end
+
+        def monetize(**options)
+          Strings::Numeral.monetize(self, **options)
+        end
+
+        def romanize
+          Strings::Numeral.romanize(self)
+        end
+      end
+
+      refine String do
+        include Methods
+      end
+
+      refine Float do
+        include Methods
+      end
+
+      refine Integer do
+        include Methods
+      end
+    end # Extensions
+  end # Numeral
+end # Strings

data/lib/strings/numeral/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Strings
+  class Numeral
+    VERSION = "0.1.0"
+  end # Numeral
+end # Strings

data/strings-numeral.gemspec

@@ -0,0 +1,34 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "strings/numeral/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "strings-numeral"
+  spec.version       = Strings::Numeral::VERSION
+  spec.authors       = ["Piotr Murach"]
+  spec.email         = ["me@piotrmurach.com"]
+  spec.summary       = %q{Express numbers as word numerals}
+  spec.description   = %q{Express numbers as word numerals like cardinal, ordinal, roman and monetary}
+  spec.homepage      = "https://github.com/piotrmurach/strings-numeral"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+    spec.metadata["changelog_uri"] = "https://github.com/piotrmurach/strings-numeral/blob/master/CHANGELOG.md"
+    spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/strings-numeral"
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = "https://github.com/piotrmurach/strings-numeral"
+  end
+
+  spec.files         = Dir["lib/**/*.rb"]
+  spec.files        += Dir["tasks/*", "strings-numeral.gemspec"]
+  spec.files        += Dir["README.md", "CHANGELOG.md", "LICENSE.txt", "Rakefile"]
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.0.0"
+
+  spec.add_development_dependency "bundler", ">= 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/tasks/console.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+desc "Load gem inside irb console"
+task :console do
+  require "irb"
+  require "irb/completion"
+  require File.join(__FILE__, "../../lib/strings-numeral")
+  ARGV.clear
+  IRB.start
+end
+task c: %w[ console ]

data/tasks/coverage.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+desc "Measure code coverage"
+task :coverage do
+  begin
+    original, ENV["COVERAGE"] = ENV["COVERAGE"], "true"
+    Rake::Task["spec"].invoke
+  ensure
+    ENV["COVERAGE"] = original
+  end
+end

data/tasks/spec.rake

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+begin
+  require "rspec/core/rake_task"
+
+  desc "Run all specs"
+  RSpec::Core::RakeTask.new(:spec) do |task|
+    task.pattern = "spec/{unit,integration}{,/*/**}/*_spec.rb"
+  end
+
+  namespace :spec do
+    desc "Run unit specs"
+    RSpec::Core::RakeTask.new(:unit) do |task|
+      task.pattern = "spec/unit{,/*/**}/*_spec.rb"
+    end
+
+    desc "Run integration specs"
+    RSpec::Core::RakeTask.new(:integration) do |task|
+      task.pattern = "spec/integration{,/*/**}/*_spec.rb"
+    end
+
+    desc "Run performance specs"
+    RSpec::Core::RakeTask.new(:perf) do |task|
+      task.pattern = "spec/perf{,/*/**}/*_spec.rb"
+    end
+  end
+
+rescue LoadError
+  %w[spec spec:unit spec:integration].each do |name|
+    task name do
+      $stderr.puts "In order to run #{name}, do `gem install rspec`"
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: strings-numeral
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Piotr Murach
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-12-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Express numbers as word numerals like cardinal, ordinal, roman and monetary
+email:
+- me@piotrmurach.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/strings-numeral.rb
+- lib/strings/numeral.rb
+- lib/strings/numeral/configuration.rb
+- lib/strings/numeral/extensions.rb
+- lib/strings/numeral/version.rb
+- strings-numeral.gemspec
+- tasks/console.rake
+- tasks/coverage.rake
+- tasks/spec.rake
+homepage: https://github.com/piotrmurach/strings-numeral
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/piotrmurach/strings-numeral/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/strings-numeral
+  homepage_uri: https://github.com/piotrmurach/strings-numeral
+  source_code_uri: https://github.com/piotrmurach/strings-numeral
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.0.pre3
+signing_key: 
+specification_version: 4
+summary: Express numbers as word numerals
+test_files: []