finrb 1.1.0 → 1.3.0

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/schedule.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'calendars'
+require 'date'
+
+module Finrb
+  # Immutable date schedule for recurring financial payments.
+  class Schedule
+    FREQUENCY_MONTHS = { monthly: 1, quarterly: 3, semiannual: 6, annual: 12 }.freeze
+    STUB_CONVENTIONS = %i[none short_final].freeze
+    public_constant :FREQUENCY_MONTHS, :STUB_CONVENTIONS
+
+    # Shared date rules used by both the class constructor and period builder.
+    module DateRules
+      module_function
+
+      def normalize(date, name)
+        raise(ArgumentError, "#{name} must be a Date.") unless date.instance_of?(Date)
+
+        Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+      end
+
+      def anchored_date(anchor, month_offset)
+        month_start = Date.new(anchor.year, anchor.month, 1, Date::GREGORIAN) >> month_offset
+        next_month_start = month_start >> 1
+        month_end = next_month_start - 1
+        anchor_month_end = (Date.new(anchor.year, anchor.month, 1, Date::GREGORIAN) >> 1) - 1
+        day = anchor.day == anchor_month_end.day ? month_end.day : [anchor.day, month_end.day].min
+        Date.new(month_start.year, month_start.month, day, Date::GREGORIAN)
+      end
+    end
+    private_constant :DateRules
+
+    # Immutable dates and index for one accrual/payment period.
+    class Period
+      attr_reader :index, :accrual_start_date, :unadjusted_payment_date, :payment_date, :stub
+
+      def initialize(index:, accrual_start_date:, unadjusted_payment_date:, payment_date:, stub: nil)
+        @index = index
+        @accrual_start_date = accrual_start_date
+        @unadjusted_payment_date = unadjusted_payment_date
+        @payment_date = payment_date
+        @stub = stub
+        freeze
+      end
+
+      def short_final_stub?
+        stub == :short_final
+      end
+    end
+
+    attr_reader :start_date, :maturity_date, :frequency, :stub, :calendar, :business_day_convention, :periods, :payment_dates, :unadjusted_payment_dates
+
+    def self.from_months(start_date:, term_months:, frequency: :monthly, stub: :none, calendar: nil, business_day_convention: nil)
+      raise(ArgumentError, 'term_months must be a positive integer.') unless term_months.is_a?(Integer) && term_months.positive?
+
+      start_date = DateRules.normalize(start_date, 'start_date')
+      maturity_date = DateRules.anchored_date(start_date, term_months)
+      new(start_date:, maturity_date:, frequency:, stub:, calendar:, business_day_convention:)
+    end
+
+    def initialize(start_date:, maturity_date:, frequency: :monthly, stub: :none, calendar: nil, business_day_convention: nil)
+      @start_date = DateRules.normalize(start_date, 'start_date')
+      @maturity_date = DateRules.normalize(maturity_date, 'maturity_date')
+      raise(ArgumentError, 'maturity_date must be after start_date.') if @maturity_date <= @start_date
+      raise(ArgumentError, "frequency must be one of #{FREQUENCY_MONTHS.keys.join(', ')}.") unless FREQUENCY_MONTHS.key?(frequency)
+      raise(ArgumentError, "stub must be one of #{STUB_CONVENTIONS.join(', ')}.") unless STUB_CONVENTIONS.include?(stub)
+
+      validate_calendar_options!(calendar, business_day_convention)
+      @frequency = frequency
+      @stub = stub
+      @calendar = calendar
+      @business_day_convention = business_day_convention
+      @unadjusted_payment_dates = build_unadjusted_payment_dates.freeze
+      @periods = build_periods.freeze
+      @payment_dates = @periods.map(&:payment_date).freeze
+      freeze
+    end
+
+    private
+
+    def validate_calendar_options!(calendar, convention)
+      raise(ArgumentError, 'business_day_convention requires a calendar.') if calendar.nil? && !convention.nil?
+      return if calendar.nil?
+
+      raise(ArgumentError, 'calendar must be a Finrb::Calendars::Base instance.') unless calendar.is_a?(Calendars::Base)
+      raise(ArgumentError, "business_day_convention must be one of #{Calendars::Base::CONVENTIONS.join(', ')}.") unless Calendars::Base::CONVENTIONS.include?(convention)
+    end
+
+    def build_unadjusted_payment_dates
+      interval = FREQUENCY_MONTHS.fetch(frequency)
+      dates = []
+      month_offset = interval
+      loop do
+        regular_date = DateRules.anchored_date(start_date, month_offset)
+        if regular_date < maturity_date
+          dates << regular_date
+          month_offset += interval
+        elsif regular_date == maturity_date
+          dates << regular_date
+          break
+        else
+          raise(ArgumentError, 'maturity_date does not align with frequency; pass stub: :short_final to allow a short final period.') unless stub == :short_final
+
+          dates << maturity_date
+          break
+        end
+      end
+      dates
+    end
+
+    def build_periods
+      previous_payment_date = start_date
+      unadjusted_payment_dates.each_with_index.map do |unadjusted_date, index|
+        regular_date = DateRules.anchored_date(start_date, FREQUENCY_MONTHS.fetch(frequency) * (index + 1))
+        period_stub = :short_final if index == unadjusted_payment_dates.length - 1 && regular_date != unadjusted_date
+        payment_date = calendar ? calendar.adjust(unadjusted_date, convention: business_day_convention) : unadjusted_date
+        raise(ArgumentError, 'calendar adjustment must produce dates strictly after the prior payment date.') if payment_date <= previous_payment_date
+
+        period = Period.new(index:, accrual_start_date: previous_payment_date, unadjusted_payment_date: unadjusted_date, payment_date:, stub: period_stub)
+        previous_payment_date = payment_date
+        period
+      end
+    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

data/lib/finrb/validation.rb

@@ -23,5 +23,47 @@ module Finrb
 
       value
     end
+
+    def positive_decimal(value, name:, error: ArgumentError, message: nil)
+      decimal = decimal(value, name:)
+      raise(error, message || "#{name} must be greater than zero.") unless decimal.positive?
+
+      decimal
+    end
+
+    def non_negative_decimal(value, name:, error: ArgumentError, message: nil)
+      decimal = decimal(value, name:)
+      raise(error, message || "#{name} must be greater than or equal to zero.") if decimal.negative?
+
+      decimal
+    end
+
+    def decimal_greater_than(value, minimum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be greater than #{minimum}.") if decimal <= minimum
+
+      decimal
+    end
+
+    def decimal_at_least(value, minimum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be greater than or equal to #{minimum}.") if decimal < minimum
+
+      decimal
+    end
+
+    def non_zero_decimal(value, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be non-zero.") if decimal.zero?
+
+      decimal
+    end
+
+    def decimal_between(value, minimum:, maximum:, name:, error: ArgumentError)
+      decimal = decimal(value, name:)
+      raise(error, "#{name} must be between #{minimum} and #{maximum}, inclusive.") unless decimal.between?(minimum, maximum)
+
+      decimal
+    end
   end
 end

data/lib/finrb/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Finrb
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
   public_constant :VERSION
 end