xirr 0.7.1 → 1.0.0

data/test/test_solver_properties.rb

@@ -0,0 +1,135 @@
+require_relative 'test_helper'
+
+# Property and stress tests for the rtsafe solver. These are the tests that would
+# catch a bracketing or overflow regression: they assert the invariant a solver
+# must satisfy — the returned rate sits within one precision-step of a genuine
+# sign change of the net present value — rather than a hand-computed number.
+describe 'rtsafe solver properties' do
+  # The rounding granularity of a converged result.
+  H = 10.0**(-Xirr.config.precision)
+
+  # The returned rate is a real root to the configured precision when the NPV
+  # changes sign across [rate - H, rate + H] (or is already ~0 there). This holds
+  # regardless of the flow's magnitude or maturity, so it doubles as the property
+  # assertion and the stress-case assertion.
+  def assert_root(cf, rate)
+    here = cf.xnpv(rate)
+    lo   = cf.xnpv(rate - H)
+    hi   = cf.xnpv(rate + H)
+    straddles = (lo <= 0 && hi >= 0) || (lo >= 0 && hi <= 0)
+    assert straddles || here.abs < 1e-6,
+           "rate #{rate} is not a root to precision #{Xirr.config.precision}: " \
+           "xnpv(r-H)=#{lo}, xnpv(r)=#{here}, xnpv(r+H)=#{hi}"
+  end
+
+  # A valid, single-sign-change cashflow: an initial outlay followed by returns.
+  def random_cashflow(rng)
+    cf   = Cashflow.new
+    base = Date.new(2000, 1, 1)
+    cf << Transaction.new(-(1_000 + rng.rand(9_000)), date: base)
+    n = 1 + rng.rand(10)
+    (1..n).each do |i|
+      days = i * (30 + rng.rand(400))
+      cf << Transaction.new(rng.rand(3_500) - 800, date: base + days)
+    end
+    # Guarantee at least one inflow so the series changes sign.
+    cf << Transaction.new(500 + rng.rand(6_000), date: base + (n + 1) * 400)
+    cf
+  end
+
+  it 'returns a genuine root for random cashflows' do
+    rng     = Random.new(0xC0FFEE)
+    checked = 0
+    300.times do
+      cf = random_cashflow(rng)
+      next unless cf.valid?
+
+      rate =
+        begin
+          cf.xirr!(method: :rtsafe)
+        rescue ArgumentError
+          next # genuine non-convergence, nothing to assert about
+        end
+
+      assert_root(cf, rate)
+      checked += 1
+    end
+    assert checked > 100, "property test was nearly vacuous: only #{checked} cases checked"
+  end
+
+  it 'agrees with bisection and newton on a well-behaved flow' do
+    cf = Cashflow.new
+    cf << Transaction.new(1000, date: '1985-01-01'.to_date)
+    cf << Transaction.new(-600, date: '1990-01-01'.to_date)
+    cf << Transaction.new(-6000, date: '1995-01-01'.to_date)
+    assert_in_delta cf.xirr(method: :bisection).to_f, cf.xirr(method: :rtsafe).to_f, 1e-5
+    assert_in_delta cf.xirr(method: :newton_method).to_f, cf.xirr(method: :rtsafe).to_f, 1e-5
+  end
+
+  describe 'stress cases' do
+    it 'handles a 30-year monthly schedule (long maturity, low per-period rate)' do
+      cf   = Cashflow.new
+      base = Date.new(1990, 1, 1)
+      cf << Transaction.new(-100_000, date: base)
+      360.times { |m| cf << Transaction.new(650, date: base >> (m + 1)) }
+      rate = cf.xirr!(method: :rtsafe)
+      assert rate > 0, "expected a positive rate, got #{rate}"
+      assert_root(cf, rate)
+    end
+
+    it 'handles a near -100% return without overflowing' do
+      cf = Cashflow.new
+      cf << Transaction.new(-10_000, date: '2014-04-15'.to_date)
+      cf << Transaction.new(305.6, date: '2014-05-15'.to_date)
+      cf << Transaction.new(500, date: '2014-10-19'.to_date)
+      rate = cf.xirr!(method: :rtsafe)
+      assert rate < -0.9, "expected a rate near -1, got #{rate}"
+      assert rate > -1.0
+    end
+
+    it 'handles a very long, low-rate horizon' do
+      cf = Cashflow.new flow: [
+        Transaction.new(-1000, date: Date.new(1957, 1, 1)),
+        Transaction.new(390_000, date: Date.new(2013, 1, 1))
+      ]
+      assert_in_delta 0.112339, cf.xirr!(method: :rtsafe).to_f, 1e-5
+    end
+
+    it 'reports non-convergence rather than crashing on an impossible bracket' do
+      # One day apart with an enormous return: the root is astronomically high and
+      # lies outside any sane bracket, so rtsafe gives up cleanly.
+      cf = Cashflow.new
+      cf << Transaction.new(1000, date: '1985-01-01'.to_date)
+      cf << Transaction.new(-6000, date: '1985-01-02'.to_date)
+      assert_raises(ArgumentError) { cf.xirr!(method: :rtsafe) }
+    end
+
+    it 'the native rtsafe_c matches the pure-Ruby rtsafe' do
+      skip 'native extension not compiled' unless Xirr::NATIVE
+      rng = Random.new(0xBEEF)
+      50.times do
+        cf = random_cashflow(rng)
+        next unless cf.valid?
+        assert_equal cf.xirr(method: :rtsafe), cf.xirr(method: :rtsafe_c)
+      end
+    end
+
+    it 'raises a clear error when rtsafe_c is chosen without the extension' do
+      skip 'extension is compiled here' if Xirr::NATIVE
+      cf = Cashflow.new
+      cf << Transaction.new(-1000, date: '2014-01-01'.to_date)
+      cf << Transaction.new(1100, date: '2015-01-01'.to_date)
+      assert_raises(ArgumentError) { cf.xirr(method: :rtsafe_c) }
+    end
+
+    it 'newton does not crash when a guess overshoots below -100%' do
+      # A Newton step from this guess drives the rate below -1, where the
+      # discount base goes negative; the solver must bail, not raise.
+      cf = Cashflow.new
+      cf << Transaction.new(-10_000, date: '2014-04-15'.to_date)
+      cf << Transaction.new(305.6, date: '2014-05-15'.to_date)
+      cf << Transaction.new(500, date: '2014-10-19'.to_date)
+      assert_equal Xirr::REPLACE_FOR_NIL, cf.xirr(method: :newton_method, guess: 0.1)
+    end
+  end
+end

