finrb 1.1.0 → 1.2.0

data/lib/finrb/ratios.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Financial-statement, leverage, and per-share ratios.
@@ -25,9 +26,9 @@ module Finrb
     # @example
     #   Finrb::Ratios.cash_ratio(cash=3000,ms=2000,cl=2000)
     def self.cash_ratio(cash:, ms:, cl:)
-      cash = Flt::DecNum(cash.to_s)
-      ms = Flt::DecNum(ms.to_s)
-      cl = Flt::DecNum(cl.to_s)
+      cash = Validation.decimal(cash, name: 'cash')
+      ms = Validation.decimal(ms, name: 'marketable securities')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       ((cash + ms) / cl)
     end
@@ -39,8 +40,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.current_ratio(ca=8000,cl=2000)
     def self.current_ratio(ca:, cl:)
-      ca = Flt::DecNum(ca.to_s)
-      cl = Flt::DecNum(cl.to_s)
+      ca = Validation.decimal(ca, name: 'current assets')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       (ca / cl)
     end
@@ -52,8 +53,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.debt_ratio(td=6000,ta=20000)
     def self.debt_ratio(td:, ta:)
-      td = Flt::DecNum(td.to_s)
-      ta = Flt::DecNum(ta.to_s)
+      td = Validation.decimal(td, name: 'total debt')
+      ta = Validation.non_zero_decimal(ta, name: 'total assets', error: DomainError)
 
       (td / ta)
     end
@@ -81,15 +82,15 @@ module Finrb
     # @example
     #   Finrb::Ratios.diluted_eps(ni=115600,pd=10000,cpd=10000,cdi=42000,tax=0.4,w=200000,cps=40000,cds=60000,iss=2500)
     def self.diluted_eps(ni:, pd:, w:, cpd: 0, cdi: 0, tax: 0, cps: 0, cds: 0, iss: 0)
-      ni = Flt::DecNum(ni.to_s)
-      pd = Flt::DecNum(pd.to_s)
-      w = Flt::DecNum(w.to_s)
-      cpd = Flt::DecNum(cpd.to_s)
-      cdi = Flt::DecNum(cdi.to_s)
-      tax = Flt::DecNum(tax.to_s)
-      cps = Flt::DecNum(cps.to_s)
-      cds = Flt::DecNum(cds.to_s)
-      iss = Flt::DecNum(iss.to_s)
+      ni = Validation.decimal(ni, name: 'net income')
+      pd = Validation.decimal(pd, name: 'preferred dividends')
+      w = Validation.positive_decimal(w, name: 'weighted average common shares', error: DomainError)
+      cpd = Validation.non_negative_decimal(cpd, name: 'convertible preferred dividends')
+      cdi = Validation.non_negative_decimal(cdi, name: 'convertible debt interest')
+      tax = Validation.decimal_between(tax, minimum: 0, maximum: 1, name: 'tax rate')
+      cps = Validation.non_negative_decimal(cps, name: 'convertible preferred shares')
+      cds = Validation.non_negative_decimal(cds, name: 'convertible debt shares')
+      iss = Validation.non_negative_decimal(iss, name: 'incremental option shares')
 
       basic = (ni - pd) / w
       diluted = (ni - pd + cpd + (cdi * (1 - tax))) / (w + cps + cds + iss)
@@ -105,9 +106,9 @@ module Finrb
     # @example
     #   Finrb::Ratios.eps(ni=10000,pd=1000,w=11000)
     def self.eps(ni:, pd:, w:)
-      ni = Flt::DecNum(ni.to_s)
-      pd = Flt::DecNum(pd.to_s)
-      w = Flt::DecNum(w.to_s)
+      ni = Validation.decimal(ni, name: 'net income')
+      pd = Validation.decimal(pd, name: 'preferred dividends')
+      w = Validation.positive_decimal(w, name: 'weighted average common shares', error: DomainError)
 
       ((ni - pd) / w)
     end
@@ -119,8 +120,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.financial_leverage(te=16000,ta=20000)
     def self.financial_leverage(te:, ta:)
-      te = Flt::DecNum(te.to_s)
-      ta = Flt::DecNum(ta.to_s)
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
+      ta = Validation.decimal(ta, name: 'total assets')
 
       (ta / te)
     end
@@ -132,8 +133,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.gpm(gp=1000,rv=20000)
     def self.gpm(gp:, rv:)
