fat_period 2.1.0 → 3.1.0

data/Rakefile

@@ -1,9 +1,29 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
 
-require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => [:spec, :rubocop]
+require 'gem_docs'
+GemDocs.install
+
+########################################################################
+# Rubocop tasks
+########################################################################
+# Option A (recommended): Keep using Bundler and run rubocop via `bundle exec`.
+# This wrapper task ensures the rubocop run uses the gems from your Gemfile,
+# even when you invoke `rake rubocop` (no need to remember `bundle exec rake`).
+#
+# You can pass extra RuboCop CLI flags with the RUBOCOP_OPTS environment variable:
+#   RUBOCOP_OPTS="--format simple" rake rubocop
+
+desc 'Run rubocop under `bundle exec`'
+task :rubocop do
+  opts = (ENV['RUBOCOP_OPTS'] || '').split
+  Bundler.with_unbundled_env do
+    sh 'bundle', 'exec', 'rubocop', *opts
+  end
+end
+
+task default: %i[spec rubocop]

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'fat_period'

data/fat_period.gemspec

@@ -1,6 +1,6 @@
-# coding: utf-8
+# frozen_string_literal: true
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'fat_period/version'
 
@@ -21,5 +21,6 @@ Gem::Specification.new do |spec|
   # spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'fat_core', '>= 5.4'
+  spec.add_dependency 'fat_core', '>= 7.0'
+  spec.add_dependency 'fat_date'
 end

data/lib/fat_period/date.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatPeriod
   # An extension of Date for methods useful with respect to FatPeriod::Periods.
   module Date
@@ -21,9 +23,5 @@ module FatPeriod
   end
 end
 
-# An extension Date for methods useful with respect to FatPeriod::Periods.
-class Date
-  include FatPeriod::Date
-  # @!parse include FatPeriod::Date
-  # @!parse extend FatPeriod::Date::ClassMethods
-end
+# Add the period helpers to Ruby's Date class.
+Date.include(FatPeriod::Date)

data/lib/fat_period/period.rb

@@ -1,5 +1,7 @@
-require 'active_support'
-require 'fat_core/date'
+# frozen_string_literal: true
+
+require 'fat_date'
+require 'bigdecimal'
 
 # The Period class represents a range of Dates and supports a variety of
 # operations on those ranges.
@@ -41,7 +43,7 @@ class Period
   # @group Parsing
   #
   # Return a period based on two date specs passed as strings (see
-  # `FatCore::Date.parse_spec`), a 'from' and a 'to' spec. The returned period
+  # `FatCore::Date.spec`), a 'from' and a 'to' spec. The returned period
   # begins on the first day of the period given as the `from` spec and ends on
   # the last day given as the `to` spec. If the to spec is not given or is nil,
   # the from spec is used for both the from- and to-spec.
@@ -52,15 +54,15 @@ class Period
   #   # Assuming this executes in December, 2014
   #   Period.parse('last_month', 'this_month').inspect #=> Period('2014-11-01..2014-12-31')
   #
-  # @param from [String] spec ala FatCore::Date.parse_spec
-  # @param to [String] spec ala FatCore::Date.parse_spec
+  # @param from [String] spec ala FatCore::Date.spec
+  # @param to [String] spec ala FatCore::Date.spec
   # @return [Period] from beginning of `from` to end of `to`
   def self.parse(from, to = nil)
     raise ArgumentError, 'Period.parse missing argument' unless from
 
     to ||= from
-    first = Date.parse_spec(from, :from)
-    second = Date.parse_spec(to, :to)
+    first = Date.spec(from, :from)
+    second = Date.spec(to, :to)
     Period.new(first, second) if first && second
   end
 
@@ -75,10 +77,11 @@ class Period
   # @param prd [String|Period] or any candidate for conversion to Period
   # @return Period correspondign to prd parameter
   def self.ensure(prd)