data/test/test_transactions.rb

@@ -6,10 +6,10 @@ describe 'Transaction' do
   end
 
   it 'converts amount to float' do
-    assert true, @t.amount.kind_of?(Float)
+    assert_kind_of Float, @t.amount
   end
 
-  it 'retreives the date' do
+  it 'retrieves the date' do
     assert_equal Date.today, @t.date
   end
 

data/test/test_tvm.rb

@@ -0,0 +1,69 @@
+require_relative 'test_helper'
+
+describe 'Xirr::TVM' do
+  it 'fv — future value' do
+    assert_in_delta 2886.68, Xirr::TVM.fv(0.05, 10, -100, -1000).round(2), 1e-2
+  end
+
+  it 'pv — present value' do
+    assert_in_delta 1386.09, Xirr::TVM.pv(0.05, 10, -100, -1000).round(2), 1e-2
+  end
+
+  it 'pmt — level payment' do
+    assert_in_delta(-162.75, Xirr::TVM.pmt(0.10, 10, 1000).round(2), 1e-2)
+  end
+
+  it 'ipmt — interest portion' do
+    assert_in_delta(-8.333333, Xirr::TVM.ipmt(0.10 / 12, 1, 12, 1000), 1e-6)
+  end
+
+  it 'ppmt — principal portion' do
+    assert_in_delta(-79.582554, Xirr::TVM.ppmt(0.10 / 12, 1, 12, 1000), 1e-6)
+  end
+
+  it 'ipmt + ppmt equals pmt for every period' do
+    payment = Xirr::TVM.pmt(0.10 / 12, 12, 1000)
+    (1..12).each do |per|
+      split = Xirr::TVM.ipmt(0.10 / 12, per, 12, 1000) + Xirr::TVM.ppmt(0.10 / 12, per, 12, 1000)
+      assert_in_delta payment, split, 1e-9
+    end
+  end
+
+  it 'nper — number of periods' do
+    assert_in_delta 14.21, Xirr::TVM.nper(0.05, -100, 1000).round(2), 1e-2
+  end
+
+  it 'rate — solves for the periodic rate' do
+    assert_equal 0.0, Xirr::TVM.rate(10, -100, 1000)
+  end
+
+  it 'validates the type argument' do
+    assert_raises(ArgumentError) { Xirr::TVM.fv(0.05, 10, -100, -1000, 2) }
+  end
+
+  it 'handles annuity due (type 1)' do
+    # A due payment is the ordinary payment discounted one period earlier.
+    ordinary = Xirr::TVM.pmt(0.10, 10, 1000, 0, 0)
+    due = Xirr::TVM.pmt(0.10, 10, 1000, 0, 1)
+    assert_in_delta ordinary / 1.10, due, 1e-9
+  end
+
+  describe 'amortization_schedule' do
+    before do
+      @schedule = Xirr::TVM.amortization_schedule(0.10 / 12, 12, 1000)
+    end
+
+    it 'has a correct first row' do
+      first = @schedule.first
+      assert_equal(-87.92, first[:payment])
+      assert_equal(-8.33, first[:interest])
+      assert_equal(-79.59, first[:principal])
+      assert_equal 920.41, first[:balance]
+    end
+
+    it 'pays the balance down to exactly zero' do
+      assert_equal 0.0, @schedule.last[:balance]
+      assert_equal 12, @schedule.length
+    end
+  end
+end