-      gp = Flt::DecNum(gp.to_s)
-      rv = Flt::DecNum(rv.to_s)
+      gp = Validation.decimal(gp, name: 'gross profit')
+      rv = Validation.non_zero_decimal(rv, name: 'revenue', error: DomainError)
 
       (gp / rv)
     end
@@ -146,14 +147,14 @@ module Finrb
     # @example
     #   Finrb::Ratios.iss(amp=20,ep=15,n=10000)
     def self.iss(amp:, ep:, n:)
-      amp = Flt::DecNum(amp.to_s)
-      ep = Flt::DecNum(ep.to_s)
-      n = Flt::DecNum(n.to_s)
+      amp = Validation.positive_decimal(amp, name: 'average market price', error: DomainError)
+      ep = Validation.non_negative_decimal(ep, name: 'exercise price')
+      n = Validation.non_negative_decimal(n, name: 'option shares')
 
       if amp > ep
         ((amp - ep) * n / amp)
       else
-        raise(Error, 'amp must larger than ep')
+        raise(DomainError, 'Average market price must be greater than exercise price.')
       end
     end
 
@@ -164,8 +165,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.lt_d2e(ltd=8000,te=20000)
     def self.lt_d2e(ltd:, te:)
-      ltd = Flt::DecNum(ltd.to_s)
-      te = Flt::DecNum(te.to_s)
+      ltd = Validation.decimal(ltd, name: 'long-term debt')
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
 
       (ltd / te)
     end
@@ -177,8 +178,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.npm(ni=8000,rv=20000)
     def self.npm(ni:, rv:)
-      ni = Flt::DecNum(ni.to_s)
-      rv = Flt::DecNum(rv.to_s)
+      ni = Validation.decimal(ni, name: 'net income')
+      rv = Validation.non_zero_decimal(rv, name: 'revenue', error: DomainError)
 
       (ni / rv)
     end
@@ -192,10 +193,10 @@ module Finrb
     # @example
     #   Finrb::Ratios.quick_ratio(cash=3000,ms=2000,rc=1000,cl=2000)
     def self.quick_ratio(cash:, ms:, rc:, cl:)
-      cash = Flt::DecNum(cash.to_s)
-      ms = Flt::DecNum(ms.to_s)
-      rc = Flt::DecNum(rc.to_s)
-      cl = Flt::DecNum(cl.to_s)
+      cash = Validation.decimal(cash, name: 'cash')
+      ms = Validation.decimal(ms, name: 'marketable securities')
+      rc = Validation.decimal(rc, name: 'receivables')
+      cl = Validation.non_zero_decimal(cl, name: 'current liabilities', error: DomainError)
 
       ((cash + ms + rc) / cl)
     end
@@ -207,8 +208,8 @@ module Finrb
     # @example
     #   Finrb::Ratios.total_d2e(td=6000,te=20000)
     def self.total_d2e(td:, te:)
-      td = Flt::DecNum(td.to_s)
-      te = Flt::DecNum(te.to_s)
+      td = Validation.decimal(td, name: 'total debt')
+      te = Validation.non_zero_decimal(te, name: 'total equity', error: DomainError)
 
       (td / te)
     end
@@ -223,8 +224,8 @@ module Finrb
     # @example
     #   s=[11000,4400,-3000];m=[12,9,4];Finrb::Ratios.was(ns=s,nm=m)
     def self.was(ns:, nm:)
-      ns = wrap_array(ns).map { |value| Flt::DecNum(value.to_s) }
-      nm = wrap_array(nm).map { |value| Flt::DecNum(value.to_s) }
+      ns = wrap_array(ns).map { |value| Validation.decimal(value, name: 'share change') }
+      nm = wrap_array(nm).map { |value| Validation.decimal_between(value, minimum: 0, maximum: 12, name: 'months outstanding') }
 
       m = ns.size
       n = nm.size
@@ -234,7 +235,7 @@ module Finrb
           sum += (ns[i] * nm[i])
         end
       else
-        raise(Error, 'length of ns and nm must be equal')
+        raise(ArgumentError, 'Share changes and months outstanding must have equal lengths.')
       end
       sum /= 12
       sum

data/lib/finrb/returns.rb

@@ -29,12 +29,9 @@ module Finrb
     # @param periods [Integer] number of equal annual periods
     # @return [Flt::DecNum] compound growth rate per period
     def self.cagr(beginning_value:, ending_value:, periods:)
