ree_lib 1.0.0

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_human.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToHuman
+  include Ree::FnDSL
+
+  fn :number_to_human do
+    link :round_helper, import: -> { ROUND_MODES }
+    link :number_to_rounded
+    link :t, from: :ree_i18n
+    link :number_to_delimited
+    link :slice, from: :ree_hash
+    link 'ree_number/functions/constants', -> { DECIMAL_UNITS & INVERTED_DECIMAL_UNITS }
+  end
+
+  DEFAULTS = {
+    units: "decimal_units",
+    locale: :en,
+    format: "%n %u",
+    precision: 3,
+    significant: true,
+    strip_insignificant_zeros: true,
+    separator: ".",
+    delimiter: "",
+    round_mode: :default
+  }.freeze
+
+  doc(<<~DOC)
+    Pretty prints (formats and approximates) a number in a way it
+    is more readable by humans (e.g.: 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 (e.g.: 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>:round_mode</tt> - Determine how rounding is performed
+      (defaults to :default. See BigDecimal::mode)
+    * <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"
+  DOC
+
+  contract(
+    Or[Integer, Float, String],
+    Ksplat[
+      units?: String,
+      locale?: Symbol,
+      format?: String,
+      precision?: Integer,
+      significant?: Bool,
+      strip_insignificant_zeros?: Bool,
+      separator?: String,
+      delimiter?: String,
+      round_mode?: Or[*ROUND_MODES]
+    ] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+
+    number = round_helper(
+      number,
+      **slice(options, [:precision, :significant, :round_mode])
+    )
+
+    number = Float(number)
+
+    exponent = calculate_exponent(
+      number, options[:locale], options[:units]
+    )
+
+    number = number / (10**exponent)
+
+    rounded_number = number_to_rounded(
+      number,
+      **slice(
+        options,
+        [:precision, :significant, :strip_insignificant_zeros, :round_mode]
+      )
+    )
+
+    unit = determine_unit(
+      exponent, options[:units], options[:locale]
+    )
+
+    result_number = options[:format]
+      .gsub("%n", rounded_number)
+      .gsub("%u", unit)
+      .strip
+
+    number_to_delimited(
+      result_number,
+      **slice(options, [:separator, :delimiter])
+    )
+  end
+
+  private
+
+  def determine_unit(exponent, units, locale)
+    exp = DECIMAL_UNITS[exponent]
+    case units
+    when Hash
+      units[exp] || ""
+    when String, Symbol
+      t("human.#{units}.#{exp}", locale: locale, default_by_locale: :en)
+    else
+      t("human.decimal_units.#{exp}", count: number.to_i, default_by_locale: :en)
+    end
+  end
+
+  def calculate_exponent(number, locale, units)
+    exponent = number != 0 ? Math.log10(number.abs).floor : 0
+
+    unit_exponents(units, locale).find { |e| exponent >= e } || 0
+  end
+
+  def unit_exponents(units, locale)
+    case units
+    when Hash
+      units
+    when String, Symbol
+      t("human.#{units}", locale: locale, raise: true, default_by_locale: :en)
+    else
+      raise ArgumentError, ":units must be a Hash or String translation scope."
+    end.keys.map { |e_name| INVERTED_DECIMAL_UNITS[e_name] }.sort_by(&:-@)
+  end
+end

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_human_size.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToHumanSize
+  include Ree::FnDSL
+
+  fn :number_to_human_size do
+    link :number_to_rounded, import: -> { ROUND_MODES }
+    link :slice, from: :ree_hash
+    link :t, from: :ree_i18n
+    link :number_to_delimited
+    link 'ree_number/functions/constants', -> { STORAGE_UNITS }
+  end
+
+  DEFAULTS = {
+    locale: :en,
+    format: "%n %u",
+    precision: 3,
+    significant: true,
+    strip_insignificant_zeros: true,
+    separator: ".",
+    delimiter: "",
+    round_mode: :default
+  }.freeze
+
+  BASE = 1024
+
+  doc(<<~DOC)
+    Formats the bytes in +number+ into a more understandable
+    representation (e.g., giving it 1500 yields 1.46 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>:round_mode</tt> - Determine how rounding is performed
+      (defaults to :default. See BigDecimal::mode)
+    * <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(483989, precision: 2, round_mode: :up)
+      # => "480 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"
+  DOC
+
+  contract(
+    Or[Integer, Float, String],
+    Ksplat[
+      locale?: Symbol,
+      precision?: Integer,
+      significant?: Bool,
+      strip_insignificant_zeros?: Bool,
+      separator?: String,
+      delimiter?: String,
+      round_mode?: Or[*ROUND_MODES]
+    ] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+
+    number = Float(number)
+
+    if smaller_than_base?(number)
+      number_to_format = number.to_i.to_s
+    else
+      human_size = number / (BASE**exponent(number))
+      number_to_format = number_to_rounded(
+        human_size,
+        **slice(
+          options,
+          [:precision, :significant, :strip_insignificant_zeros, :round_mode]
+        )
+      )
+    end
+
+    storage_unit_key = storage_unit_key(number)
+
+    unit = unit(options[:locale], storage_unit_key, number)
+    result_number = options[:format]
+      .gsub("%n", number_to_format)
+      .gsub("%u", unit)
+
+    number_to_delimited(
+      result_number,
+      **slice(options, [:separator, :delimiter])
+    )
+  end
+
+  private
+
+  def unit(locale, storage_unit_key, number)
+    t(
+      storage_unit_key,
+      locale: locale,
+      count: number.to_i,
+      raise: true,
+      default_by_locale: :en
+    )
+  end
+
+  def storage_unit_key(number)
+    key_end = smaller_than_base?(number) ? "byte" : STORAGE_UNITS[exponent(number)]
+    "human.sizes.#{key_end}"
+  end
+
+  def exponent(number)
+    max = STORAGE_UNITS.size - 1
+    exp = (Math.log(number) / Math.log(BASE)).to_i
+    exp = max if exp > max
+    exp
+  end
+
+  def smaller_than_base?(number)
+    number.to_i < BASE
+  end
+end

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_ordinalized.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToOrdinalized
+  include Ree::FnDSL
+
+  fn :number_to_ordinalized do
+    link :t, from: :ree_i18n
+  end
+
+  DEFAULTS = {
+    locale: :en
+  }
+
+  doc(<<~DOC)
+    Turns a number into an ordinal string used to denote the position in an
+    ordered sequence such as 1st, 2nd, 3rd, 4th.
+
+      ordinalize(1)     # => "1st"
+      ordinalize(2)     # => "2nd"
+      ordinalize(1002)  # => "1002nd"
+      ordinalize(1003)  # => "1003rd"
+      ordinalize(-11)   # => "-11th"
+      ordinalize(-1021) # => "-1021st"
+  DOC
+
+  contract(
+    Integer,
+    Ksplat[locale?: Symbol] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+    ordinalize(number, options[:locale])
+  end
+
+  private
+
+  # Returns the suffix that should be added to a number to denote the position
+  # in an ordered sequence such as 1st, 2nd, 3rd, 4th.
+  #
+  #   ordinal(1)     # => "st"
+  #   ordinal(2)     # => "nd"
+  #   ordinal(1002)  # => "nd"
+  #   ordinal(1003)  # => "rd"
+  #   ordinal(-11)   # => "th"
+  #   ordinal(-1021) # => "st"
+  def ordinal(number, locale)
+    number = number.abs
+    number_key = number % 100
+
+    if number_key > 13
+      number_key %= 10
+    end
+
+    t("human.ordinals.#{number_key}", locale: locale, default_by_locale: :en)
+  end
+
+  def ordinalize(number, locale)
+    number.to_s + ordinal(number, locale)
+  end
+end

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_percentage.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToPercentage
+  include Ree::FnDSL
+
+  fn :number_to_percentage do
+    link :number_to_rounded, import: -> { ROUND_MODES }
+    link :slice, from: :ree_hash
+  end
+
+  DEFAULTS = {
+    format: "%n%",
+    precision: 3,
+    significant: false,
+    strip_insignificant_zeros: false,
+    delimiter: "",
+    round_mode: :default
+  }.freeze
+
+  doc(<<~DOC)
+    Converts Integer, String or Float to a String with percentage at the end.
+    The +opts+ parameter takes a hash of any of these keys:
+        <tt>:format</tt>, <tt>:precision</tt>, 
+        <tt>:significant</tt>, <tt>:strip_insignificant_zeros</tt>, <tt>:delimiter</tt>,
+        <tt>:round_mode</tt>
+      number_to_percentage(100)                                                      # => "100.000%"
+      number_to_percentage(123.400, precision: 3, strip_insignificant_zeros: true)   # => "123.4%"
+      number_to_percentage.("-0.13", format_percentage: " %", precision: 2)          # => "-0.13 %"
+  DOC
+
+  contract(
+    Or[Integer, String, Float], 
+    Ksplat[
+      format?: String, 
+      precision?: Integer,
+      significant?: Bool,
+      strip_insignificant_zeros?: Bool,
+      delimiter?: String,
+      round_mode?: Or[*ROUND_MODES]
+    ] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+
+    rounded_number = number_to_rounded(
+      number,
+      **slice(
+        options,
+        [:precision, :significant, :strip_insignificant_zeros, :round_mode]
+      )
+    )
+
+    options[:format].gsub("%n", rounded_number)
+  end
+end

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_phone.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToPhone
+  include Ree::FnDSL
+
+  fn :number_to_phone
+
+  DEFAULT_PHONE_PATTERN = /(\d{0,3})(\d{3})(\d{4})$/
+  DEFAULT_AREA_PHONE_PATTERN = /(\d{1,3})(\d{3})(\d{4}$)/
+
+  DEFAULTS = {
+    delimiter: "-"
+  }.freeze
+
+  doc(<<~DOC)
+    Converts Integer to a formatted string (phone number format).
+    Country_code, delimiter, area_code, extension are optional.
+  
+    number_to_phone(5551234)                                     # => "555-1234"
+    number_to_phone(8005551212)                                  # => "800-555-1212"
+    number_to_phone(8005551212, area_code: true)                 # => "(800) 555-1212"
+    number_to_phone(8005551212, delimiter: " ")                  # => "800 555 1212"
+    number_to_phone(8005551212, country_code: 7)                 # => "+7-800-555-1212"
+    number_to_phone(8005551212, country_code: 7, extension: 123) # => "+7-800-555-1212 x 123"
+  DOC
+  
+  contract(
+    Integer, 
+    Ksplat[
+      country_code?: Integer,
+      delimiter?: String,
+      area_code?: Bool,
+      pattern?: Regexp,
+      extension?: Integer
+    ] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+    str = country_code(options[:country_code], options[:delimiter]).dup
+
+    str << convert_to_phone_number(
+      number.to_s.strip,
+      options[:delimiter],
+      options[:area_code],
+      options[:pattern]
+    )
+
+    str << phone_extension(options[:extension]) if options[:extension]
+    str
+  end
+
+  private 
+
+  def country_code(country_code, delimiter)
+    country_code ? "+#{country_code}#{delimiter}" : ""
+  end
+
+  def convert_to_phone_number(phone, delimiter, area_code, pattern)
+    if area_code
+      convert_with_area_code(phone, delimiter, pattern)
+    else
+      convert_without_area_code(phone, delimiter, pattern)      
+    end
+  end
+
+  def convert_without_area_code(phone, delimiter, pattern)
+    converted_phone = phone.gsub(
+      pattern || DEFAULT_PHONE_PATTERN,
+      "\\1#{delimiter}\\2#{delimiter}\\3"
+    )
+
+    delimiter && converted_phone.start_with?(delimiter) ? converted_phone[1..-1] : converted_phone
+  end
+
+  def convert_with_area_code(phone, delimiter, pattern)
+    phone.gsub(
+      pattern || DEFAULT_AREA_PHONE_PATTERN,
+      "(\\1) \\2#{delimiter}\\3"
+    )
+  end
+
+  def phone_extension(extension)
+    " x #{extension}"
+  end
+end

data/lib/ree_lib/packages/ree_number/package/ree_number/functions/number_to_rounded.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+class ReeNumber::NumberToRounded
+  include Ree::FnDSL
+
+  fn :number_to_rounded do
+    link :number_to_delimited
+    link :digit_count
+    link :round_helper, import: -> { ROUND_MODES }
+    link :slice, from: :ree_hash
+  end
+
+  DEFAULTS = {
+    precision: 3,
+    significant: false,
+    strip_insignificant_zeros: false,
+    delimiter: "",
+    round_mode: :default
+  }.freeze
+
+  doc(<<~DOC)
+    Rounds Integer(Float, Rational, String) and converts to a String.
+
+    The +options+ parameter takes a hash of any of these keys: 
+      <tt>:precision</tt>, <tt>:significant</tt>, <tt>:strip_insignificant_zeros</tt>.
+
+    Presicion is 3 by default.
+      number_to_rounded(111.2346)                                # => "111.235"
+      number_to_rounded("111.2346")                              # => "111.235"
+      number_to_rounded("111.2346", precision: 20)               # => "111.23460000000000000000"
+      number_to_rounded(Rational(1112346, 10000)                 # => "111.2346"
+      number_to_rounded(123987, precision: 3, significant: true) # => "124000"
+
+      number_to_rounded(
+        5.3929, 
+        precision: 10, 
+        significant: true, 
+        strip_insignificant_zeros: true
+      )                                                          # => "5.3929"
+  DOC
+  
+  contract(
+    Or[Integer, Float, Rational, String], 
+    Ksplat[
+      precision?: Integer,
+      significant?: Bool,
+      strip_insignificant_zeros?: Bool,
+      round_mode?: Or[*ROUND_MODES]
+    ] => String
+  )
+  def call(number, **opts)
+    options = DEFAULTS.merge(opts)
+
+    rounded_number = round_helper(
+      number, 
+      **slice(
+        options, 
+        [:precision, :significant, :round_mode]
+      )
+    )
+
+    if precision = options[:precision]
+
+      if options[:significant] && precision > 0
+        digits = digit_count(rounded_number)
+        precision -= digits
+        precision = 0 if precision < 0
+      end
+
+      formatted_string = 
+
+        if rounded_number.finite?
+          s = rounded_number.to_s("F")
+          a, b = s.to_s.split(".", 2)
+
+          if precision != 0
+            b << "0" * precision
+            a << "."
+            a << b[0, precision]
+          end
+          a
+        else 
+          "%f" % rounded_number
+        end
+
+    else 
+      formatted_string = rounded_number
+    end
+
+    delimited_number = number_to_delimited(formatted_string, **slice(options, [:separator, :delimiter]))
+    options[:strip_insignificant_zeros] ? format_number(delimited_number) : delimited_number
+  end
+
+  private
+
+  def format_number(number)
+    escaped_separator = Regexp.escape(".")
+    number.sub(/(#{escaped_separator})(\d*[1-9])?0+\z/, '\1\2').sub(/#{escaped_separator}\z/, "")      
+  end
+end