core_ext 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 65bef674a3f30a7d453c6daf9c001da0ad8ce670
-  data.tar.gz: 4091487a2288aeeb53d9a65f16b64bd91e71962a
+  metadata.gz: 1bdf3f20c2a4605b931d22569286e4d4a2bc5b89
+  data.tar.gz: c27a153f427d418addb719755493eab242b85d95
 SHA512:
-  metadata.gz: c4eedaeea00537d6013ce8a4e4176b219bc20894776a27241c6781c611382f92753923d75604ca6d2d7bcb6748dce6d2580993aeceb763b209601d4e846bd95e
-  data.tar.gz: 8c7e8c31d381fcfa7511f98a5764fed0fe449bfc1b524cd3968c3766ff05f59751d5686b51f016ff79f76f9475fc56b10f9a12bcf4fd8e98c15c97e430854aad
+  metadata.gz: fe9e06e452543c0d39defe62ca3117d022987aedb45c7ee2c373a14a59413c20fa30104b31ad3c528e8c3b1056bccda89624c5bddf686dadd9ea45879bd919ab
+  data.tar.gz: f2f93d74095ddb305b276d5027fb18fd52361cff76ff1f806a66ecb78f990137be868aaa8e9625f6bb6f2e7535bd62090eaea17a31bc3f654827a53fae42126f

data/lib/core_ext.rb

@@ -1,4 +1,7 @@
+require "core_ext/version"
+require "core_ext/module/attribute_accessors"
+
 module CoreExt
+  cattr_accessor :test_order # :nodoc :
 end
 
-require "core_ext/version"

data/lib/core_ext/callbacks.rb

@@ -1,4 +1,5 @@
 require 'core_ext/concern'
+require 'core_ext/descendants_tracker'
 require 'core_ext/array/extract_options'
 require 'core_ext/class/attribute'
 require 'core_ext/kernel/reporting'
@@ -60,6 +61,10 @@ module CoreExt
   module Callbacks
     extend Concern
 
+    included do
+      extend CoreExt::DescendantsTracker
+    end
+
     CALLBACK_FILTER_TYPES = [:before, :after, :around]
 
     # If true, Active Record and Active Model callbacks returning +false+ will
@@ -551,8 +556,10 @@ module CoreExt
       # This is used internally to append, prepend and skip callbacks to the
       # CallbackChain.
       def __update_callbacks(name) #:nodoc:
-        chain = get_callbacks name
-        yield self, chain.dup
+        ([self] + CoreExt::DescendantsTracker.descendants(self)).reverse_each do |target|
+          chain = target.get_callbacks name
+          yield target, chain.dup
+        end
       end
 
       # Install a callback for the given event.
@@ -641,6 +648,12 @@ module CoreExt
       # Remove all set callbacks for the given event.
       def reset_callbacks(name)
         callbacks = get_callbacks name
+        CoreExt::DescendantsTracker.descendants(self).each do |target|
+          chain = target.get_callbacks(name).dup
+          callbacks.each { |c| chain.delete(c) }
+          target.set_callbacks name, chain
+        end
+
         set_callbacks name, callbacks.dup.clear
       end
 

data/lib/core_ext/descendants_tracker.rb

@@ -0,0 +1,50 @@
+module CoreExt
+  # This module provides an internal implementation to track descendants
+  # which is faster than iterating through ObjectSpace.
+  module DescendantsTracker
+    @@direct_descendants = {}
+
+    class << self
+      def direct_descendants(klass)
+        @@direct_descendants[klass] || []
+      end
+
+      def descendants(klass)
+        arr = []
+        accumulate_descendants(klass, arr)
+        arr
+      end
+
+      def clear
+        @@direct_descendants.clear
+      end
+
+      # This is the only method that is not thread safe, but is only ever called
+      # during the eager loading phase.
+      def store_inherited(klass, descendant)
+        (@@direct_descendants[klass] ||= []) << descendant
+      end
+
+      private
+      def accumulate_descendants(klass, acc)
+        if direct_descendants = @@direct_descendants[klass]
+          acc.concat(direct_descendants)
+          direct_descendants.each { |direct_descendant| accumulate_descendants(direct_descendant, acc) }
+        end
+      end
+    end
+
+    def inherited(base)
+      DescendantsTracker.store_inherited(self, base)
+      super
+    end
+
+    def direct_descendants
+      DescendantsTracker.direct_descendants(self)
+    end
+
+    def descendants
+      DescendantsTracker.descendants(self)
+    end
+  end
+end

