financial_calculator 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f0d684ffcf8cd34cdad09576834da2057e6879b45af1484123474b6e151baad
-  data.tar.gz: eccae432dc2cca2470cf1023871c0d9cb58620b080715c8ed00c818a62e4d2b4
+  metadata.gz: 7ece241c288b5547ac0946a57d3488646427c41744219e0a7f2d86a164a8e088
+  data.tar.gz: b8fa7e3149792486255d06c54b53998e5f1846fe013d1152d511642349e5080c
 SHA512:
-  metadata.gz: 5715ae679ff1cc465004bf136989bdee35ce1d60c3c1a21cf6daac07ec4ecbe71f1db8f04ff26d8b3e57a525394e7508601c96be5c5923e443b6504014c94325
-  data.tar.gz: 449cdc6640b282aea1e34a3de372717986232474310101bcf4097ecbbfac6021087aa26d1b4b429ab017239f40bd337c993f91675f3f7f9823920a1243c7bc70
+  metadata.gz: 880f9c1d6b98aadc025c246ba46e88b4f09928c92d395f59bfccb816796c806e2d1a9e3ce1358bf0c6ae288f4068c92bf9c466cd5d8013e68ff675a33dd0d6a4
+  data.tar.gz: bc10cbf71ecc8478778b46f61cbd25adbebb79dc074203200a14d31688ea6c4cf123cf728957a0f3c6a99e300648d15cf52718dee74fc395eb23128953dcd499

data/CHANGELOG.md

@@ -6,9 +6,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [3.1.0] - 2018-05-20
+### Added
+- New class for PMT calculation (FinancialCalculator::Pmt)
+
+### Removed
+
+### Changed
+
 ## [3.0.0] - 2018-05-12
 ### Added
-- New class for Present Value calculation (FinancialCalculator::PV)
+- New class for Present Value calculation (FinancialCalculator::Pv)
 
 ### Removed
 - Monkey patched cashflow methods on Array

data/README.md

@@ -107,11 +107,12 @@ You can also increase your payment to a specific amount:
     >> extra_payments_2 = 250000.amortize(rate){ -1500 }
 
 ## SUPPORTED STANDARD CALCUALTIONS
-- PV
-- NPV
-- XNPV
 - IRR
+- NPV
+- PMT
+- PV
 - XIRR
+- XNPV
 
 ## FEATURES
 

data/lib/financial_calculator.rb

@@ -8,6 +8,7 @@ require 'flt/d'
 #  * *principal* represents the outstanding balance of a loan or annuity.
 #  * *rate* represents the interest rate _per period_.
 module FinancialCalculator
+  require 'financial_calculator/validator'
   require 'financial_calculator/amortization'
   require 'financial_calculator/rates'
   require 'financial_calculator/transaction'
@@ -16,4 +17,5 @@ module FinancialCalculator
   require 'financial_calculator/npv'
   require 'financial_calculator/xnpv'
   require 'financial_calculator/xirr'
+  require 'financial_calculator/pmt'
 end

data/lib/financial_calculator/pmt.rb