-      beginning_value = Validation.decimal(beginning_value, name: 'beginning_value')
-      ending_value = Validation.decimal(ending_value, name: 'ending_value')
-      periods = Validation.positive_integer(periods, name: 'periods')
-
-      raise(ArgumentError, 'beginning_value must be greater than zero.') unless beginning_value.positive?
-      raise(ArgumentError, 'ending_value must be greater than or equal to zero.') if ending_value.negative?
+      beginning_value = Validation.positive_decimal(beginning_value, name: 'beginning value')
+      ending_value = Validation.non_negative_decimal(ending_value, name: 'ending value')
+      periods = Validation.positive_integer(periods, name: 'period count')
 
       ((ending_value / beginning_value)**(Flt::DecNum(1) / periods)) - 1
     end
@@ -49,18 +46,16 @@ module Finrb
 
     # Compound a periodic return into an annual return.
     def self.annualize_return(rate:, periods_per_year:)
-      rate = Validation.decimal(rate, name: 'rate')
-      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
-      raise(ArgumentError, 'rate must be greater than or equal to -1.') if rate < -1
+      rate = Validation.decimal_at_least(rate, minimum: -1, name: 'periodic rate')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
 
       ((rate + 1)**periods_per_year) - 1
     end
 
     # Scale periodic volatility by the square root of periods per year.
     def self.annualize_volatility(volatility:, periods_per_year:)
-      volatility = Validation.decimal(volatility, name: 'volatility')
-      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
-      raise(ArgumentError, 'volatility must be greater than or equal to zero.') if volatility.negative?
+      volatility = Validation.non_negative_decimal(volatility, name: 'volatility')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
 
       volatility * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
     end
@@ -103,7 +98,7 @@ module Finrb
       ratio = ((returns.sum / returns.size) - target) / downside
       return ratio if periods_per_year.nil?
 
-      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods_per_year')
+      periods_per_year = Validation.positive_integer(periods_per_year, name: 'periods per year')
       ratio * (Flt::DecNum(periods_per_year)**Flt::DecNum('0.5'))
     end
 
@@ -126,8 +121,9 @@ module Finrb
     # @example
     #   Finrb::Returns.coefficient_variation(sd=0.15,avg=0.39)
     def self.coefficient_variation(sd:, avg:)
-      sd = Flt::DecNum(sd.to_s)
-      avg = Flt::DecNum(avg.to_s)
+      sd = Validation.non_negative_decimal(sd, name: 'standard deviation')
+      avg = Validation.decimal(avg, name: 'average')
+      raise(DomainError, 'Average must be non-zero.') if avg.zero?
 
       (sd / avg)
     end
@@ -138,10 +134,13 @@ module Finrb
     # @example
     #   Finrb::Returns.geometric_mean(r=[-0.0934, 0.2345, 0.0892])
     def self.geometric_mean(r:)
-      r = wrap_array(r).map { |value| Flt::DecNum(value.to_s) }
+      returns = risk_values(r, name: 'return')
+      returns.each do |value|
+        raise(DomainError, 'Returns must be greater than or equal to -1.') if value < -1
+      end
 
-      rs = r.map { |value| value + 1 }
-      ((rs.reduce(:*)**(Flt::DecNum(1) / rs.size)) - 1)
+      growth_factors = returns.map { |value| value + 1 }
+      ((growth_factors.reduce(:*)**(Flt::DecNum(1) / growth_factors.size)) - 1)
     end
 
     # harmonic mean, average price
@@ -149,9 +148,10 @@ module Finrb
     # @example
     #   Finrb::Returns.harmonic_mean(p=[8,9,10])
     def self.harmonic_mean(p:)
-      p = wrap_array(p).map { |value| Flt::DecNum(value.to_s) }
+      prices = risk_values(p, name: 'price')
+      raise(DomainError, 'Prices must be greater than zero.') unless prices.all?(&:positive?)
 
-      (Flt::DecNum(1) / (p.sum { |val| Flt::DecNum(1) / val } / p.size))
+      (Flt::DecNum(1) / (prices.sum { |price| Flt::DecNum(1) / price } / prices.size))
     end
 
     # Computing HPR, the holding period return
@@ -162,9 +162,9 @@ module Finrb
     # @example
     #   Finrb::Returns.hpr(ev=33,bv=30,cfr=0.5)
     def self.hpr(ev:, bv:, cfr: 0)