data/lib/core_ext/gzip.rb

@@ -0,0 +1,36 @@
+require 'zlib'
+require 'stringio'
+
+module CoreExt
+  # A convenient wrapper for the zlib standard library that allows
+  # compression/decompression of strings with gzip.
+  #
+  #   gzip = CoreExt::Gzip.compress('compress me!')
+  #   # => "\x1F\x8B\b\x00o\x8D\xCDO\x00\x03K\xCE\xCF-(J-.V\xC8MU\x04\x00R>n\x83\f\x00\x00\x00"
+  #
+  #   CoreExt::Gzip.decompress(gzip)
+  #   # => "compress me!"
+  module Gzip
+    class Stream < StringIO
+      def initialize(*)
+        super
+        set_encoding "BINARY"
+      end
+      def close; rewind; end
+    end
+
+    # Decompresses a gzipped string.
+    def self.decompress(source)
+      Zlib::GzipReader.new(StringIO.new(source)).read
+    end
+
+    # Compresses a string using gzip.
+    def self.compress(source, level=Zlib::DEFAULT_COMPRESSION, strategy=Zlib::DEFAULT_STRATEGY)
+      output = Stream.new
+      gz = Zlib::GzipWriter.new(output, level, strategy)
+      gz.write(source)
+      gz.close
+      output.string
+    end
+  end
+end

data/lib/core_ext/i18n.rb

@@ -0,0 +1,11 @@
+require 'core_ext/hash/deep_merge'
+require 'core_ext/hash/except'
+require 'core_ext/hash/slice'
+begin
+  require 'i18n'
+rescue LoadError => e
+  $stderr.puts "The i18n gem is not available. Please add it to your Gemfile and run bundle install"
+  raise e
+end
+
+I18n.load_path << "#{File.dirname(__FILE__)}/locale/en.yml"

data/lib/core_ext/locale/en.yml