@@ -0,0 +1,67 @@
+module FinancialCalculator
+  # Calculates the payment of an ordinary annuity
+  class Pmt
+    include ::Validator
+
+    # @return [Numeric] The rate used for calculating the payment amount
+    # @api public
+    attr_reader :rate
+
+    # @return [Numeric] The number of payments to be made
+    # @api public
+    attr_reader :num_periods
+
+    # @return [Numeric] The current value of the annuity
+    # @api public
+    attr_reader :present_value
+
+    # @return [Numeric] The ending value of the annuity. Defaults to 0
+    # @api public
+    attr_reader :future_value
+
+    # @return [Boolean] Whether the payment is made at the beginning of the 
+    #   period (true) or end of the period (false)
+    # @api public
+    attr_reader :pay_at_beginning
+
+    # @return [DecNum] Result of the PMT calculation
+    # @api public
+    attr_reader :result
+
+    # Create a new object for calculating the periodic payment of an ordinary annuity
+    # @param [Numeric] rate The discount (interest) rate
+    # @param [Numeric] num_periods The number of payments to be made
+    # @param [Numeric] present_value The current value of the annuity 
+    # @param [Numeric] future_value The ending value of the annuity
+    # @param [Boolean] pay_at_beginning. Whether the payment is made at the beginning
+    #   of the period (true) or end of the period (false) 
+    # @return [FinancialCalculator::Npv] An instance of a PMT calculation
+    def initialize(rate, num_periods, present_value, future_value = 0, pay_at_beginning = false)
+      validate_numerics(rate: rate, num_periods: num_periods, present_value: present_value, future_value: future_value)
+
+      @rate             = Flt::DecNum(rate.to_s)
+      @num_periods          = Flt::DecNum(num_periods.to_s)
+      @present_value    = Flt::DecNum(present_value.to_s)
+      @future_value     = Flt::DecNum(future_value || "0")
+      @pay_at_beginning = pay_at_beginning || false
+      @result           = solve(@rate, @num_periods, @present_value, @future_value, @pay_at_beginning)
+    end
+
+    # @return [Boolean] Whether the payments are made at the beginning of each period
+    # @api public
+    def pays_at_beginning?
+      @pay_at_beginning
+    end
+
+    def inspect
+      "PMT(#{result})"
+    end
+
+    private
+
+    def solve(i, nper, pv, fv, pay_at_beginning)
+      type = pay_at_beginning ? 1 : 0
+      @result = ((pv * (1 + i) ** nper) + fv) * i / ((1 + i * type) * (1 - (1 + i) ** nper))
+    end
+  end
+end

data/lib/financial_calculator/pv.rb

@@ -1,6 +1,7 @@
 module FinancialCalculator
   # Calculate the future value of a series of equal of payments
   class Pv
+    include ::Validator
 
     # @return [Numeric] The discount rate used in the calculation
     attr_reader :rate
@@ -71,14 +72,6 @@ module FinancialCalculator
       return 0 if amount.zero?
       amount / (1 + rate) ** periods 
     end
-
-    def validate_numerics(numerics)
-      numerics.each do |key, value|
-        unless value.is_a? Numeric
-          raise ArgumentError.new("#{key} must be a type of Numeric. Got #{value.class} instead.")
-        end
-      end
-    end
   end
 
   PresentValue = Pv

data/lib/financial_calculator/validator.rb

@@ -0,0 +1,10 @@
+module Validator
+  protected 
+  def validate_numerics(numerics)
+    numerics.each do |key, value|
+      unless value.is_a? Numeric
+        raise ArgumentError.new("#{key} must be a type of Numeric. Got #{value.class} instead.")
+      end
+    end
+  end
+end

data/lib/financial_calculator/version.rb

@@ -1,3 +1,3 @@
 module FinancialCalculator
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 end

data/spec/pmt_spec.rb

@@ -0,0 +1,71 @@
+require_relative 'spec_helper'
+
+describe "Pmt" do
+  let(:rate)      { 0.1 }
+  let(:present_value) { 1000 }
+  let(:num_periods)       { 20 }
+  let(:future_value)  { 0 }
+  let(:pay_at_beginning) { false }
+  let(:pmt)       { Pmt.new(rate, num_periods, present_value, future_value, pay_at_beginning) }
+
+  subject { pmt }
+
+  it 'has a rate attribute' do
+    expect(subject).to have_attributes(rate: rate)
+  end
+
+  it 'has a num_periods attribute' do
+    expect(subject).to have_attributes(num_periods: num_periods)
+  end
+
+  it 'has a present_value attribute' do
+    expect(subject).to have_attributes(present_value: present_value)
+  end
+
+  it 'has a future_value attribute' do
+    expect(subject).to have_attributes(future_value: future_value)
+  end
+
+  it 'has a pays_at_beginning? attribute that defaults to false' do
+    expect(subject).to have_attributes(pays_at_beginning?: false)
+  end
+
+  it 'has a result attribute' do
+    expect(subject.result).to be_a Numeric
+  end
+
+  context 'when payments occur at the beginning of each period' do
+    let(:pay_at_beginning) { true }
+    it { is_expected.to have_attributes(pays_at_beginning?: true) }
+  end
+
+  context 'when given a non-numeric rate' do
+    let(:rate) { 'string' }
+    it_behaves_like 'it has invalid arguments'
+  end
+
+  context 'when given a non-numeric number of periods' do
+    let(:num_periods) { 'string' }
+    it_behaves_like 'it has invalid arguments'
+  end
+
+  context 'when given a non-numeric present value' do
+    let(:present_value) { 'string' }
+    it_behaves_like 'it has invalid arguments'
+  end
+
+  context 'when give a non-numeric future value' do
+    let(:future_value) { 'string' }
+    it_behaves_like 'it has invalid arguments'
+  end
+
+  describe '#inspect' do
+    subject { pmt.inspect }
+
+    it { is_expected.to be_a String }
+    it { is_expected.to include 'PMT' }
+    it 'includes the result of the PMT calculation' do
+      expect(subject).to include pmt.result.to_s
+    end
+  end
+end