-      ev = Flt::DecNum(ev.to_s)
-      bv = Flt::DecNum(bv.to_s)
-      cfr = Flt::DecNum(cfr.to_s)
+      ev = Validation.decimal(ev, name: 'ending value')
+      bv = Validation.positive_decimal(bv, name: 'beginning value', error: DomainError)
+      cfr = Validation.decimal(cfr, name: 'cashflow received')
 
       ((ev - bv + cfr) / bv)
     end
@@ -176,8 +176,8 @@ module Finrb
     # @example
     #   Finrb::Returns.sampling_error(sm=0.45, mu=0.5)
     def self.sampling_error(sm:, mu:)
-      sm = Flt::DecNum(sm.to_s)
-      mu = Flt::DecNum(mu.to_s)
+      sm = Validation.decimal(sm, name: 'sample mean')
+      mu = Validation.decimal(mu, name: 'population mean')
 
       (sm - mu)
     end
@@ -190,9 +190,9 @@ module Finrb
     # @example
     #   Finrb::Returns.sf_ratio(rp=0.09,rl=0.03,sd=0.12)
     def self.sf_ratio(rp:, rl:, sd:)
-      rp = Flt::DecNum(rp.to_s)
-      rl = Flt::DecNum(rl.to_s)
-      sd = Flt::DecNum(sd.to_s)
+      rp = Validation.decimal(rp, name: 'portfolio return')
+      rl = Validation.decimal(rl, name: 'threshold return')
+      sd = Validation.positive_decimal(sd, name: 'standard deviation', error: DomainError)
 
       ((rp - rl) / sd)
     end
@@ -205,9 +205,9 @@ module Finrb
     # @example
     #   Finrb::Returns.sharpe_ratio(rp=0.038,rf=0.015,sd=0.07)
     def self.sharpe_ratio(rp:, rf:, sd:)
-      rp = Flt::DecNum(rp.to_s)
-      rf = Flt::DecNum(rf.to_s)
-      sd = Flt::DecNum(sd.to_s)
+      rp = Validation.decimal(rp, name: 'portfolio return')
+      rf = Validation.decimal(rf, name: 'risk-free return')
+      sd = Validation.positive_decimal(sd, name: 'standard deviation', error: DomainError)
 
       ((rp - rf) / sd)
     end
@@ -220,22 +220,20 @@ module Finrb
     # @example
     #   Finrb::Returns.twrr(ev=[120,260],bv=[100,240],cfr=[2,4])
     def self.twrr(ev:, bv:, cfr:)
-      ev = wrap_array(ev).map { |value| Flt::DecNum(value.to_s) }
-      bv = wrap_array(bv).map { |value| Flt::DecNum(value.to_s) }
-      cfr = wrap_array(cfr).map { |value| Flt::DecNum(value.to_s) }
-
-      r = ev.size
-      s = bv.size
-      t = cfr.size
-      wr = Flt::DecNum(1)
-      if r != s || r != t || s != t
-        raise(Error, 'Different number of values!')
-      else
-        (0...r).each do |i|
-          wr *= (Finrb::Returns.hpr(ev: ev[i], bv: bv[i], cfr: cfr[i]) + 1)
+      ending_values = risk_values(ev, name: 'ending value')
+      beginning_values = risk_values(bv, name: 'beginning value')
+      cashflows_received = risk_values(cfr, name: 'cashflow received')
+      sizes = [ending_values.size, beginning_values.size, cashflows_received.size]
+      raise(ArgumentError, 'Ending values, beginning values, and cashflows received must have equal lengths.') unless sizes.uniq.one?
+
+      wealth_relative =
+        ending_values.each_index.reduce(Flt::DecNum(1)) do |product, index|
+          period_growth = hpr(ev: ending_values[index], bv: beginning_values[index], cfr: cashflows_received[index]) + 1
+          raise(DomainError, 'Each subperiod wealth relative must be greater than or equal to zero.') if period_growth.negative?
+
+          product * period_growth
         end
-        ((wr**(Flt::DecNum(1) / r)) - 1)
-      end
+      (wealth_relative**(Flt::DecNum(1) / ending_values.size)) - 1
     end
 
     # Weighted mean as a portfolio return