-    prd.to_period if prd.respond_to?(:to_period)
+    return prd.to_period if prd.respond_to?(:to_period)
+
     case prd
     when String
-      if prd.match(/from|to/i)
+      if prd.match?(/from|to/i)
         Period.parse_phrase(prd).first
       else
         Period.parse(prd)
@@ -110,13 +113,13 @@ class Period
     phrase = phrase.clean
     case phrase
     when /\Afrom\s+([^\s]+)\s+to\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
-      from_phrase = $1
-      to_phrase = $2
+      from_phrase = ::Regexp.last_match(1)
+      to_phrase = ::Regexp.last_match(2)
     when /\Afrom\s+([^\s]+)(\s+per\s+[^\s]+)?\z/, /\Ato\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
-      from_phrase = $1
+      from_phrase = ::Regexp.last_match(1)
       to_phrase = nil
     when /\A([^\s]+)(\s+per\s+[^\s]+)?\z/
-      from_phrase = $1
+      from_phrase = ::Regexp.last_match(1)
       to_phrase = nil
     else
       raise ArgumentError, "unintelligible period phrase: '#{phrase}''"
@@ -183,7 +186,7 @@ class Period
     "Period(#{first.iso}..#{last.iso})"
   end
 
-  # Allow erb documents can directly interpolate ranges
+  # Allow erb documents to directly interpolate ranges
   def tex_quote
     "#{first.iso}--#{last.iso}"
   end
@@ -205,11 +208,6 @@ class Period
     [first, last] <=> [other.first, other.last]
   end
 
-  # Comparable does not include this.
-  def !=(other)
-    !(self == other)
-  end
-
   # Return the hash value for this Period.  Make Period's with identical
   # values test eql? so that they may be used as hash keys.
   #
@@ -224,18 +222,6 @@ class Period
     hash == other.hash
   end
 
-  # Return whether this Period contains the given date.
-  #
-  # @param date [Date] date to test
-  # @return [Boolean] is the given date within this Period?
-  def contains?(date)
-    date = date.to_date if date.respond_to?(:to_date)
-    raise ArgumentError, 'argument must be a Date' unless date.is_a?(Date)
-
-    to_range.cover?(date)
-  end
-  alias_method :===, :contains?
-
   include Enumerable
 
   # @group Enumeration
@@ -347,38 +333,47 @@ class Period
 
   # Return a period representing a chunk containing a given Date.
   def self.day_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date, date)
   end
 
   def self.week_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_week, date.end_of_week)
   end
 
   def self.biweek_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_biweek, date.end_of_biweek)
   end
 
   def self.semimonth_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_semimonth, date.end_of_semimonth)
   end
 
   def self.month_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_month, date.end_of_month)
   end
 
   def self.bimonth_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_bimonth, date.end_of_bimonth)
   end
 
   def self.quarter_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_quarter, date.end_of_quarter)
   end
 
   def self.half_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_half, date.end_of_half)
   end
 
   def self.year_containing(date)
+    date = Date.ensure_date(date)
     Period.new(date.beginning_of_year, date.end_of_year)
   end
 
@@ -628,8 +623,7 @@ class Period
   # @param round_up_last [Boolean] allow the last period in the returned array
   #   to extend beyond the end of self.
   # @return [Array<Period>] periods that subdivide self into chunks of size, `size`
-  def chunks(size: :month, partial_first: true, partial_last: true,
-    round_up_last: false)
+  def chunks(size: :month, partial_first: true, partial_last: true, round_up_last: false)
     chunk_size = size.to_sym
     raise ArgumentError, "unknown chunk size '#{chunk_size}'" unless CHUNKS.include?(chunk_size)
 
@@ -819,6 +813,19 @@ class Period
     to_range.overlaps?(other.to_range)
   end
 
