finrb 1.1.0 → 1.2.0

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.2.0'
   public_constant :VERSION
 end

data/lib/finrb/yields.rb

@@ -2,6 +2,7 @@
 
 require_relative 'decimal'
 require_relative 'errors'
+require_relative 'validation'
 
 module Finrb
   # Money-market yield and interest-rate conversion calculations.
@@ -14,9 +15,9 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy(d=1500,f=100000,t=120)
     def self.bdy(d:, f:, t:)
-      d = Flt::DecNum(d.to_s)
-      f = Flt::DecNum(f.to_s)
-      t = Flt::DecNum(t.to_s)
+      d = Validation.decimal(d, name: 'dollar discount')
+      f = Validation.positive_decimal(f, name: 'face value', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (d * 360 / f / t)
     end
@@ -28,10 +29,12 @@ module Finrb
     # @example
     #   Finrb::Yields.bdy2mmy(bdy=0.045,t=120)
     def self.bdy2mmy(bdy:, t:)
-      bdy = Flt::DecNum(bdy.to_s)
-      t = Flt::DecNum(t.to_s)
+      bdy = Validation.decimal(bdy, name: 'bank discount yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
+      denominator = 360 - (t * bdy)
+      raise(DomainError, 'Bank discount yield and time to maturity must imply a positive purchase price.') unless denominator.positive?
 
-      (bdy * 360 / (360 - (t * bdy)))
+      (bdy * 360 / denominator)
     end
 
     # Convert stated annual rate to the effective annual rate
@@ -44,10 +47,10 @@ module Finrb
     # @example
     #   Finrb::Yields.ear(0.04,365)
     def self.ear(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      ((((r / m) + 1)**m) - 1)
+      ((compounding_base(r, m)**m) - 1)
     end
 
     # Convert stated annual rate to the effective annual rate with continuous compounding
@@ -59,7 +62,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear_continuous(0.03)
     def self.ear_continuous(r:)
-      r = Flt::DecNum(r.to_s)
+      r = Validation.decimal(r, name: 'stated annual rate')
 
       (r.exp - 1)
     end
@@ -70,7 +73,7 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2bey(ear=0.08)
     def self.ear2bey(ear:)
-      ear = Flt::DecNum(ear.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
 
       (((ear + 1).sqrt - 1) * 2)
     end
@@ -82,8 +85,8 @@ module Finrb
     # @example
     #   Finrb::Yields.ear2hpr(ear=0.05039,t=150)
     def self.ear2hpr(ear:, t:)
-      ear = Flt::DecNum(ear.to_s)
-      t = Flt::DecNum(t.to_s)
+      ear = Validation.decimal_at_least(ear, minimum: -1, name: 'effective annual rate', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((ear + 1)**(t / 365)) - 1)
     end
@@ -124,18 +127,18 @@ module Finrb
     #   # monthly proportional interest rate which is equivalent to a simple annual interest
     #   Finrb::Yields.eir(r=0.05,p=12,type='p')
     def self.eir(r:, n: 1, p: 12, type: 'e')
-      r = Flt::DecNum(r.to_s)
-      n = Flt::DecNum(n.to_s)
-      p = Flt::DecNum(p.to_s)
+      r = Validation.decimal(r, name: 'annual rate')
+      n = Validation.positive_decimal(n, name: 'source compounding periods', error: DomainError)
+      p = Validation.positive_decimal(p, name: 'target compounding periods', error: DomainError)
       type = type.to_s
 
       case type
       when 'e'
-        eir = (((r / n) + 1)**(n / p)) - 1
+        eir = (compounding_base(r, n)**(n / p)) - 1
       when 'p'
         eir = r / p
       else
-        raise(Error, "type must be 'e' or 'p'")
+        raise(ArgumentError, "conversion type must be 'e' (equivalent) or 'p' (proportional)")
       end
       eir
     end
@@ -147,8 +150,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2bey(hpr=0.02,t=3)
     def self.hpr2bey(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       ((((hpr + 1)**(6 / t)) - 1) * 2)
     end
@@ -160,8 +163,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2ear(hpr=0.015228,t=120)
     def self.hpr2ear(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal_at_least(hpr, minimum: -1, name: 'holding period return', error: DomainError)
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (((hpr + 1)**(365 / t)) - 1)
     end
@@ -173,8 +176,8 @@ module Finrb
     # @example
     #   Finrb::Yields.hpr2mmy(hpr=0.01523,t=120)
     def self.hpr2mmy(hpr:, t:)
-      hpr = Flt::DecNum(hpr.to_s)
-      t = Flt::DecNum(t.to_s)
+      hpr = Validation.decimal(hpr, name: 'holding period return')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (hpr * 360 / t)
     end
@@ -186,8 +189,8 @@ module Finrb
     # @example
     #   Finrb::Yields.mmy2hpr(mmy=0.04898,t=150)
     def self.mmy2hpr(mmy:, t:)
-      mmy = Flt::DecNum(mmy.to_s)
-      t = Flt::DecNum(t.to_s)
+      mmy = Validation.decimal(mmy, name: 'money market yield')
+      t = Validation.positive_decimal(t, name: 'time to maturity', error: DomainError)
 
       (mmy * t / 360)
     end
@@ -199,10 +202,10 @@ module Finrb
     # @example
     #   Finrb::Yields.r_continuous(r=0.03,m=4)
     def self.r_continuous(r:, m:)
-      r = Flt::DecNum(r.to_s)
-      m = Flt::DecNum(m.to_s)
+      r = Validation.decimal(r, name: 'nominal rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
-      (m * ((r / m) + 1).log)
+      (m * compounding_base(r, m).log)
     end
 
     # Convert a given continuous compounded rate to a norminal rate
@@ -215,10 +218,18 @@ module Finrb
     # @example
     #   Finrb::Yields.r_norminal(rc=0.03,m=4)
     def self.r_norminal(rc:, m:)
-      rc = Flt::DecNum(rc.to_s)
-      m = Flt::DecNum(m.to_s)
+      rc = Validation.decimal(rc, name: 'continuously compounded rate')
+      m = Validation.positive_decimal(m, name: 'compounding periods', error: DomainError)
 
       (m * ((rc / m).exp - 1))
     end
+
+    def self.compounding_base(rate, periods)
+      base = (rate / periods) + 1
+      raise(DomainError, 'The rate per compounding period must be greater than -1.') unless base.positive?
+
+      base
+    end
+    private_class_method :compounding_base
   end
 end

data/sig/finrb.rbs

@@ -150,7 +150,7 @@ module Finrb
   end
 
   module TVM
-    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?lower: number, ?upper: number) -> decimal
+    def self.discount_rate: (n: number, pv: number, fv: number, pmt: number, ?type: Integer, ?guess: number?, ?lower: number?, ?upper: number?) -> decimal
     def self.fv: (r: number, n: number, ?pv: number, ?pmt: number, ?type: Integer) -> decimal
     def self.fv_annuity: (r: number, n: number, pmt: number, ?type: Integer) -> decimal
     def self.fv_simple: (r: number, n: number, pv: number) -> decimal
@@ -169,7 +169,7 @@ module Finrb
   module Accounting
     type inventory_result = { cost_of_goods: decimal, ending_inventory: decimal }
 
-    def self.cogs: (uinv: number, pinv: number, units: number | numbers, price: number | numbers, sinv: number, ?method: String) -> inventory_result
+    def self.cogs: (uinv: number, pinv: number, units: number | numbers | nil, price: number | numbers | nil, sinv: number, ?method: String | Symbol) -> inventory_result
     def self.ddb: (cost: number, rv: number, t: Integer) -> { t: Array[Integer], ddb: Array[decimal] }
     def self.slde: (cost: number, rv: number, t: number) -> decimal
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finrb
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Nadir Cohen
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -248,10 +262,12 @@ extra_rdoc_files:
 - README.md
 files:
 - CHANGELOG.md
+- CONTRIBUTING.md
 - COPYING
 - COPYING.LESSER
 - NOTICE.md
 - README.md
+- SECURITY.md
 - lib/finrb.rb
 - lib/finrb/accounting.rb
 - lib/finrb/amortization.rb