@@ -245,13 +243,12 @@ module Finrb
     # @example
     #   Finrb::Returns.wpr(r=[0.12, 0.07, 0.03],w=[0.5,0.4,0.1])
     def self.wpr(r:, w:)
-      r = wrap_array(r).map { |value| Flt::DecNum(value.to_s) }
-      w = wrap_array(w).map { |value| Flt::DecNum(value.to_s) }
-
-      # TODO: need to change
-      puts('sum of weights is NOT equal to 1!') if w.sum != 1
+      returns = risk_values(r, name: 'return')
+      weights = risk_values(w, name: 'weight')
+      raise(ArgumentError, 'Returns and weights must have equal lengths.') unless returns.size == weights.size
+      raise(ArgumentError, 'Weights must sum to 1.') unless weights.sum == 1
 
-      r.zip(w).sum { |arr| arr.reduce(:*) }
+      returns.zip(weights).sum { |rate, weight| rate * weight }
     end
   end
 end

data/lib/finrb/tvm.rb

@@ -4,123 +4,225 @@ require_relative 'config'
 require_relative 'decimal'
 require_relative 'errors'
 require_relative 'numerical/brent'
+require_relative 'numerical/rate_search'
+require_relative 'validation'
 
 module Finrb
   # Time-value-of-money calculations for periodic rates and cashflows.
   module TVM
     module_function
 
-    def discount_rate(n:, pv:, fv:, pmt:, type: 0, lower: 0.0001, upper: 100)
-      n, pv, fv, pmt, type, lower, upper = decimals(n, pv, fv, pmt, type, lower, upper)
+    UNSET_BOUND = Object.new.freeze
+    private_constant :UNSET_BOUND
+    INPUT_NAMES = { fv: 'future value', g: 'growth rate', guess: 'rate guess', lower: 'lower rate bound', n: 'period count', pmt: 'payment', pv: 'present value', r: 'periodic rate', upper: 'upper rate bound' }.freeze
+    private_constant :INPUT_NAMES
+
+    def discount_rate(n:, pv:, fv:, pmt:, type: 0, guess: nil, lower: UNSET_BOUND, upper: UNSET_BOUND)
+      n = period_count(n)
+      pv, fv, pmt = decimal_inputs(pv:, fv:, pmt:).values
+      type = payment_type(type)
       function = ->(rate) { fv_simple(r: rate, n:, pv:) + fv_annuity(r: rate, n:, pmt:, type:) - fv }
 
-      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(function, lower:, upper:)
+      bounds = rate_bounds(function, guess:, lower:, upper:)
+      return bounds.first if bounds.first == bounds.last
+
+      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(function, lower: bounds.first, upper: bounds.last)
     end
 
     def fv(r:, n:, pv: 0, pmt: 0, type: 0)