+  # @group Coverage
+
+  # Return whether this Period contains the given date.
+  #
+  # @param date [Date] date to test
+  # @return [Boolean] is the given date within this Period?
+  def contains?(date)
+    date = Date.ensure(date)
+
+    to_range.cover?(date)
+  end
+  alias_method :===, :contains?
+
   # Return whether any of the given periods overlap any other.
   #
   # @example
@@ -894,4 +901,212 @@ class Period
     to_range.gaps(periods.map(&:to_range))
       .map { |r| Period.new(r.first, r.last) }
   end
+
+  # Return the fraction of a whole year represented by the part of this Period
+  # from its beginning to the given date2, following the day-count convention,
+  # convention.
+  #
+  # This Period is assumed to represent an entire accrual period, for example,
+  # a whole month for a loan, or a whole quarter or semi-year for a bond.  We
+  # infer the annual frequency of payments from the length of this Period.
+  #
+  # Return the fraction of the year that has elapsed on date2, typically the
+  # settlement date.
+  #
+  # - ~first~ :: is the date on which interest accrual begins
+  # - ~date2~ :: is the date when payment of interest is made,
+  # - ~last~ :: is the date on which the interest accrual period ends,
+  #   usually irrelevant unless actual days in period are considered
+  #
+  # The ~convention~ is the day-count convention to be used.
+  #
+  # That is, the convention for how interest is calculated between
+  # interest payment dates.  This has to do with the fraction by which the
+  # annual interest or coupon rate is multiplied to pay for a partial
+  # period.  The numerator is the number of days that have elapsed; The
+  # denominator is the number of days in the entire year.  These involve
+  # assumptions about the number of days in the months that fall within
+  # the partial period.  They will assume either that every month consists
+  # of 30 days, even if the particular period in which the payment occurs
+  # contains February, July, and August, or they will take into account
+  # the actual number of days in the particular period.
+  #
+  # | ~convention~ | Description        | Source                             |
+  # |--------------+--------------------+------------------------------------|
+  # | 0            | 30/360 Bond        | ISDA 2006 Section 4.16(f)          |
+  # | 1            | 30/360 US          | ISDA 2006 Section 4.16(f) (Note A) |
+  # | 2            | 30E/360            | ISDA 2006 Section 4.16(g)          |
+  # | 3            | 30E/360 ISDA       | ISDA 2006 Section 4.16(h)          |
+  # | 4            | Actual/actual ICMA | ISDA 2006 Section 4.16(c)          |
+  # | 5            | Actual/actual ISDA | ISDA 2006 Section 4.16(b)          |
+  # | 6            | Actual/365 Fixed   | ISDA 2006 Section 4.16(d)          |
+  # | 7            | Actual/360         | ISDA 2006 Section 4.16(e)          |
+  # | 8            | Actual/364         |                                    |
+  # | 9            | Actual/365L        | ICMA Rule 251.1(i)                 |
+  # | 10           | Actual/Actual AFB  |                                    |
+  # | 11           | 1/1                | ISDA 2006 Section 4.16(a)          |
+  #
+  # Source: https://en.wikipedia.org/wiki/Day_count_convention
+  #
+  # Unlike Period#size, day counts use elapsed days, without adding one.
+  # For ICMA, first and last are consecutive coupon boundaries; only regular
+  # coupon periods are supported. Settlement must lie within this Period.
+  # Actual/365L uses the settlement date to determine its denominator, following
+  # the reference above. Convention 11 (1/1) always returns one, even for equal dates.
+  # AFB counts whole years backwards, with the February month-end adjustment
+  # used by QuantLib, then counts the remaining days (start included, end excluded).
+  #
+  # @param date2 [Date, String] payment or settlement date within this Period
+  # @param convention [Integer] day-count convention, 0 through 11; defaults to 1 (30/360 US)
+  # @param eom [Boolean] apply February end-of-month rules for convention 1
+  # @param maturity_date [Date, String, nil] final maturity for convention 3
+  # @return [BigDecimal] accrued fraction of a year
+  def year_fraction(date2, convention: 1, eom: true, maturity_date: nil)
+    unless convention.is_a?(Integer) && (0..11).cover?(convention)
+      raise ArgumentError, 'convention must be an integer 0..11'
+    end
+
+    date1 = first
+    date2 = Date.ensure(date2)
+    unless (first..last).cover?(date2)
+      raise ArgumentError, 'settlement date must lie within the period'
+    end
+
+    maturity_date = Date.ensure(maturity_date) if maturity_date
+    return BigDecimal(1) if convention == 11
+    return BigDecimal(0) if date1 == date2
+
+    if (0..3).cover?(convention)
+      # 360-day methods
+      y1 = date1.year
+      m1 = date1.month
+      d1 = date1.day
+      y2 = date2.year
+      m2 = date2.month
+      d2 = date2.day
+      case convention
+      when 0
+        # 30/360 Bond
+        d1 = [d1, 30].min
+        d2 = d1 > 29 ? [d2, 30].min : d2
+      when 1
+        # 30/360 US
+        if eom && date1.end_of_month? && m1 == 2 && date2.end_of_month? && m2 == 2
+          d2 = 30
+        end
+        if eom && date1.end_of_month? && m1 == 2
+          d1 = 30
+        end
+        # If D2 is 31 and D1 is 30 or 31, then change D2 to 30.
+        if d2 == 31 && (d1 == 30 || d1 == 31)
+          d2 = 30
+        end
+        # If D1 is 31, then change D1 to 30.
+        if d1 == 31
+          d1 = 30
+        end
+      when 2
+        # 30E/360
+        # If D1 is 31, then change D1 to 30.
+        if d1 == 31
+          d1 = 30
+        end
+        # If D2 is 31, then change D2 to 30.
+        if d2 == 31
+          d2 = 30
+        end
+      when 3
+        # 30E/360 ISDA
+        if date1.end_of_month?
+          d1 = 30
+        end
+        if date2.end_of_month? && !(m2 == 2 && maturity_date && date2 == maturity_date)
+          # If D2 is the last day of the month (unless Date2 is the maturity
+          # date and M2 is February), then change D2 to 30.
+          d2 = 30
+        end
+      end
+      num = 360 * (y2 - y1) + 30 * (m2 - m1) + (d2 - d1)
+      return BigDecimal(num) / 360
+    end
+
+    num = BigDecimal((date2 - date1).to_i)
+    case convention
+    when 4
+      # Actual/actual ICMA: elapsed days in the reference coupon period.
+      num / (freq_per_year(days: (last - first).to_i) * (last - first).to_i)
+    when 5
+      # Actual/actual ISDA: split only the elapsed interval at year boundaries.
+      frac = BigDecimal(0)
+      cursor = date1
+      while cursor < date2
+        boundary = [Date.new(cursor.year + 1, 1, 1), date2].min
+        frac += BigDecimal((boundary - cursor).to_i) / (cursor.leap? ? 366 : 365)
+        cursor = boundary
+      end
+      frac
+    when 6
+      num / 365
+    when 7
+      num / 360
+    when 8
+      num / 364
+    when 9
+      # Actual/365L: annual coupons exclude the start and include the end
+      # when looking for February 29. Other frequencies use the settlement year.
+      leap =
+        if freq_per_year(days: (last - first).to_i) == 1
+          (first.year..date2.year).any? do |year|
+            Date.leap?(year) && first < Date.new(year, 2, 29) && Date.new(year, 2, 29) <= date2
+          end
+        else
+          date2.leap?
+        end
+      num / (leap ? 366 : 365)
+    when 10
+      # Actual/actual AFB: whole years plus the remaining fraction.
+      years = 0
+      remainder_end = date2
+      loop do
+        previous = remainder_end << 12
+        previous += 1 if previous.month == 2 && previous.day == 28 && previous.leap?
+        break if previous < date1
+
+        years += 1
+        remainder_end = previous
+      end
+      leap = (date1.year..remainder_end.year).any? do |year|
+        Date.leap?(year) && date1 <= Date.new(year, 2, 29) && Date.new(year, 2, 29) < remainder_end
+      end
+      years + BigDecimal((remainder_end - date1).to_i) / (leap ? 366 : 365)
+    end
+  end
+
+  # Infer payment frequency from the period length, allowing the same tolerance
+  # as chunk_name. Daily periods use the number of days in the starting year.
+  # @param days [Integer] period length; use elapsed days for coupon boundaries
+  def freq_per_year(days: length)
+    case Period.days_to_chunk(days)
+    when :year
+      1
+    when :half
+      2
+    when :quarter
+      4
+    when :bimonth
+      6
+    when :month
+      12
+    when :semimonth
+      24
+    when :biweek
+      26
+    when :week
+      52
+    when :day
+      first.leap? ? 366 : 365
+    else
+      raise ArgumentError, "indeterminate size of period (#{self})"
+    end
+  end
 end

