fat_period 3.0.0 → 3.2.0

data/README.org

@@ -1,54 +1,28 @@
 #+TITLE: FatPeriod User Guide
 #+OPTIONS: toc:5
-#+PROPERTY: header-args:ruby :colnames no :session fat_period :hlines yes :exports both :wrap example :ruby "bundle exec irb --prompt=simple"
-#+PROPERTY: header-args:sh :exports code
 #+LATEX_HEADER: \usepackage[margin=0.75in]{geometry}
+#+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
+#+PROPERTY: header-args:ruby+ :wrap example :session fat_period_session :eval yes
+#+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fat_period'"
+#+PROPERTY: header-args:sh :exports code :eval no
+#+PROPERTY: header-args:bash :exports code :eval no
 
-[[https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml][https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml/badge.svg?branch=master]]
+#+BEGIN_EXPORT markdown
+[![CI](https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml)
+#+END_EXPORT
 
-* Setup for Code Blocks                            :noexport:
-Run this block before all others to ensure that we are reading the libraries
-from the source directory.
-
-#+begin_src ruby :results output :export no
-  Dir.chdir("/home/ded/src/fat_period")
-  puts "Current directory: #{Dir.pwd}"
-  puts "Ruby LOADPATH:"
-  $LOAD_PATH.unshift(File.expand_path("lib", Dir.pwd)) unless $:[0].match?(%r{src/fat_period/lib})
-  $:[0..10].each { |d| puts d }
-  puts "..."
-  require 'fat_period'
-#+end_src
-
-#+RESULTS:
-#+begin_example
-Current directory: /home/ded/src/fat_period
-Ruby LOADPATH:
-/home/ded/src/fat_period/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/bundler-2.6.7/lib
-/home/ded/.rbenv/rbenv.d/exec/gem-rehash
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/bundler/gems/rubocop-ddoherty-6b28e9614f18/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-shopify-2.17.1/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-rspec-3.7.0/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-rake-0.7.1/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-performance-1.26.1/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-1.81.6/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/unicode-display_width-3.2.0/lib
-/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/unicode-emoji-4.1.0/lib
-...
-#+end_example
 
 * Version
 #+begin_src ruby :wrap EXAMPLE
   "Current version is: #{FatPeriod::VERSION}"
 #+end_src
 
+#+RESULTS:
 #+begin_EXAMPLE
-Current version is: 3.0.0
+Current version is: 3.1.0
 #+end_EXAMPLE
 
 * 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
@@ -62,43 +36,6 @@ 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.
 
-* Table of Contents                                            :toc:noexport:
-- [[#version][Version]]
-- [[#introduction][Introduction]]
-- [[#installation][Installation]]
-  - [[#installing-the-gem][Installing the gem]]
-- [[#usage][Usage]]
-  - [[#constant-periodforever][Constant Period::FOREVER]]
-  - [[#construction-of-periods][Construction of Periods]]
-    - [[#periodnew][Period.new]]
-    - [[#periodparse][Period.parse]]
-      - [[#with-only-a-from-spec][With Only a From-Spec]]
-      - [[#with-both-a-from-spec-and-to-spec][With Both a From-Spec and To-Spec]]
-      - [[#using-skip-modifiers][Using Skip Modifiers]]
-    - [[#periodparse_phrase][Period.parse_phrase]]
-    - [[#periodensure][Period.ensure]]
-  - [[#conversion][Conversion]]
-    - [[#to-range][To Range]]
-    - [[#to-string][To String]]
-    - [[#tex-form][TeX Form]]
-  - [[#comparison][Comparison]]
-  - [[#enumeration][Enumeration]]
-  - [[#size][Size]]
-  - [[#chunking][Chunking]]
-  - [[#set-operations][Set Operations]]
-    - [[#subset-determination][Subset Determination]]
-    - [[#superset-determination][Superset Determination]]
-    - [[#intersection][Intersection]]
-    - [[#difference][Difference]]
-    - [[#union][Union]]
-  - [[#coverage][Coverage]]
-    - [[#contains][Contains?]]
-    - [[#overlapping][Overlapping]]
-    - [[#spanning][Spanning]]
-    - [[#gaps][Gaps]]
-- [[#development][Development]]
-- [[#contributing][Contributing]]
-
 * Installation
 
 ** Installing the gem
@@ -109,20 +46,29 @@ Add this line to your application's Gemfile:
   gem 'fat_period'
 #+END_SRC
 
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
 And then execute:
 
 #+BEGIN_SRC sh
   $ bundle
 #+END_SRC
 
+#+RESULTS:
+
 Or install it yourself as:
 
 #+BEGIN_SRC sh
   $ gem install fat_period
 #+END_SRC
 
+#+RESULTS:
+
 * Usage
-** Constant Period::FOREVER
+** Constant ~Period::FOREVER~
 
 The ~Period~ class depends on the extensions to ~Date~ made by the ~fat_core~
 gem, which you can read about [[https://github.com/ddoherty03/fat_core][here]].  It defines a constant, ~Period::FOREVER~,
@@ -132,7 +78,7 @@ the beginning of time and end of time for practical commercial purposes.  The
 constant is not frozen, so you can re-define it to your liking.
 
 ** Construction of Periods
-*** Period.new
+*** ~Period.new~
 A Period is constructed with two arguments for the begin and end date.  The
 begin date must be on or before the end date.  Each argument can be (1) a
 Date, (2) a string parseable as a Date by the Date.parse method, or (3) an
@@ -146,18 +92,22 @@ object that responds to ~#to_s~ and can be parsed as a Date by Date.parse:
 #+end_SRC
 
 #+RESULTS:
-| 2025-03-20 to 2025-04-19 |
-| 1963-11-22 to 2025-03-20 |
+#+begin_example
+| 2026-11-05 to 2026-12-05 |
+| 1963-11-22 to 2026-11-05 |
 | 1961-01-21 to 1963-11-22 |
+#+end_example
 
 #+begin_src ruby
   ["Camelot lasted #{p3.length} days"]
 #+end_src
 
 #+RESULTS:
+#+begin_example
 | Camelot lasted 1036 days |
+#+end_example
 
-*** Period.parse
+*** ~Period.parse~
 A more convenient way to construct a period is provided by ~Period.parse~.  It
 takes two strings as its arguments, a mandatory "from-spec" and an optional
 "to-spec":
@@ -181,6 +131,18 @@ overall period:
   tab
 #+end_src
 
+#+RESULTS:
+#+begin_example
+| From Spec   | Result                         |
+|-------------+--------------------------------|
+| 2020        | Period(2020-01-01..2020-12-31) |
+| 2020-2Q     | Period(2020-04-01..2020-06-30) |
+| 2020-W15    | Period(2020-04-06..2020-04-12) |
+| 2020-09     | Period(2020-09-01..2020-09-30) |
+| 2020-09-A   | Period(2020-09-01..2020-09-15) |
+| 2020-09-iii | Period(2020-09-14..2020-09-20) |
+#+end_example
+
 #+begin_example
 | From Spec   | Result                         |
 |-------------+--------------------------------|
@@ -209,6 +171,17 @@ period is the last day of the to-spec:
   tab
 #+end_src
 
+#+RESULTS:
+#+begin_example
+| From Spec | To Spec     | Result                         |
+|-----------+-------------+--------------------------------|
+| 2020      | 2020-2Q     | Period(2020-01-01..2020-06-30) |
+| 2020-2Q   | 2020-W15    | Period(2020-04-01..2020-04-12) |
+| 2020-W15  | 2020-09     | Period(2020-04-06..2020-09-30) |
+| 2020-09   | 2020-09-A   | Period(2020-09-01..2020-09-15) |
+| 2020-09-A | 2020-09-iii | Period(2020-09-01..2020-09-20) |
+#+end_example
+
 #+begin_example
 | From Spec | To Spec     | Result                         |
 |-----------+-------------+--------------------------------|
@@ -242,6 +215,7 @@ skipping forward instead.
   tab
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | From Spec | To Spec       | Result                         | Description                                                |
 |-----------+---------------+--------------------------------+------------------------------------------------------------|
@@ -251,7 +225,16 @@ skipping forward instead.
 | 2012-11   | 2012-11-4Thur | Period(2012-11-01..2012-11-22) | And through Thanksgiving (not always the /last/ Thursday!) |
 #+end_example
 
-*** Period.parse_phrase
+#+begin_example
+| From Spec | To Spec       | Result                         | Description                                                |
+|-----------+---------------+--------------------------------+------------------------------------------------------------|
+| 2025-2Q   | 2025<=Wed     | Period(2025-04-01..2025-12-31) | From 2q to last Wednesday of 2025                          |
+| 2025-2Q   | 2025<Wed      | Period(2025-04-01..2025-12-31) | From 2q to last Wednesday /before/ the end of 2025         |
+| 2012-11   | 2012-11<=Thur | Period(2012-11-01..2012-11-29) | November 2012 through last Thursday                        |
+| 2012-11   | 2012-11-4Thur | Period(2012-11-01..2012-11-22) | And through Thanksgiving (not always the /last/ Thursday!) |
+#+end_example
+
+*** ~Period.parse_phrase~
 For example:
 
 The ~Period.parse_phrase~ method will take a string having a 'from', 'to', and
@@ -275,6 +258,7 @@ as a 'from' clause.
   tab
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | k | Sub Period                     |
 |---+--------------------------------|
@@ -319,6 +303,7 @@ of the overall period.
   tab
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |  k | Sub Period                     |
 |----+--------------------------------|
@@ -364,8 +349,7 @@ of the overall period.
 | 39 | Period(2025-09-29..2025-09-30) |
 #+end_example
 
-
-*** Period.ensure
+*** ~Period.ensure~
 ~Period.ensure~ tries to interpret its argument as a ~Period~ and returns it;
 otherwise it throws an ~ArgumentError~ exception:
 
@@ -392,14 +376,16 @@ otherwise it throws an ~ArgumentError~ exception:
    Period.ensure(cm)
   #+end_src
 
-#+begin_example
-Period(2025-09-01..2025-09-30)
+  #+RESULTS:
+  #+begin_example
+  Period(2025-09-01..2025-09-30)
   #+end_example
 
 #+begin_src ruby
   Period.ensure('from 2016 to 2018-3Q')
 #+end_src
 
+#+RESULTS:
 #+begin_example
 Period(2016-01-01..2018-09-30)
 #+end_example
@@ -408,29 +394,884 @@ Period(2016-01-01..2018-09-30)
   Period.ensure(Period.new('2016-01-02', '2017-09-29'))
 #+end_src
 
+#+RESULTS:
 #+begin_example
 Period(2016-01-02..2017-09-29)
 #+end_example
 
 ** Conversion
-*** To Range
-*** To String
-*** TeX Form
+*** ~#to_range~
+~Period#to_range~ converts the ~Period~ to a ~Range~ with limits
+~first..last~.
+
+#+begin_src ruby
+  [Period.this_year.to_range.class, Period.this_year.to_range.to_s]
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Range | 2026-01-01..2026-12-31 |
+#+end_example
+
+*** ~#to_s~
+~Period#to_s~ does ~String~ conversion but using compact notation for
+years, halves, quarters, and months if possible; otherwise, it gives
+~first~ and ~last~ explicitly:
+
+#+begin_src ruby
+  specs = [
+    'from this_year',
+    'from 2026-2H',
+    'from 2026-3Q',
+    'from 2026-10',
+    'from 2026-10 to 2026-10-30'
+  ]
+  tab = []
+  tab << ['Spec', '#to_s']
+  tab << nil
+  specs.each do |s|
+    pd = Period.parse_phrase(s).first
+    tab << [s, pd.to_s]
+  end
+  tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Spec                       | #to_s                    |
+|----------------------------+--------------------------|
+| from this_year             | 2026                     |
+| from 2026-2H               | 2026-2H                  |
+| from 2026-3Q               | 2026-3Q                  |
+| from 2026-10               | 2026-10                  |
+| from 2026-10 to 2026-10-30 | 2026-10-01 to 2026-10-30 |
+#+end_example
+
+*** ~#tex_quote~
+~Period#tex_quote~ formats a period in a way suitable for TeX or LaTeX.
+Mainly, this causes it to use an "en-dash" to separate the end points
+and hyphens to separate date components.
+
+#+begin_src ruby
+  specs = [
+    'from this_year',
+    'from 2026-2H',
+    'from 2026-3Q',
+    'from 2026-10',
+    'from 2026-10 to 2026-10-30'
+  ]
+  tab = []
+  tab << ['Spec', '#to_s']
+  tab << nil
+  specs.each do |s|
+    pd = Period.parse_phrase(s).first
+    tab << [s, pd.tex_quote]
+  end
+  tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Spec                       | #to_s                  |
+|----------------------------+------------------------|
+| from this_year             | 2026-01-01--2026-12-31 |
+| from 2026-2H               | 2026-07-01--2026-12-31 |
+| from 2026-3Q               | 2026-07-01--2026-09-30 |
+| from 2026-10               | 2026-10-01--2026-10-31 |
+| from 2026-10 to 2026-10-30 | 2026-10-01--2026-10-30 |
+#+end_example
+
 ** Comparison
+The ~Period~ class includes ~Comparable~ so periods can be compared
+directly.  Period are compared by ~first~, and if those are the same,
+then by ~last~, and those using normal ~Date~ comparison.
+
+#+begin_src ruby
+  spec_pairs = [
+    ['from 2026', 'from 2026-1H'],
+    ['from 2026', 'from 2026-2H'],
+    ['from 2016-05', 'from 2016-05 to 2016-06'],
+    ['from 2026', 'from 2026-2H'],
+    ['from 2026', 'from 2025'],
+    ['from 2010-09', 'from 2010-09'],
+  ]
+  tab = []
+  tab << ['Period1', 'Period2', 'Period1 <=> Period2']
+  tab << nil
+  spec_pairs.each do |s1, s2|
+    p1 = Period.parse_phrase(s1).first
+    p2 = Period.parse_phrase(s2).first
+    tab << [p1.to_s, p2.to_s, p1 <=> p2]
+  end
+  tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Period1 | Period2                  | Period1 <=> Period2 |
+|---------+--------------------------+---------------------|
+|    2026 | 2026-1H                  | 1                   |
+|    2026 | 2026-2H                  | -1                  |
+| 2016-05 | 2016-05-01 to 2016-06-30 | -1                  |
+|    2026 | 2026-2H                  | -1                  |
+|    2026 | 2025                     | 1                   |
+| 2010-09 | 2010-09                  | 0                   |
+#+end_example
+
 ** Enumeration
-** Size
+*** ~#each~
+~Period~ includes ~Enumerable~ and defines an ~#each~ method that
+iterates through each day in the period:
+
+#+begin_src ruby
+pd = Period.parse('2024-02')
+n = 0
+tab = []
+tab << ['N', 'Day']
+tab << nil
+pd.each do |day|
+  tab << [n += 1, day.iso]
+end
+tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+|  N | Day        |
+|----+------------|
+|  1 | 2024-02-01 |
+|  2 | 2024-02-02 |
+|  3 | 2024-02-03 |
+|  4 | 2024-02-04 |
+|  5 | 2024-02-05 |
+|  6 | 2024-02-06 |
+|  7 | 2024-02-07 |
+|  8 | 2024-02-08 |
+|  9 | 2024-02-09 |
+| 10 | 2024-02-10 |
+| 11 | 2024-02-11 |
+| 12 | 2024-02-12 |
+| 13 | 2024-02-13 |
+| 14 | 2024-02-14 |
+| 15 | 2024-02-15 |
+| 16 | 2024-02-16 |
+| 17 | 2024-02-17 |
+| 18 | 2024-02-18 |
+| 19 | 2024-02-19 |
+| 20 | 2024-02-20 |
+| 21 | 2024-02-21 |
+| 22 | 2024-02-22 |
+| 23 | 2024-02-23 |
+| 24 | 2024-02-24 |
+| 25 | 2024-02-25 |
+| 26 | 2024-02-26 |
+| 27 | 2024-02-27 |
+| 28 | 2024-02-28 |
+| 29 | 2024-02-29 |
+#+end_example
+
+*** ~#size~
+~Period#size~ returns the number of days in the period.
+
+#+begin_src ruby
+Period.parse('2024-02').size
+#+end_src
+
+#+RESULTS:
+#+begin_example
+29
+#+end_example
+
 ** Chunking
+~FatPeriod~ recognizes several calendar sub-period types than the
+standard libraries do:
+
+- day
+- week
+- biweek
+- semimonth
+- month
+- bimonth
+- quarter
+- half
+- year
+
+~FatPeriod~ refers to these special kinds of periods as "chunks", and
+they are often useful in financial applications.
+
+*** ~Period.<chunk>_containing(date)~
+For each chunk, ~FatPeriod~ provides a method for returning the ~Period~
+of the size of the given chunk containing a given date.  For example, to
+find the calendar quarter containing '2016-08-04', you can call
+~Period.quarter_containing('2016-08-04')~ and get the period ~2016-3Q~.
+
+#+begin_src ruby
+  chunks = %w(
+    day
+    week
+    biweek
+    semimonth
+    month
+    bimonth
+    quarter
+    half
+    year
+)
+tab = []
+tab << ['Chunk Size', 'Containing Period']
+tab << nil
+chunks.each do |ck|
+  meth = "#{ck}_containing".to_sym
+  pd = Period.send(meth, '2016-08-04').to_s
+  tab << [ck, pd.to_s]
+end
+tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Chunk Size | Containing Period        |
+|------------+--------------------------|
+| day        | 2016-08-04 to 2016-08-04 |
+| week       | 2016-08-01 to 2016-08-07 |
+| biweek     | 2016-08-01 to 2016-08-14 |
+| semimonth  | 2016-08-01 to 2016-08-15 |
+| month      | 2016-08                  |
+| bimonth    | 2016-07-01 to 2016-08-31 |
+| quarter    | 2016-3Q                  |
+| half       | 2016-2H                  |
+| year       | 2016                     |
+#+end_example
+
+~Period~ also provides several related methods that return the
+chunk-sized period containing today's date:
+
+#+begin_src ruby
+  chunks = %w(
+    day
+    week
+    biweek
+    semimonth
+    month
+    bimonth
+    quarter
+    half
+    year
+)
+tab = []
+tab << ['Chunk Size', 'Current Period']
+tab << nil
+chunks.each do |ck|
+  meth = "this_#{ck}".to_sym
+  pd = Period.send(meth).to_s
+  tab << [ck, pd.to_s]
+end
+tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Chunk Size | Current Period           |
+|------------+--------------------------|
+| day        | 2026-11-05 to 2026-11-05 |
+| week       | 2026-11-02 to 2026-11-08 |
+| biweek     | 2026-10-26 to 2026-11-08 |
+| semimonth  | 2026-11-01 to 2026-11-15 |
+| month      | 2026-11                  |
+| bimonth    | 2026-11-01 to 2026-12-31 |
+| quarter    | 2026-4Q                  |
+| half       | 2026-2H                  |
+| year       | 2026                     |
+#+end_example
+
+*** ~#chunk_sym~ and ~#chunk_name~
+A ~Period~ can determine if it is a chunk with the ~#chunk_sym~ method.
+It's ~first~ and ~last~ dates correspond to a chunk boundary, it returns
+a ~Symbol~ for its chunks size, or the symbol :irregular otherwise. A
+similar method, ~#chunk_name~, returns a ~String~ name of the chunk:
+
+#+begin_src ruby
+Date.beginning_of_week = :sunday
+pds = [
+Period.new('2016-02-01', '2016-02-29'),
+Period.new('2016-02-01', '2016-02-28'),
+Period.new('2017-02-01', '2017-02-28'),
+Period.new('2017-01-01', '2017-02-28'),
+Period.new('2016-01-01', '2016-03-31'),
+Period.new('2016-03-20', '2016-03-26'),
+Period.new('2016-01-02', '2016-04-01'),
+]
+tab = []
+tab << ['First', 'Last', 'Chunk']
+tab << nil
+pds.each do |pd|
+  tab << [pd.first.iso, pd.last.iso, pd.chunk_sym]
+end
+tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| First      | Last       | Chunk      |
+|------------+------------+------------|
+| 2016-02-01 | 2016-02-29 | :month     |
+| 2016-02-01 | 2016-02-28 | :irregular |
+| 2017-02-01 | 2017-02-28 | :month     |
+| 2017-01-01 | 2017-02-28 | :bimonth   |
+| 2016-01-01 | 2016-03-31 | :quarter   |
+| 2016-03-20 | 2016-03-26 | :week      |
+| 2016-01-02 | 2016-04-01 | :irregular |
+#+end_example
+
+*** ~#chunks(size: :month, partial_first: true, partial_last: true, round_up_last: false)~
+You may want to divide a year into months, or a quarter into
+semi-months.  For this ~FatTable~ provides ~Period#chunks~.  By default,
+the first and last chunks will be partial, the first starting at
+~Period#first~ regardless of whether it is a full chunk and the last
+ending at ~Period#last~ regardless of whether it is a full chunk.  But
+this can be altered at the cost of not fully spanning the subject
+~Period~.
+
+- ~partial_first~ :: if set ~false~, the first chunk will be a
+  full-sized chunk at the possible cost of starting later than
+  ~Period#first~; it is ~true~ by default.
+- ~partial_last~ :: if set ~false~, the last chunk will be a
+  full-sized chunk at the possible cost of ending earlier than
+  ~Period#last~; it is ~true~ by default.
+- ~round_up_last~ :: if set ~true~, the last chunk returned may extend
+  beyond ~Period#last~ if it needs to in order to make it whole; it is
+  ~false~ by default.
+
+Since weeks do not necessarily align with calendar quarters, we get a
+partial first and last week by default:
+
+#+begin_src ruby
+  Period.parse('2026-3Q').chunks(size: :week).map {|m| [m]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Period | (2026-07-01..2026-07-04) |
+| Period | (2026-07-05..2026-07-11) |
+| Period | (2026-07-12..2026-07-18) |
+| Period | (2026-07-19..2026-07-25) |
+| Period | (2026-07-26..2026-08-01) |
+| Period | (2026-08-02..2026-08-08) |
+| Period | (2026-08-09..2026-08-15) |
+| Period | (2026-08-16..2026-08-22) |
+| Period | (2026-08-23..2026-08-29) |
+| Period | (2026-08-30..2026-09-05) |
+| Period | (2026-09-06..2026-09-12) |
+| Period | (2026-09-13..2026-09-19) |
+| Period | (2026-09-20..2026-09-26) |
+| Period | (2026-09-27..2026-09-30) |
+#+end_example
+
+But we can suppress the partials at the cost of not spanning the whole
+quarter:
+
+#+begin_src ruby
+  Period.parse('2026-3Q').chunks(size: :week, partial_first: false, partial_last: false).map {|m| [m]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Period | (2026-07-05..2026-07-11) |
+| Period | (2026-07-12..2026-07-18) |
+| Period | (2026-07-19..2026-07-25) |
+| Period | (2026-07-26..2026-08-01) |
+| Period | (2026-08-02..2026-08-08) |
+| Period | (2026-08-09..2026-08-15) |
+| Period | (2026-08-16..2026-08-22) |
+| Period | (2026-08-23..2026-08-29) |
+| Period | (2026-08-30..2026-09-05) |
+| Period | (2026-09-06..2026-09-12) |
+| Period | (2026-09-13..2026-09-19) |
+| Period | (2026-09-20..2026-09-26) |
+#+end_example
+
+With ~round_up_last~ set ~true~, the last chunk overflows the subject
+Period's bounds if needed to make it a whole week:
+
+#+begin_src ruby
+  Period.parse('2026-3Q').chunks(size: :week, round_up_last: true).map {|m| [m]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Period | (2026-07-01..2026-07-04) |
+| Period | (2026-07-05..2026-07-11) |
+| Period | (2026-07-12..2026-07-18) |
+| Period | (2026-07-19..2026-07-25) |
+| Period | (2026-07-26..2026-08-01) |
+| Period | (2026-08-02..2026-08-08) |
+| Period | (2026-08-09..2026-08-15) |
+| Period | (2026-08-16..2026-08-22) |
+| Period | (2026-08-23..2026-08-29) |
+| Period | (2026-08-30..2026-09-05) |
+| Period | (2026-09-06..2026-09-12) |
+| Period | (2026-09-13..2026-09-19) |
+| Period | (2026-09-20..2026-09-26) |
+| Period | (2026-09-27..2026-10-03) |
+#+end_example
+
 ** Set Operations
-*** Subset Determination
-*** Superset Determination
-*** Intersection
-*** Difference
-*** Union
+Another question one might want to ask of a ~Period~ is how it relates
+to another ~Period~.  Does it fully contain another?  Is it a sub-period
+of another, and so-forth.  Since these resemble the same sorts of
+questions one might ask of sets of numbers, these are called "set
+operations" on ~Period~s.
+
+*** ~#subset_of?(other)~
+Is this ~Period~ wholly contained within the ~other~ ~Period~?
+
+#+begin_src ruby
+ Period.parse('2026-1Q').subset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+Note that every ~Period~ is it's own subset:
+
+#+begin_src ruby
+ Period.parse('2026').subset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+#+begin_src ruby
+ Period.parse('2026').subset_of?(Period.parse('2026-2Q'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
+*** ~#proper_subset_of?(other)~
+Is this ~Period~ wholly contained within the ~other~ ~Period~ but not
+identical to it?
+
+#+begin_src ruby
+ Period.parse('2026-1Q').proper_subset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+Note that every ~Period~ is /not/ it's own proper subset:
+
+#+begin_src ruby
+ Period.parse('2026').proper_subset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
+*** ~#superset_of(other)~
+Does this ~Period~ wholly contain ~other~ ~Period~?
+
+#+begin_src ruby
+ Period.parse('2026-1Q').superset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
+#+begin_src ruby
+ Period.parse('2026').superset_of?(Period.parse('2026-2H'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+Note that every ~Period~ is it's own superset:
+
+#+begin_src ruby
+ Period.parse('2026').superset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+*** ~#proper_superset_of(other)~
+Does this ~Period~ wholly contain ~other~ ~Period~ without being
+identical to it?
+
+#+begin_src ruby
+ Period.parse('2026').proper_superset_of?(Period.parse('2026-2Q'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+Note that every ~Period~ is /not/ it's own proper superset:
+
+#+begin_src ruby
+ Period.parse('2026').proper_superset_of?(Period.parse('2026'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
+*** ~#intersection(other)~
+Return a new ~Period~ that is contained in both the subject ~Period~ and
+~other~.
+
+#+begin_src ruby
+ Period.parse('2026').intersection(Period.parse_phrase('from 2025-33W to 2026-23W').first)
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Period(2026-01-01..2026-06-07)
+#+end_example
+
+The ~&~ operator is equivalent.
+#+begin_src ruby
+ Period.parse('2026') & Period.parse_phrase('from 2025-33W to 2026-23W').first
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Period(2026-01-01..2026-06-07)
+#+end_example
+
+As is the method ~narrow_to~.
+#+begin_src ruby
+ Period.parse('2026').narrow_to(Period.parse_phrase('from 2025-33W to 2026-23W').first)
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Period(2026-01-01..2026-06-07)
+#+end_example
+
+Return ~nil~ if there is no intersection:
+#+begin_src ruby
+ Period.parse('2026').intersection(Period.parse('2024-3Q'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+nil
+#+end_example
+
+*** ~#union(other)~
+If two ~Periods~ either overlap or are contiguous, you can return a
+~Period~ that spans both:
+
+#+begin_src ruby
+ Period.parse('2026').union(Period.parse_phrase('from 2025-33W to 2026-23W').first)
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Period(2025-08-11..2026-12-31)
+#+end_example
+
+The ~+~ operator is equivalent.
+#+begin_src ruby
+ Period.parse('2026') + Period.parse_phrase('from 2025-33W to 2026-23W').first
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Period(2025-08-11..2026-12-31)
+#+end_example
+
+Return ~nil~ if there is no overlap or contiguity:
+#+begin_src ruby
+ Period.parse('2026').union(Period.parse('2024-3Q'))
+#+end_src
+
+#+RESULTS:
+#+begin_example
+nil
+#+end_example
+
+*** ~#difference(other)~
+Return an ~Array~ of ~Periods~ representing the subject ~Period~ with
+any overlap with ~other~ excluded.  If there is no overlap, return the
+subject ~Period~.
+
+#+begin_src ruby
+ Period.parse('2015-1Q').difference(Period.parse('2015-02')).map {|p| [p.to_s]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| 2015-01 |
+| 2015-03 |
+#+end_example
+
+#+begin_src ruby
+ Period.parse('2015-1Q').difference(Period.parse('2015-08')).map {|p| [p.to_s]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| 2015-1Q |
+#+end_example
+
+The operator ~-~ can be used as well:
+#+begin_src ruby
+ (Period.parse('2015-1Q') - Period.parse('2015-02')).map {|p| [p.to_s]}
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| 2015-01 |
+| 2015-03 |
+#+end_example
+
 ** Coverage
-*** Contains?
-*** Overlapping
-*** Spanning
-*** Gaps
+*** ~#contains?(date)~
+Return whether the subject ~Period~ contains the given ~Date~.
+
+#+begin_src ruby
+  Period.parse('2026-2Q').contains?('2026-04-15')
+#+end_src
+
+#+RESULTS:
+#+begin_example
+true
+#+end_example
+
+#+begin_src ruby
+  Period.parse('2026-2Q').contains?('2026-08-15')
+#+end_src
+
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
+*** ~Period.overlaps_among?(periods)~
+This class method takes an ~Array~ of ~Periods~ and returns whether the
+given periods have any overlaps with one another.
+
+*** ~#overlaps_among?~
+Similar to ~Period.overlaps_among~ except that it returns true only if
+any of the overlaps occur within the subject ~Period~.
+
+*** ~#spanned_by(periods)~
+Returns whether the given ~Array~ of ~Periods~ "span" the subject
+~Period~, that is, whether they collectively cover the subject ~Period~
+with no overlaps and no gaps.
+
+*** ~#gaps~
+Returns an ~Array~ of ~Period~s representing the gaps within the subject
+~Period~ not covered by the given ~Array~ of ~Periods~.  Overlaps among
+the periods do not affect the result nor do gaps outside the range of
+the subject ~Period~.  Ordering among the given ~periods~ does not
+matter.
+
+
+** Interest Day-count fraction (~#year_fraction~)
+For interest-related calculations, the methods by which accrued interest
+is allocated to a partial ~Period~ are numerous and subtle.  Rather than
+solve this problem over-and-over, ~FatPeriod~ aims to implement a single
+method that solves this problem once-and-for-all.
+
+The dates that correspond to the notation in Wikipedia's [[https://en.wikipedia.org/wiki/Day_count_convention][Day count
+convention]] article, which was used as a reference for ~FatPeriod~'s
+implementation, are as follows:
+
+- ~first~ is Date1, the start of accrual.
+- ~date2~ is Date2, the payment or settlement date, supplied as a ~Date~ or a
+  date string.  It must fall within the Period, including its endpoints.
+- ~last~ is Date3, the next coupon payment date.  For ICMA, construct the
+  Period with consecutive coupon boundaries.
+
+~Period#year_fraction~ returns a ~BigDecimal~ factor for calculating
+interest from ~first~ to a given payment or settlement date.  Usually
+this is a fraction of a year: multiply the principal by the annual rate
+and this factor to calculate accrued interest.  The default convention
+is *30/360 US* (~convention: 1~).
+
+#+begin_example
+period.year_fraction(date2, convention: 1, eom: true, maturity_date: nil)
+#+end_example
+
+Day counts use elapsed days, without adding one as ~Period#size~ does.  For
+example, January 1 to July 1 is the reference period for a coupon paid on
+July 1; use July 1 as ~last~, rather than June 30.  Passing ~last~ as the
+settlement date calculates the full coupon's factor.
+
+#+begin_src ruby
+period = Period.new('2024-01-01', '2024-07-01')
+pay_date = '2024-04-01'
+principal = BigDecimal('1000')
+rate = BigDecimal('0.05')
+
+tab =
+  [['Principal', principal.to_s('F')],
+   ['Rate', rate.to_s('F')],
+   ['Period', period.to_s],
+   ['Payment Date', pay_date]]
+tab
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Principal    |                   1000.0 |
+| Rate         |                     0.05 |
+| Period       | 2024-01-01 to 2024-07-01 |
+| Payment Date |               2024-04-01 |
+#+end_example
+
+#+begin_src ruby :results value table
+tab2 = []
+tab2 << ['Convention', 'Factor', 'Interest']
+tab2 << nil
+0.upto(11) do |conv|
+  factor = period.year_fraction(pay_date, convention: conv)
+  interest = principal * rate * factor
+  tab2 << [conv, factor.round(4).to_s('F'), interest.round(2).to_s('F')]
+end
+tab2
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Convention | Factor | Interest |
+|------------+--------+----------|
+| 0          |   0.25 |     12.5 |
+| 1          |   0.25 |     12.5 |
+| 2          |   0.25 |     12.5 |
+| 3          |   0.25 |     12.5 |
+| 4          |   0.25 |     12.5 |
+| 5          | 0.2486 |    12.43 |
+| 6          | 0.2493 |    12.47 |
+| 7          | 0.2528 |    12.64 |
+| 8          |   0.25 |     12.5 |
+| 9          | 0.2486 |    12.43 |
+| 10         | 0.2486 |    12.43 |
+| 11         |    1.0 |     50.0 |
+#+end_example
+
+*** Choosing a convention
+The convention numbers are specific to ~FatPeriod~; they are not Excel's
+~YEARFRAC~ basis numbers.  Supply ~convention: 0~ explicitly for Bond Basis.
+The ISDA references below are to Section 4.16 of the /2006 ISDA Definitions/.
+
+| Convention | Name                | Reference                       |
+|------------+---------------------+---------------------------------|
+| 0          | 30/360 Bond Basis   | ISDA 4.16(f)                    |
+| 1          | 30/360 US (default) | 4.16(f), plus US February rules |
+| 2          | 30E/360             | ISDA 4.16(g)                    |
+| 3          | 30E/360 ISDA        | ISDA 4.16(h)                    |
+| 4          | Actual/Actual ICMA  | ISDA 4.16(c); ICMA Rule 251     |
+| 5          | Actual/Actual ISDA  | ISDA 4.16(b)                    |
+| 6          | Actual/365 Fixed    | ISDA 4.16(d)                    |
+| 7          | Actual/360          | ISDA 4.16(e)                    |
+| 8          | Actual/364          | Wikipedia's Actual/364 section  |
+| 9          | Actual/365L         | Wikipedia's Actual/365L section |
+| 10         | Actual/Actual AFB   | Wikipedia's AFB discussion      |
+| 11         | 1/1                 | ISDA 4.16(a)                    |
+
+For convention 1, ~eom: true~ (the default) applies the February
+end-of-month rules for investments that pay at month end.  Set ~eom:
+false~ to omit those February adjustments.  The remaining 30/360
+adjustments still apply.
+
+For convention 3, ~maturity_date:~ accepts a ~Date~ or date string and
+identifies the investment's final maturity.  It is irrelevant for the
+other conventions and is ~nil~ by default.  Under convention 3, when
+settlement (i.e., ~date2~) is that date and is the last day of February,
+its day number is left unchanged.  Otherwise the usual month-end
+adjustment applies.
+
+#+begin_src ruby
+  final_coupon = Period.new('2023-08-31', '2024-02-29')
+  ordinary = final_coupon.year_fraction('2024-02-29', convention: 3)
+  at_maturity = final_coupon.year_fraction(
+    '2024-02-29', convention: 3, maturity_date: '2024-02-29'
+  )
+  [ordinary.to_s('F'), at_maturity.round(10).to_s('F')]
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| 0.5 | 0.4972222222 |
+#+end_example
+
+*** Actual-day conventions and boundaries
+ICMA (4) divides elapsed days by the product of payment frequency and elapsed
+days in the full coupon period.  Frequency is inferred from the full period's
+length.  For example, both a full 181-day half-year coupon and a full 184-day
+half-year coupon have a factor of 0.5, but their daily accruals differ.
+
+#+begin_src ruby
+  coupon = Period.new('2024-01-01', '2024-07-01')
+  partial = coupon.year_fraction('2024-04-01', convention: 4)
+  full = coupon.year_fraction(coupon.last, convention: 4)
+  [partial.to_s('F'), full.to_s('F')]
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| 0.25 | 0.5 |
+#+end_example
+
+ICMA supports regular coupon periods only; it does not construct notional
+coupon schedules for irregular first or final coupons.  Frequency inference
+allows the same 10% length tolerance as ~chunk_name~ for monthly and longer
+periods.  An unrecognizable length raises ~ArgumentError~ for conventions
+that require frequency (4 and 9).
+
+ISDA Actual/Actual (5) splits the elapsed interval at calendar-year boundaries,
+using 365 or 366 for each portion.  Conventions 6, 7, and 8 use fixed
+denominators of 365, 360, and 364 respectively.
+
+Actual/365L (9) follows the Wikipedia article's settlement-date rule: for
+annual payments, it uses 366 if February 29 falls after ~first~ and on or
+before settlement, otherwise 365.  For other frequencies, it uses the number
+of days in the settlement year.  The full period determines frequency, not
+the leap-day test interval.
+
+AFB (10) counts complete years backwards from settlement, then calculates the
+remaining initial fraction.  It uses the ISDA backward-counting February
+adjustment described in the article: a February 28 anniversary moves to
+February 29 when the preceding year is a leap year.  The remaining fraction
+uses 366 only when it includes February 29, counting its start but excluding
+its end.
+
+Equal start and settlement dates return zero for conventions 0 through 10.
+Convention 11 (1/1) always returns one, even for equal dates: it applies the
+full contractual rate without prorating for time.  Invalid convention numbers
+or settlement dates outside the Period raise ~ArgumentError~.
+
+*** Sources
+- [[https://en.wikipedia.org/wiki/Day_count_convention][Wikipedia: Day count convention]] gives the formulas, naming variants, and
+  discussion of the conventions implemented here.
+- [[https://www.isda.org/book/2006-isda-definitions/][2006 ISDA Definitions]], Section 4.16, /Day Count Fraction/, is the primary
+  source for most of these rules.  A [[https://www.sc.com/en/uploads/sites/66/content/docs/2006-ISDA-Definitions.pdf][PDF copy hosted by Standard Chartered]]
+  contains the section on printed pages 11-13.  Section 4.16(f) defines Bond
+  Basis; the additional US February rules are described in the Wikipedia
+  article rather than that clause.
+
 
 * Development