-      r, n, pv, pmt, type = decimals(r, n, pv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment_type(type)
 
-      fv_simple(r:, n:, pv:) + fv_annuity(r:, n:, pmt:, type:)
+      fv_simple(r: rate, n: periods, pv:) + fv_annuity(r: rate, n: periods, pmt:, type:)
     end
 
     def fv_annuity(r:, n:, pmt:, type: 0)
-      r, n, pmt, type = decimals(r, n, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment = Validation.decimal(pmt, name: 'payment')
+      payment_timing = payment_type(type)
+      return -payment * periods if rate.zero?
 
-      (pmt / r * (((r + 1)**n) - 1)) * ((r + 1)**type) * -1
+      (payment / rate * (((rate + 1)**periods) - 1)) * ((rate + 1)**payment_timing) * -1
     end
 
     def fv_simple(r:, n:, pv:)
-      r, n, pv = decimals(r, n, pv)
-      (pv * ((r + 1)**n)) * -1
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      present_value = Validation.decimal(pv, name: 'present value')
+      (present_value * ((rate + 1)**periods)) * -1
     end
 
     def fv_uneven(r:, cf:)
-      r = Flt::DecNum(r.to_s)
-      cashflows = array(cf).map { |value| Flt::DecNum(value.to_s) }
+      rate = periodic_rate(r)
+      cashflows = cashflow_values(cf)
 
       cashflows.each_with_index.sum do |cashflow, index|
-        fv_simple(r:, n: cashflows.size - index - 1, pv: cashflow)
+        fv_simple(r: rate, n: cashflows.size - index - 1, pv: cashflow)
       end
     end
 
     def n_period(r:, pv:, fv:, pmt:, type: 0)
-      r, pv, fv, pmt, type = decimals(r, pv, fv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      values = decimal_inputs(pv:, fv:, pmt:)
+      payment_timing = payment_type(type)
+
+      return zero_rate_periods(**values) if rate.zero?
+
+      numerator = ((values[:fv] * rate) - (values[:pmt] * ((rate + 1)**payment_timing))) * -1
+      denominator = (values[:pv] * rate) + (values[:pmt] * ((rate + 1)**payment_timing))
+      periods = (numerator / denominator).log / (rate + 1).log
+      raise(DomainError, 'Inputs do not produce a finite non-negative period count.') unless periods.finite? && !periods.negative?
 
-      numerator = ((fv * r) - (pmt * ((r + 1)**type))) * -1
-      denominator = (pv * r) + (pmt * ((r + 1)**type))
-      (numerator / denominator).log / (r + 1).log
+      periods
+    rescue Flt::Num::Exception, Math::DomainError, ZeroDivisionError => e
+      raise(DomainError, "Inputs do not produce a real period count: #{e.message}", e.backtrace)
     end
 
     def npv(r:, cf:)
-      cashflows = array(cf).map { |value| Flt::DecNum(value.to_s) }
-      (pv_uneven(r:, cf: cashflows.drop(1)) * -1) + cashflows.first
+      rate = periodic_rate(r)
+      cashflows = cashflow_values(cf)
+      return cashflows.first if cashflows.one?
+
+      (pv_uneven(r: rate, cf: cashflows.drop(1)) * -1) + cashflows.first
     end
 
     def pmt(r:, n:, pv:, fv:, type: 0)
-      r, n, pv, fv, type = decimals(r, n, pv, fv, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = positive_period_count(n)
+      values = decimal_inputs(pv:, fv:)
+      payment_timing = payment_type(type)
+      return -(values[:pv] + values[:fv]) / periods if rate.zero?
 
-      (pv + (fv / ((r + 1)**n))) * r / (1 - (Flt::DecNum(1) / ((r + 1)**n))) * -1 * ((r + 1)**(type * -1))
+      (values[:pv] + (values[:fv] / ((rate + 1)**periods))) * rate / (1 - (Flt::DecNum(1) / ((rate + 1)**periods))) * -1 * ((rate + 1)**(payment_timing * -1))
     end
 
     def pv(r:, n:, fv: 0, pmt: 0, type: 0)
-      r, n, fv, pmt, type = decimals(r, n, fv, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment_type(type)
 
-      pv_simple(r:, n:, fv:) + pv_annuity(r:, n:, pmt:, type:)
+      pv_simple(r: rate, n: periods, fv:) + pv_annuity(r: rate, n: periods, pmt:, type:)
     end
 
     def pv_annuity(r:, n:, pmt:, type: 0)
-      r, n, pmt, type = decimals(r, n, pmt, type)
-      validate_payment_type!(type)
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      payment = Validation.decimal(pmt, name: 'payment')
+      payment_timing = payment_type(type)
+      return -payment * periods if rate.zero?
 
-      (pmt / r * (1 - (Flt::DecNum(1) / ((r + 1)**n)))) * ((r + 1)**type) * -1
+      (payment / rate * (1 - (Flt::DecNum(1) / ((rate + 1)**periods)))) * ((rate + 1)**payment_timing) * -1
     end
 
     def pv_perpetuity(r:, pmt:, g: 0, type: 0)
-      r, pmt, g, type = decimals(r, pmt, g, type)
-      validate_payment_type!(type)
-      raise(Error, 'Error: g is not smaller than r!') if g >= r
+      rate = periodic_rate(r)
+      payment = Validation.decimal(pmt, name: 'payment')
+      growth = periodic_rate(g, name: :g)
+      payment_timing = payment_type(type)
+      raise(DomainError, 'Growth rate must be smaller than the discount rate.') if growth >= rate
 
-      (pmt / (r - g)) * ((r + 1)**type) * -1
+      (payment / (rate - growth)) * ((rate + 1)**payment_timing) * -1
     end
 
     def pv_simple(r:, n:, fv:)
-      r, n, fv = decimals(r, n, fv)
-      (fv / ((r + 1)**n)) * -1
+      rate = periodic_rate(r)
+      periods = period_count(n)
+      future_value = Validation.decimal(fv, name: 'future value')
+      (future_value / ((rate + 1)**periods)) * -1
     end
 
     def pv_uneven(r:, cf:)
-      r = Flt::DecNum(r.to_s)
-      array(cf).each_with_index.sum do |cashflow, index|
-        pv_simple(r:, n: index + 1, fv: cashflow)
+      rate = periodic_rate(r)
+      cashflow_values(cf).each_with_index.sum do |cashflow, index|
+        pv_simple(r: rate, n: index + 1, fv: cashflow)
       end
     end
 
     def r_perpetuity(pmt:, pv:)
-      pmt, pv = decimals(pmt, pv)
-      pmt * -1 / pv
+      payment = Validation.decimal(pmt, name: 'payment')
+      present_value = Validation.decimal(pv, name: 'present value')
+      raise(DomainError, 'Present value must be non-zero.') if present_value.zero?
+
+      payment * -1 / present_value
     end
 
-    def array(value)
-      return [] if value.nil?
-      return value.to_ary || [value] if value.respond_to?(:to_ary)
+    def cashflow_values(value)
+      values =
+        if value.nil?
+          []
+        elsif value.respond_to?(:to_ary)
+          value.to_ary || [value]
+        else
+          [value]
+        end
+      raise(ArgumentError, 'cashflows cannot be empty.') if values.empty?
+
+      values.map { |cashflow| Validation.decimal(cashflow, name: 'cashflow') }
+    end
+    private_class_method :cashflow_values
+
+    def decimal_inputs(**values)
+      values.to_h { |name, value| [name, Validation.decimal(value, name: input_name(name))] }
+    end
+    private_class_method :decimal_inputs
+
+    def payment_type(value)
+      value = Validation.decimal(value, name: 'payment timing type')
+      raise(ArgumentError, 'payment timing type must be 0 (end) or 1 (beginning).') unless [Flt::DecNum(0), Flt::DecNum(1)].include?(value)
+
+      value
+    end
+    private_class_method :payment_type
 
-      [value]
+    def period_count(value)
+      Validation.non_negative_decimal(value, name: 'period count', error: DomainError)
     end
-    private_class_method :array
+    private_class_method :period_count
 
-    def decimals(*values)
-      values.map { |value| Flt::DecNum(value.to_s) }
+    def positive_period_count(value)
+      Validation.positive_decimal(value, name: 'period count', error: DomainError)
     end
-    private_class_method :decimals
+    private_class_method :positive_period_count
+
+    def periodic_rate(value, name: :r)
+      Validation.decimal_greater_than(value, minimum: -1, name: input_name(name), error: DomainError)
+    end
+    private_class_method :periodic_rate
+
+    def input_name(name)
+      INPUT_NAMES.fetch(name, name.to_s.tr('_', ' '))
+    end
+    private_class_method :input_name
+
+    def rate_bounds(function, guess:, lower:, upper:)
+      return searched_rate_bounds(function, guess) if lower.equal?(UNSET_BOUND) && upper.equal?(UNSET_BOUND)
+
+      lower = '0.0001' if lower.equal?(UNSET_BOUND)
+      upper = 100 if upper.equal?(UNSET_BOUND)
+      lower = periodic_rate(lower, name: :lower)
+      upper = periodic_rate(upper, name: :upper)
+      raise(ArgumentError, 'lower rate bound must be less than upper rate bound.') if lower >= upper
+
+      [lower, upper]
+    end
+    private_class_method :rate_bounds
+
+    def searched_rate_bounds(function, guess)
+      guess = Finrb.config.guess if guess.nil?
+      Numerical::RateSearch.new.bracket(function, guess: periodic_rate(guess, name: :guess))
+    end
+    private_class_method :searched_rate_bounds
+
+    def zero_rate_periods(pv:, fv:, pmt:)
+      raise(DomainError, 'pmt must be non-zero when solving periods at a zero rate.') if pmt.zero?
+
+      periods = (-pv - fv) / pmt
+      raise(DomainError, 'Inputs do not produce a non-negative period count.') if periods.negative?
 
-    def validate_payment_type!(type)
-      raise(Error, 'Error: type should be 0 or 1!') unless [Flt::DecNum(0), Flt::DecNum(1)].include?(type)
+      periods
     end
-    private_class_method :validate_payment_type!
+    private_class_method :zero_rate_periods
   end
 end