@@ -0,0 +1,135 @@
+en:
+  date:
+    formats:
+      # Use the strftime parameters for formats.
+      # When no format has been given, it uses default.
+      # You can provide other formats here if you like!
+      default: "%Y-%m-%d"
+      short: "%b %d"
+      long: "%B %d, %Y"
+
+    day_names: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
+    abbr_day_names: [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
+
+    # Don't forget the nil at the beginning; there's no such thing as a 0th month
+    month_names: [~, January, February, March, April, May, June, July, August, September, October, November, December]
+    abbr_month_names: [~, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
+    # Used in date_select and datetime_select.
+    order:
+      - year
+      - month
+      - day
+
+  time:
+    formats:
+      default: "%a, %d %b %Y %H:%M:%S %z"
+      short: "%d %b %H:%M"
+      long: "%B %d, %Y %H:%M"
+    am: "am"
+    pm: "pm"
+
+# Used in array.to_sentence.
+  support:
+    array:
+      words_connector: ", "
+      two_words_connector: " and "
+      last_word_connector: ", and "
+  number:
+    # Used in NumberHelper.number_to_delimited()
+    # These are also the defaults for 'currency', 'percentage', 'precision', and 'human'
+    format:
+      # Sets the separator between the units, for more precision (e.g. 1.0 / 2.0 == 0.5)
+      separator: "."
+      # Delimits thousands (e.g. 1,000,000 is a million) (always in groups of three)
+      delimiter: ","
+      # Number of decimals, behind the separator (the number 1 with a precision of 2 gives: 1.00)
+      precision: 3
+      # If set to true, precision will mean the number of significant digits instead
+      # of the number of decimal digits (1234 with precision 2 becomes 1200, 1.23543 becomes 1.2)
+      significant: false
+      # If set, the zeros after the decimal separator will always be stripped (eg.: 1.200 will be 1.2)
+      strip_insignificant_zeros: false
+
+    # Used in NumberHelper.number_to_currency()
+    currency:
+      format:
+        # Where is the currency sign? %u is the currency unit, %n the number (default: $5.00)
+        format: "%u%n"
+        unit: "$"
+        # These five are to override number.format and are optional
+        separator: "."
+        delimiter: ","
+        precision: 2
+        significant: false
+        strip_insignificant_zeros: false
+
+    # Used in NumberHelper.number_to_percentage()
+    percentage:
+      format:
+        # These five are to override number.format and are optional
+        # separator:
+        delimiter: ""
+        # precision:
+        # significant: false
+        # strip_insignificant_zeros: false
+        format: "%n%"
+
+    # Used in NumberHelper.number_to_rounded()
+    precision:
+      format:
+        # These five are to override number.format and are optional
+        # separator:
+        delimiter: ""
+        # precision:
+        # significant: false
+        # strip_insignificant_zeros: false
+
+    # Used in NumberHelper.number_to_human_size() and NumberHelper.number_to_human()
+    human:
+      format:
+        # These five are to override number.format and are optional
+        # separator:
+        delimiter: ""
+        precision: 3
+        significant: true
+        strip_insignificant_zeros: true
+      # Used in number_to_human_size()
+      storage_units:
+        # Storage units output formatting.
+        # %u is the storage unit, %n is the number (default: 2 MB)
+        format: "%n %u"
+        units:
+          byte:
+            one:   "Byte"
+            other: "Bytes"
+          kb: "KB"
+          mb: "MB"
+          gb: "GB"
+          tb: "TB"
+          pb: "PB"
+          eb: "EB"
+      # Used in NumberHelper.number_to_human()
+      decimal_units:
+        format: "%n %u"
+        # Decimal units output formatting
+        # By default we will only quantify some of the exponents
+        # but the commented ones might be defined or overridden
+        # by the user.
+        units:
+          # femto: Quadrillionth
+          # pico: Trillionth
+          # nano: Billionth
+          # micro: Millionth
+          # mili: Thousandth
+          # centi: Hundredth
+          # deci: Tenth
+          unit: ""
+          # ten:
+          #   one: Ten
+          #   other: Tens
+          # hundred: Hundred
+          thousand: Thousand
+          million: Million
+          billion: Billion
+          trillion: Trillion
+          quadrillion: Quadrillion

data/lib/core_ext/number_helper.rb

@@ -0,0 +1,358 @@
+module CoreExt
+  module NumberHelper
+
+    require "core_ext/number_helper/number_converter"
+    require "core_ext/number_helper/number_to_rounded_converter"
+    require "core_ext/number_helper/number_to_delimited_converter"
+    require "core_ext/number_helper/number_to_human_converter"
+    require "core_ext/number_helper/number_to_human_size_converter"
+    require "core_ext/number_helper/number_to_phone_converter"
+    require "core_ext/number_helper/number_to_currency_converter"
+    require "core_ext/number_helper/number_to_percentage_converter"
+
+    extend self
+
+    # Formats a +number+ into a US phone number (e.g., (555)
+    # 123-9876). You can customize the format in the +options+ hash.
+    #
+    # ==== Options
+    #
+    # * <tt>:area_code</tt> - Adds parentheses around the area code.
+    # * <tt>:delimiter</tt> - Specifies the delimiter to use
+    #   (defaults to "-").
+    # * <tt>:extension</tt> - Specifies an extension to add to the
+    #   end of the generated number.
+    # * <tt>:country_code</tt> - Sets the country code for the phone
+    #   number.
+    # ==== Examples
+    #
+    #   number_to_phone(5551234)                                     # => 555-1234
+    #   number_to_phone('5551234')                                   # => 555-1234
+    #   number_to_phone(1235551234)                                  # => 123-555-1234
+    #   number_to_phone(1235551234, area_code: true)                 # => (123) 555-1234
+    #   number_to_phone(1235551234, delimiter: ' ')                  # => 123 555 1234
+    #   number_to_phone(1235551234, area_code: true, extension: 555) # => (123) 555-1234 x 555
+    #   number_to_phone(1235551234, country_code: 1)                 # => +1-123-555-1234
+    #   number_to_phone('123a456')                                   # => 123a456
+    #
+    #   number_to_phone(1235551234, country_code: 1, extension: 1343, delimiter: '.')
+    #   # => +1.123.555.1234 x 1343
+    def number_to_phone(number, options = {})
+      NumberToPhoneConverter.convert(number, options)
+    end
+
+    # Formats a +number+ into a currency string (e.g., $13.65). You
+    # can customize the format in the +options+ hash.
+    #
+    # The currency unit and number formatting of the current locale will be used
+    # unless otherwise specified in the provided options. No currency conversion
+    # is performed. If the user is given a way to change their locale, they will
+    # also be able to change the relative value of the currency displayed with
+    # this helper. If your application will ever support multiple locales, you
+    # may want to specify a constant <tt>:locale</tt> option or consider
+    # using a library capable of currency conversion.
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:precision</tt> - Sets the level of precision (defaults
+    #   to 2).
+    # * <tt>:unit</tt> - Sets the denomination of the currency
+    #   (defaults to "$").
+    # * <tt>:separator</tt> - Sets the separator between the units
+    #   (defaults to ".").
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to ",").
+    # * <tt>:format</tt> - Sets the format for non-negative numbers
+    #   (defaults to "%u%n").  Fields are <tt>%u</tt> for the
+    #   currency, and <tt>%n</tt> for the number.
+    # * <tt>:negative_format</tt> - Sets the format for negative
+    #   numbers (defaults to prepending an hyphen to the formatted
+    #   number given by <tt>:format</tt>).  Accepts the same fields
+    #   than <tt>:format</tt>, except <tt>%n</tt> is here the
+    #   absolute value of the number.
+    #
+    # ==== Examples
+    #
+    #   number_to_currency(1234567890.50)                # => $1,234,567,890.50
+    #   number_to_currency(1234567890.506)               # => $1,234,567,890.51
+    #   number_to_currency(1234567890.506, precision: 3) # => $1,234,567,890.506
+    #   number_to_currency(1234567890.506, locale: :fr)  # => 1 234 567 890,51 €
+    #   number_to_currency('123a456')                    # => $123a456
+    #
+    #   number_to_currency(-1234567890.50, negative_format: '(%u%n)')
+    #   # => ($1,234,567,890.50)
+    #   number_to_currency(1234567890.50, unit: '&pound;', separator: ',', delimiter: '')
+    #   # => &pound;1234567890,50
+    #   number_to_currency(1234567890.50, unit: '&pound;', separator: ',', delimiter: '', format: '%n %u')
+    #   # => 1234567890,50 &pound;
+    def number_to_currency(number, options = {})
+      NumberToCurrencyConverter.convert(number, options)
+    end
+
+    # Formats a +number+ as a percentage string (e.g., 65%). You can
+    # customize the format in the +options+ hash.
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:precision</tt> - Sets the precision of the number
+    #   (defaults to 3). Keeps the number's precision if nil.
+    # * <tt>:significant</tt> - If +true+, precision will be the number
+    #   of significant_digits. If +false+, the number of fractional
+    #   digits (defaults to +false+).
+    # * <tt>:separator</tt> - Sets the separator between the
+    #   fractional and integer digits (defaults to ".").
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to "").
+    # * <tt>:strip_insignificant_zeros</tt> - If +true+ removes
+    #   insignificant zeros after the decimal separator (defaults to
+    #   +false+).
+    # * <tt>:format</tt> - Specifies the format of the percentage
+    #   string The number field is <tt>%n</tt> (defaults to "%n%").
+    #
+    # ==== Examples
+    #
+    #   number_to_percentage(100)                                  # => 100.000%
+    #   number_to_percentage('98')                                 # => 98.000%
+    #   number_to_percentage(100, precision: 0)                    # => 100%
+    #   number_to_percentage(1000, delimiter: '.', separator: ',') # => 1.000,000%
+    #   number_to_percentage(302.24398923423, precision: 5)        # => 302.24399%
+    #   number_to_percentage(1000, locale: :fr)                    # => 1000,000%
+    #   number_to_percentage(1000, precision: nil)                 # => 1000%
+    #   number_to_percentage('98a')                                # => 98a%
+    #   number_to_percentage(100, format: '%n  %')                 # => 100.000  %
+    def number_to_percentage(number, options = {})
+      NumberToPercentageConverter.convert(number, options)
+    end
+
+    # Formats a +number+ with grouped thousands using +delimiter+
+    # (e.g., 12,324). You can customize the format in the +options+
+    # hash.
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to ",").
+    # * <tt>:separator</tt> - Sets the separator between the
+    #   fractional and integer digits (defaults to ".").
+    # * <tt>:delimiter_pattern</tt> - Sets a custom regular expression used for
+    #   deriving the placement of delimiter. Helpful when using currency formats
+    #   like INR.
+    #
+    # ==== Examples
+    #
+    #   number_to_delimited(12345678)                    # => 12,345,678
+    #   number_to_delimited('123456')                    # => 123,456
+    #   number_to_delimited(12345678.05)                 # => 12,345,678.05
+    #   number_to_delimited(12345678, delimiter: '.')    # => 12.345.678
+    #   number_to_delimited(12345678, delimiter: ',')    # => 12,345,678
+    #   number_to_delimited(12345678.05, separator: ' ') # => 12,345,678 05
+    #   number_to_delimited(12345678.05, locale: :fr)    # => 12 345 678,05
+    #   number_to_delimited('112a')                      # => 112a
+    #   number_to_delimited(98765432.98, delimiter: ' ', separator: ',')
+    #                                                    # => 98 765 432,98
+    #   number_to_delimited("123456.78",
+    #     delimiter_pattern: /(\d+?)(?=(\d\d)+(\d)(?!\d))/)
+    #                                                    # => 1,23,456.78
+    def number_to_delimited(number, options = {})
+      NumberToDelimitedConverter.convert(number, options)
+    end
+
+    # Formats a +number+ with the specified level of
+    # <tt>:precision</tt> (e.g., 112.32 has a precision of 2 if
+    # +:significant+ is +false+, and 5 if +:significant+ is +true+).
+    # You can customize the format in the +options+ hash.
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:precision</tt> - Sets the precision of the number
+    #   (defaults to 3). Keeps the number's precision if nil.
+    # * <tt>:significant</tt> - If +true+, precision will be the number
+    #   of significant_digits. If +false+, the number of fractional
+    #   digits (defaults to +false+).
+    # * <tt>:separator</tt> - Sets the separator between the
+    #   fractional and integer digits (defaults to ".").
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to "").
+    # * <tt>:strip_insignificant_zeros</tt> - If +true+ removes
+    #   insignificant zeros after the decimal separator (defaults to
+    #   +false+).
+    #
+    # ==== Examples
+    #
+    #   number_to_rounded(111.2345)                                  # => 111.235
+    #   number_to_rounded(111.2345, precision: 2)                    # => 111.23
+    #   number_to_rounded(13, precision: 5)                          # => 13.00000
+    #   number_to_rounded(389.32314, precision: 0)                   # => 389
+    #   number_to_rounded(111.2345, significant: true)               # => 111
+    #   number_to_rounded(111.2345, precision: 1, significant: true) # => 100
+    #   number_to_rounded(13, precision: 5, significant: true)       # => 13.000
+    #   number_to_rounded(13, precision: nil)                        # => 13
+    #   number_to_rounded(111.234, locale: :fr)                      # => 111,234
+    #
+    #   number_to_rounded(13, precision: 5, significant: true, strip_insignificant_zeros: true)
+    #   # => 13
+    #
+    #   number_to_rounded(389.32314, precision: 4, significant: true) # => 389.3
+    #   number_to_rounded(1111.2345, precision: 2, separator: ',', delimiter: '.')
+    #   # => 1.111,23
+    def number_to_rounded(number, options = {})
+      NumberToRoundedConverter.convert(number, options)
+    end
+
+    # Formats the bytes in +number+ into a more understandable
+    # representation (e.g., giving it 1500 yields 1.5 KB). This
+    # method is useful for reporting file sizes to users. You can
+    # customize the format in the +options+ hash.
+    #
+    # See <tt>number_to_human</tt> if you want to pretty-print a
+    # generic number.
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:precision</tt> - Sets the precision of the number
+    #   (defaults to 3).
+    # * <tt>:significant</tt> - If +true+, precision will be the number
+    #   of significant_digits. If +false+, the number of fractional
+    #   digits (defaults to +true+)
+    # * <tt>:separator</tt> - Sets the separator between the
+    #   fractional and integer digits (defaults to ".").
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to "").
+    # * <tt>:strip_insignificant_zeros</tt> - If +true+ removes
+    #   insignificant zeros after the decimal separator (defaults to
+    #   +true+)
+    #
+    # ==== Examples
+    #
+    #   number_to_human_size(123)                                    # => 123 Bytes
+    #   number_to_human_size(1234)                                   # => 1.21 KB
+    #   number_to_human_size(12345)                                  # => 12.1 KB
+    #   number_to_human_size(1234567)                                # => 1.18 MB
+    #   number_to_human_size(1234567890)                             # => 1.15 GB
+    #   number_to_human_size(1234567890123)                          # => 1.12 TB
+    #   number_to_human_size(1234567890123456)                       # => 1.1 PB
+    #   number_to_human_size(1234567890123456789)                    # => 1.07 EB
+    #   number_to_human_size(1234567, precision: 2)                  # => 1.2 MB
+    #   number_to_human_size(483989, precision: 2)                   # => 470 KB
+    #   number_to_human_size(1234567, precision: 2, separator: ',')  # => 1,2 MB
+    #   number_to_human_size(1234567890123, precision: 5)            # => "1.1228 TB"
+    #   number_to_human_size(524288000, precision: 5)                # => "500 MB"
+    def number_to_human_size(number, options = {})
+      NumberToHumanSizeConverter.convert(number, options)
+    end
+
+    # Pretty prints (formats and approximates) a number in a way it
+    # is more readable by humans (eg.: 1200000000 becomes "1.2
+    # Billion"). This is useful for numbers that can get very large
+    # (and too hard to read).
+    #
+    # See <tt>number_to_human_size</tt> if you want to print a file
+    # size.
+    #
+    # You can also define your own unit-quantifier names if you want
+    # to use other decimal units (eg.: 1500 becomes "1.5
+    # kilometers", 0.150 becomes "150 milliliters", etc). You may
+    # define a wide range of unit quantifiers, even fractional ones
+    # (centi, deci, mili, etc).
+    #
+    # ==== Options
+    #
+    # * <tt>:locale</tt> - Sets the locale to be used for formatting
+    #   (defaults to current locale).
+    # * <tt>:precision</tt> - Sets the precision of the number
+    #   (defaults to 3).
+    # * <tt>:significant</tt> - If +true+, precision will be the number
+    #   of significant_digits. If +false+, the number of fractional
+    #   digits (defaults to +true+)
+    # * <tt>:separator</tt> - Sets the separator between the
+    #   fractional and integer digits (defaults to ".").
+    # * <tt>:delimiter</tt> - Sets the thousands delimiter (defaults
+    #   to "").
+    # * <tt>:strip_insignificant_zeros</tt> - If +true+ removes
+    #   insignificant zeros after the decimal separator (defaults to
+    #   +true+)
+    # * <tt>:units</tt> - A Hash of unit quantifier names. Or a
+    #   string containing an i18n scope where to find this hash. It
+    #   might have the following keys:
+    #   * *integers*: <tt>:unit</tt>, <tt>:ten</tt>,
+    #     <tt>:hundred</tt>, <tt>:thousand</tt>, <tt>:million</tt>,
+    #     <tt>:billion</tt>, <tt>:trillion</tt>,
+    #     <tt>:quadrillion</tt>
+    #   * *fractionals*: <tt>:deci</tt>, <tt>:centi</tt>,
+    #     <tt>:mili</tt>, <tt>:micro</tt>, <tt>:nano</tt>,
+    #     <tt>:pico</tt>, <tt>:femto</tt>
+    # * <tt>:format</tt> - Sets the format of the output string
+    #   (defaults to "%n %u"). The field types are:
+    #   * %u - The quantifier (ex.: 'thousand')
+    #   * %n - The number
+    #
+    # ==== Examples
+    #
+    #   number_to_human(123)                         # => "123"
+    #   number_to_human(1234)                        # => "1.23 Thousand"
+    #   number_to_human(12345)                       # => "12.3 Thousand"
+    #   number_to_human(1234567)                     # => "1.23 Million"
+    #   number_to_human(1234567890)                  # => "1.23 Billion"
+    #   number_to_human(1234567890123)               # => "1.23 Trillion"
+    #   number_to_human(1234567890123456)            # => "1.23 Quadrillion"
+    #   number_to_human(1234567890123456789)         # => "1230 Quadrillion"
+    #   number_to_human(489939, precision: 2)        # => "490 Thousand"
+    #   number_to_human(489939, precision: 4)        # => "489.9 Thousand"
+    #   number_to_human(1234567, precision: 4,
+    #                            significant: false) # => "1.2346 Million"
+    #   number_to_human(1234567, precision: 1,
+    #                            separator: ',',
+    #                            significant: false) # => "1,2 Million"
+    #
+    #   number_to_human(500000000, precision: 5)           # => "500 Million"
+    #   number_to_human(12345012345, significant: false)   # => "12.345 Billion"
+    #
+    # Non-significant zeros after the decimal separator are stripped
+    # out by default (set <tt>:strip_insignificant_zeros</tt> to
+    # +false+ to change that):
+    #
+    # number_to_human(12.00001)                                       # => "12"
+    # number_to_human(12.00001, strip_insignificant_zeros: false)     # => "12.0"
+    #
+    # ==== Custom Unit Quantifiers
+    #
+    # You can also use your own custom unit quantifiers:
+    #  number_to_human(500000, units: { unit: 'ml', thousand: 'lt' })  # => "500 lt"
+    #
+    # If in your I18n locale you have:
+    #
+    #   distance:
+    #     centi:
+    #       one: "centimeter"
+    #       other: "centimeters"
+    #     unit:
+    #       one: "meter"
+    #       other: "meters"
+    #     thousand:
+    #       one: "kilometer"
+    #       other: "kilometers"
+    #     billion: "gazillion-distance"
+    #
+    # Then you could do:
+    #
+    #   number_to_human(543934, units: :distance)            # => "544 kilometers"
+    #   number_to_human(54393498, units: :distance)          # => "54400 kilometers"
+    #   number_to_human(54393498000, units: :distance)       # => "54.4 gazillion-distance"
+    #   number_to_human(343, units: :distance, precision: 1) # => "300 meters"
+    #   number_to_human(1, units: :distance)                 # => "1 meter"
+    #   number_to_human(0.34, units: :distance)              # => "34 centimeters"
+    def number_to_human(number, options = {})
+      NumberToHumanConverter.convert(number, options)
+    end
+  end
+end