data/xirr.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version     = Xirr::VERSION
   spec.authors     = ['tubedude']
   spec.email       = ['beto@trevisan.me']
-  spec.summary     = %q{Calculates XIRR (Bisection and Newton method) of a cashflow}
-  spec.description = %q{Calculates IRR of a Cashflow, similar to Excel's, XIRR formula. It defaults to Newton Method, but will calculate Bisection as well.}
+  spec.summary     = %q{XIRR and a finance toolkit for Ruby, built on a safeguarded-Newton solver}
+  spec.description = %q{Calculates the XIRR of a cashflow (the internal rate of return for transactions on arbitrary dates, like Excel's XIRR) using a safeguarded-Newton solver, with an optional native C build. Also includes time-value-of-money, bond, depreciation, rate-conversion, and performance-metric functions.}
   spec.homepage    = 'https://github.com/tubedude/xirr'
   spec.license     = 'MIT'
 
@@ -18,13 +18,15 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
+  # Optional native rtsafe solver. The build is best-effort (see extconf.rb); the
+  # gem falls back to the pure-Ruby solver when it isn't compiled.
+  spec.extensions    = ['ext/xirr/extconf.rb']
+
   spec.required_ruby_version = '>=3.1'
 
   spec.add_dependency 'activesupport', '>= 6.1', '< 8'
 
-  spec.add_development_dependency 'activesupport', '>= 6.1', '< 8'
   spec.add_development_dependency 'minitest', '~> 5.14'
-  spec.add_development_dependency 'coveralls', '~> 0.8'
   spec.add_development_dependency 'bundler', '>= 2.2'
   spec.add_development_dependency 'rake', '~> 13.0'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xirr
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 1.0.0
 platform: ruby
 authors:
 - tubedude
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-19 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -30,26 +30,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -64,20 +44,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.14'
-- !ruby/object:Gem::Dependency
-  name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -106,35 +72,58 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Calculates IRR of a Cashflow, similar to Excel's, XIRR formula. It defaults
-  to Newton Method, but will calculate Bisection as well.
+description: Calculates the XIRR of a cashflow (the internal rate of return for transactions
+  on arbitrary dates, like Excel's XIRR) using a safeguarded-Newton solver, with an
+  optional native C build. Also includes time-value-of-money, bond, depreciation,
+  rate-conversion, and performance-metric functions.
 email:
 - beto@trevisan.me
 executables: []
-extensions: []
+extensions:
+- ext/xirr/extconf.rb
 extra_rdoc_files: []
 files:
-- ".coveralls.yml"
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".ruby-gemset"
 - ".ruby-version"
-- ".travis.yml"
 - CHANGE_LOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark/solvers.rb
+- ext/xirr/extconf.rb
+- ext/xirr/xirr_native.c
 - lib/xirr.rb
 - lib/xirr/base.rb
 - lib/xirr/bisection.rb
+- lib/xirr/bonds.rb
+- lib/xirr/brent.rb
 - lib/xirr/cashflow.rb
 - lib/xirr/config.rb
+- lib/xirr/depreciation.rb
 - lib/xirr/newton_method.rb
+- lib/xirr/periodic.rb
+- lib/xirr/rates.rb
+- lib/xirr/returns.rb
+- lib/xirr/rtsafe.rb
+- lib/xirr/rtsafe_c.rb
 - lib/xirr/transaction.rb
+- lib/xirr/tvm.rb
 - lib/xirr/version.rb
+- test/test_bonds.rb
+- test/test_brent.rb
 - test/test_cashflow.rb
+- test/test_depreciation.rb
 - test/test_helper.rb
+- test/test_periodic.rb
+- test/test_rates.rb
+- test/test_returns.rb
+- test/test_solver_properties.rb
 - test/test_transactions.rb
+- test/test_tvm.rb
 - xirr.gemspec
 homepage: https://github.com/tubedude/xirr
 licenses:
@@ -158,8 +147,16 @@ requirements: []
 rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
-summary: Calculates XIRR (Bisection and Newton method) of a cashflow
+summary: XIRR and a finance toolkit for Ruby, built on a safeguarded-Newton solver
 test_files:
+- test/test_bonds.rb
+- test/test_brent.rb
 - test/test_cashflow.rb
+- test/test_depreciation.rb
 - test/test_helper.rb
+- test/test_periodic.rb
+- test/test_rates.rb
+- test/test_returns.rb
+- test/test_solver_properties.rb
 - test/test_transactions.rb
+- test/test_tvm.rb

data/.coveralls.yml

@@ -1,2 +0,0 @@
-service_name: travis-ci
-repo_token: WWGlMyxTY9oj85CzGICcyYqlpXPG29UsN

data/.travis.yml

@@ -1,8 +0,0 @@
-language: ruby
-rvm:
-  - '2.6.9'
-  - '2.7.6'
-  - '3.0.4'
-  - '3.3.0'
-script:
-  - bundle exec rake test_units