data/spec/pv_spec.rb

@@ -1,10 +1,10 @@
 require_relative 'spec_helper'
 
-shared_examples_for 'it has invalid present value arguments' do
-  it 'raises an ArgumentError' do
-    expect { subject }.to raise_error ArgumentError
-  end
-end
+# shared_examples_for 'it has invalid arguments' do
+#   it 'raises an ArgumentError' do
+#     expect { subject }.to raise_error ArgumentError
+#   end
+# end
 
 describe "Pv" do
   let(:rate)              { 0.1 }
@@ -58,22 +58,22 @@ describe "Pv" do
 
   context 'when the number of periods is negative' do
     let(:num_periods) { -1 }
-    it_behaves_like 'it has invalid present value arguments'
+    it_behaves_like 'it has invalid arguments'
   end
 
   context 'when rate is non-numeric' do
     let(:rate) { 'string' }
-    it_behaves_like 'it has invalid present value arguments'
+    it_behaves_like 'it has invalid arguments'
   end
 
   context 'when num_periods is non-numeric' do
     let(:num_periods) { 'string' }
-    it_behaves_like 'it has invalid present value arguments'
+    it_behaves_like 'it has invalid arguments'
   end
 
   context 'when payment is non-numeric' do
     let(:payment) { 'string' }
-    it_behaves_like 'it has invalid present value arguments'
+    it_behaves_like 'it has invalid arguments'
   end
 
   context 'when future_values non-numeric' do
@@ -81,7 +81,7 @@ describe "Pv" do
     
     subject { Pv.new(rate, num_periods, payment, future_value) }
 
-    it_behaves_like 'it has invalid present value arguments'
+    it_behaves_like 'it has invalid arguments'
   end
 
   context 'when the number of periods is 0' do

data/spec/spec_helper.rb

@@ -21,4 +21,10 @@ shared_examples_for 'the values do not converge' do
   it 'should raise an ArgumentError' do
     expect { subject }.to raise_error ArgumentError
   end
+end
+
+shared_examples_for 'it has invalid arguments' do
+  it 'raises an ArgumentError' do
+    expect { subject }.to raise_error ArgumentError
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: financial_calculator
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Mike Falzone
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-12 00:00:00.000000000 Z
+date: 2018-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: flt
@@ -162,15 +162,18 @@ files:
 - lib/financial_calculator/amortization.rb
 - lib/financial_calculator/irr.rb
 - lib/financial_calculator/npv.rb
+- lib/financial_calculator/pmt.rb
 - lib/financial_calculator/pv.rb
 - lib/financial_calculator/rates.rb
 - lib/financial_calculator/transaction.rb
+- lib/financial_calculator/validator.rb
 - lib/financial_calculator/version.rb
 - lib/financial_calculator/xirr.rb
 - lib/financial_calculator/xnpv.rb
 - spec/amortization_spec.rb
 - spec/irr_spec.rb
 - spec/npv_spec.rb
+- spec/pmt_spec.rb
 - spec/pv_spec.rb
 - spec/rates_spec.rb
 - spec/spec_helper.rb
@@ -207,6 +210,7 @@ test_files:
 - spec/amortization_spec.rb
 - spec/irr_spec.rb
 - spec/npv_spec.rb
+- spec/pmt_spec.rb
 - spec/pv_spec.rb
 - spec/rates_spec.rb
 - spec/spec_helper.rb