data/lib/fat_period/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatPeriod
-  VERSION = '2.1.0'.freeze
+  VERSION = '3.1.0'
 end

data/lib/fat_period.rb

@@ -1,9 +1,29 @@
-require 'date'
+# frozen_string_literal: true
 
-require 'fat_period/version'
-require 'fat_period/date'
-require 'fat_period/period'
+require 'date'
+require 'active_support'
 
-require 'fat_core/date'
 require 'fat_core/range'
 require 'fat_core/string'
+require 'fat_date'
+
+# Gem Overview (extracted from README.org by gem_docs)
+#
+# * Introduction
+# ~FatPeriod~ provides a Ruby ~Period~ class for dealing with time periods of
+# days, that is ranges whose endpoints are of class ~Date~.  It's target is
+# financial applications, but it serves well for any application where periods
+# of time are useful.  It builds on the [[https://github.com/ddoherty03/fat_date][fat_date]] gem, which provides
+# enhancements to the ~Date~ class, especially its class method ~Date.spec~ for
+# interpreting a rich set of "specs" as the beginning or end of a variety of
+# calendar-related periods.
+#
+# In addition, set operations are provided for Period, as well as methods for
+# breaking a larger periods into an array of smaller periods of various 'chunk'
+# sizes that correspond to calendar-related periods such as days, weeks, months,
+# and so forth.
+module FatPeriod
+  require 'fat_period/version'
+  require 'fat_period/date'
+  require 'fat_period/period'
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_period
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Daniel E. Doherty
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fat_core
@@ -16,15 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
-description:
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: fat_date
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - ded@ddoherty.net
 executables: []
@@ -32,12 +44,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
-- ".github/workflows/gem-push.yml"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
+- ".rubocop.yml"
+- CHANGELOG.org
 - Gemfile
 - LICENSE.txt
+- README.md
 - README.org
 - Rakefile
 - bin/console
@@ -50,7 +64,6 @@ files:
 homepage: https://github.com/ddoherty03/fat_period
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -65,8 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Implements a Period class as a Range of Dates.
 test_files: []

data/.github/workflows/gem-push.yml

@@ -1,48 +0,0 @@
-name: Ruby Gem
-
-on:
-  push:
-    branches: [ "master" ]
-  pull_request:
-    branches: [ "master" ]
-
-jobs:
-  build:
-    name: Build + Publish
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby 2.6
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-    # uses: ruby/setup-ruby@v1
-      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
-      with:
-        ruby-version: 2.6.x
-
-    - name: Publish to GPR
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
-      env:
-        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
-        OWNER: ${{ github.repository_owner }}
-
-    - name: Publish to RubyGems
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push *.gem
-      env:
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.travis.yml

@@ -1,6 +0,0 @@
-language: ruby
-rvm:
-  - 2.5
-  - 2.6
-  - 2.7
-  - 3.0