fat_period 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 06d57a27d2bdf83d78c5d0a02b470af0a9f59d69
+  data.tar.gz: 7beb9253ef8d2020d24d41dbb30c9b92d402cbbc
+SHA512:
+  metadata.gz: 8936394c6426abb4048f95f2e2930dcafa822bb273831df12e02d26f100a6d6778581bf2e00b665e34b37fc327b242fd85cfa17bd24a8524d87142256cdd0a03
+  data.tar.gz: e2fd7548fa3f8134b4fd3e79b8ff91aff97d30348cf3d5556faa6c4564adab292518df8748532fa3d3858a444ac4f2c210c7f4e99aecee6e2c32572626f02440

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.14.3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fat_period.gemspec
+gemspec

data/README.md

@@ -0,0 +1,36 @@
+# FatPeriod
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fat_period`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fat_period'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fat_period
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Daniel E. Doherty/fat_period.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'fat_period'
+require 'pry'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+@dd1 = Date.parse('2016-01-31')
+@dd2 = Date.parse('2016-01-30')
+@dd3 = Date.parse('2016-01-29')
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/fat_period.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fat_period/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'fat_period'
+  spec.version       = FatPeriod::VERSION
+  spec.authors       = ['Daniel E. Doherty']
+  spec.email         = ['ded-law@ddoherty.net']
+
+  spec.summary       = %q{Implements a Period class as a Range of Dates.}
+  spec.homepage      = 'https://github.com/ddoherty03/fat_period'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  # Don't install any executables.
+  # spec.bindir = 'bin'
+  # spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'pry-doc'
+  spec.add_development_dependency 'pry-byebug'
+
+  spec.add_runtime_dependency 'fat_core', '~> 4.0', '>= 4.1'
+end

data/lib/fat_period/date.rb

@@ -0,0 +1,31 @@
+require 'date'
+
+module FatPeriod
+  # An extension of Date for methods useful with respect to FatPeriod::Periods.
+  module Date
+    # Return the Period of the given chunk size that contains this Date. Chunk
+    # can be one of :year, :half, :quarter, :bimonth, :month, :semimonth,
+    # :biweek, :week, or :day.
+    #
+    # @example
+    #   date = Date.parse('2015-06-13')
+    #   date.expand_to_period(:week)      #=> Period(2015-06-08..2015-06-14)
+    #   date.expand_to_period(:semimonth) #=> Period(2015-06-01..2015-06-15)
+    #   date.expand_to_period(:quarter)   #=> Period(2015-04-01..2015-06-30)
+    #
+    # @param chunk [Symbol] one of :year, :half, :quarter, :bimonth, :month,
+    #    :semimonth, :biweek, :week, or :day
+    # @return [Period] Period of size `chunk` containing self
+    def expand_to_period(chunk)
+      require 'fat_period'
+      Period.new(beginning_of_chunk(chunk), end_of_chunk(chunk))
+    end
+  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

data/lib/fat_period/period.rb

@@ -0,0 +1,785 @@
+# -*- coding: utf-8 -*-
+
+require 'fat_core/date'
+require 'fat_core/range'
+require 'fat_core/string'
+
+class Period
+  # Return the first Date of the Period
+  #
+  # @return [Date]
+  attr_reader :first
+
+  # Return the last Date of the Period
+  #
+  # @return [Date]
+  attr_reader :last
+
+  # @group Construction
+  #
+  # Return a new Period from the Date `first` to the Date `last` inclusive. Both
+  # parameters can be either a Date object or a String that can be parsed as a
+  # valid Date with `Date.parse`.
+  #
+  # @param first [Date, String] first date of Period
+  # @param last [Date, String] last date of Period
+  # @raise [ArgumentError] if string is not parseable as a Date or
+  # @raise [ArgumentError] if first date is later than last date
+  # @return [Period]
+  def initialize(first, last)
+    if first.is_a?(Date)
+      @first = first
+    elsif first.respond_to?(:to_s)
+      begin
+        @first = Date.parse(first.to_s)
+      rescue ArgumentError => ex
+        if ex.message =~ /invalid date/
+          raise ArgumentError, "you gave an invalid date '#{first}'"
+        else
+          raise
+        end
+      end
+    else
+      raise ArgumentError, 'use Date or String to initialize Period'
+    end
+
+    if last.is_a?(Date)
+      @last = last
+    elsif last.respond_to?(:to_s)
+      begin
+        @last = Date.parse(last.to_s)
+      rescue ArgumentError => ex
+        if ex.message =~ /invalid date/
+          raise ArgumentError, "you gave an invalid date '#{last}'"
+        else
+          raise
+        end
+      end
+    else
+      raise ArgumentError, 'use Date or String to initialize Period'
+    end
+    if @first > @last
+      raise ArgumentError, "Period's first date is later than its last date"
+    end
+  end
+
+  # These need to come after initialize is defined
+
+  # Period from commercial beginning of time to today
+  TO_DATE = Period.new(Date::BOT, Date.current)
+
+  # Period from commercial beginning of time to commercial end of time.
+  FOREVER = Period.new(Date::BOT, Date::EOT)
+
+  # @group Conversion
+
+  # Convert this Period to a Range.
+  #
+  # @return [Range]
+  def to_range
+    (first..last)
+  end
+
+  # Return a string representing this Period using compact format for years,
+  # halves, quarters, or months that represent a whole period; otherwise, just
+  # format the period as 'YYYY-MM-DD to YYYY-MM-DD'.
+  #
+  # @example
+  #   Period.new('2016-01-01', '2016-03-31') #=> '2016-1Q'
+  #   Period.new('2016-01-01', '2016-12-31') #=> '2016'
+  #   Period.new('2016-01-01', '2016-11-30') #=> '2016-01-01 to 2016-11-30'
+  #
+  # @return [String] concise representation of Period
+  def to_s
+    if first.beginning_of_year? && last.end_of_year? && first.year == last.year
+      first.year.to_s
+    elsif first.beginning_of_half? &&
+          last.end_of_half? &&
+          first.year == last.year &&
+          first.half == last.half
+      "#{first.year}-#{first.half}H"
+    elsif first.beginning_of_quarter? &&
+          last.end_of_quarter? &&
+          first.year == last.year &&
+          first.quarter == last.quarter
+      "#{first.year}-#{first.quarter}Q"
+    elsif first.beginning_of_month? &&
+          last.end_of_month? &&
+          first.year == last.year &&
+          first.month == last.month
+      "#{first.year}-%02d" % first.month
+    else
+      "#{first.iso} to #{last.iso}"
+    end
+  end
+
+  # A concise way to print out Periods for inspection as
+  # 'Period(YYYY-MM-DD..YYYY-MM-DD)'.
+  #
+  # @return [String]
+  def inspect
+    "Period(#{first.iso}..#{last.iso})"
+  end
+
+  # Allow erb documents can directly interpolate ranges
+  def tex_quote
+    "#{first.iso}--#{last.iso}"
+  end
+
+
+  include Comparable
+
+  # @group Comparison
+  #
+  # Comparable base: periods are compared by first, then by last and are equal
+  # only if their first and last dates are equal. Sorting will be by first date,
+  # then last, so periods starting on the same date will sort from smallest to
+  # largest.
+  #
+  # @param other [Period] @return [Integer] -1 if self < other; 0 if self ==
+  # other; 1 if self > other
+  def <=>(other)
+    return nil unless other.is_a?(Period)
+    [first, last] <=> [other.first, other.last]
+  end
+
+  # Comparable does not include this.
+  def !=(other)
+    !(self == other)
+  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 === contains?
+
+  include Enumerable
+
+  # @group Enumeration
+
+  # Yield each day in this Period.
+  def each
+    d = first
+    while d <= last
+      yield d
+      d += 1.day
+    end
+  end
+
+  # Return an Array of the days in the Period that are trading days on the NYSE.
+  # See FatCore::Date for how trading days are determined.
+  #
+  # @return [Array<Date>] trading days in this period
+  def trading_days
+    select(&:nyse_workday?)
+  end
+
+  # @group Size
+
+  # Return the number of days in the period
+  def size
+    (last - first + 1).to_i
+  end
+  alias length size
+  alias days size
+
+  # Return the fractional number of months in the period.  By default, use the
+  # average number of days in a month, but allow the user to override the
+  # assumption with a parameter.
+  def months(days_in_month = 30.436875)
+    (days / days_in_month.to_f).to_f
+  end
+
+  # Return the fractional number of years in the period.  By default, use the
+  # average number of days in a year, but allow the user to override the
+  # assumption with a parameter.
+  def years(days_in_year = 365.2425)
+    (days / days_in_year.to_f).to_f
+  end
+
+  # @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
+  # 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.
+  #
+  # @example
+  #   Period.parse('2014-11').inspect                  #=> Period('2014-11-01..2014-11-30')
+  #   Period.parse('2014-11', '2015-3Q').inspect       #=> Period('2014-11-01..2015-09-30')
+  #   # 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
+  # @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)
+    Period.new(first, second) if first && second
+  end
+
+  # Return a period as in `Period.parse` from a String phrase in which the from
+  # spec is introduced with 'from' and, optionally, the to spec is introduced
+  # with 'to'.  A phrase with only a to spec is treated the same as one with
+  # only a from spec.  If neither 'from' nor 'to' appear in phrase, treat the
+  # whole string as a from spec.
+  #
+  # @example
+  #   Period.parse_phrase('from 2014-11 to 2015-3Q') #=> Period('2014-11-01..2015-09-30')
+  #   Period.parse_phrase('from 2014-11')            #=> Period('2014-11-01..2014-11-30')
+  #   Period.parse_phrase('from 2015-3Q')            #=> Period('2015-09-01..2015-12-31')
+  #   Period.parse_phrase('to 2015-3Q')              #=> Period('2015-09-01..2015-12-31')
+  #   Period.parse_phrase('2015-3Q')                 #=> Period('2015-09-01..2015-12-31')
+  #
+  # @param phrase [String] with 'from <spec> to <spec>'
+  # @return [Period] translated from phrase
+  def self.parse_phrase(phrase)
+    phrase = phrase.clean
+    if phrase =~ /\Afrom (.*) to (.*)\z/
+      from_phrase = $1
+      to_phrase = $2
+    elsif phrase =~ /\Afrom (.*)\z/
+      from_phrase = $1
+      to_phrase = nil
+    elsif phrase =~ /\Ato (.*)\z/
+      from_phrase = $1
+    else
+      from_phrase = phrase
+      to_phrase = nil
+    end
+    parse(from_phrase, to_phrase)
+  end
+
+  # Possibly useful class method to take an array of periods and join all the
+  # contiguous ones, then return an array of the disjoint periods not
+  # contiguous to one another.  An array of periods with no gaps should return
+  # an array of only one period spanning all the given periods.
+  #
+  # Return an array of periods that represent the concatenation of all
+  # adjacent periods in the given periods.
+  # def self.meld_periods(*periods)
+  #   melded_periods = []
+  #   while (this_period = periods.pop)
+  #     melded_periods.each do |mp|
+  #       if mp.overlaps?(this_period)
+  #         melded_periods.delete(mp)
+  #         melded_periods << mp.union(this_period)
+  #         break
+  #       elsif mp.contiguous?(this_period)
+  #         melded_periods.delete(mp)
+  #         melded_periods << mp.join(this_period)
+  #         break
+  #       end
+  #     end
+  #   end
+  #   melded_periods
+  # end
+  #
+  # @group Chunking
+  #
+
+  # An Array of the valid Symbols for calendar chunks plus the Symbol :irregular
+  # for other periods.
+  CHUNKS = [
+    :day, :week, :biweek, :semimonth, :month, :bimonth,
+    :quarter, :half, :year, :irregular
+  ]
+
+  # An Array of Ranges for the number of days that can be covered by each chunk.
+  CHUNK_RANGE = {
+    day: (1..1), week: (7..7), biweek: (14..14), semimonth: (15..16),
+    month: (28..31), bimonth: (59..62), quarter: (90..92),
+    half: (180..183), year: (365..366)
+  }
+
+  # Return the chunk symbol represented by this period if it covers a single
+  # calendar period; otherwise return :irregular.
+  #
+  # @example
+  #   Period.new('2016-02-01', '2016-02-29').chunk_sym #=> :month
+  #   Period.new('2016-02-01', '2016-02-28').chunk_sym #=> :irregular
+  #   Period.new('2016-02-01', '2017-02-28').chunk_sym #=> :irregular
+  #   Period.new('2016-01-01', '2016-03-31').chunk_sym #=> :quarter
+  #   Period.new('2016-01-02', '2016-04-01').chunk_sym #=> :irregular
+  #
+  # @return [Symbol]
+  def chunk_sym
+    if first.beginning_of_year? && last.end_of_year? &&
+       CHUNK_RANGE[:year].cover?(size)
+      :year
+    elsif first.beginning_of_half? && last.end_of_half? &&
+          CHUNK_RANGE[:half].cover?(size)
+      :half
+    elsif first.beginning_of_quarter? && last.end_of_quarter? &&
+          CHUNK_RANGE[:quarter].cover?(size)
+      :quarter
+    elsif first.beginning_of_bimonth? && last.end_of_bimonth? &&
+          CHUNK_RANGE[:bimonth].cover?(size)
+      :bimonth
+    elsif first.beginning_of_month? && last.end_of_month? &&
+          CHUNK_RANGE[:month].cover?(size)
+      :month
+    elsif first.beginning_of_semimonth? && last.end_of_semimonth &&
+          CHUNK_RANGE[:semimonth].cover?(size)
+      :semimonth
+    elsif first.beginning_of_biweek? && last.end_of_biweek? &&
+          CHUNK_RANGE[:biweek].cover?(size)
+      :biweek
+    elsif first.beginning_of_week? && last.end_of_week? &&
+          CHUNK_RANGE[:week].cover?(size)
+      :week
+    elsif first == last
+      :day
+    else
+      :irregular
+    end
+  end
+
+  # Return a string name for this period based solely on the number of days in
+  # the period. Any period sufficiently close to 30 days will return the string
+  # 'Month', and any period sufficiently close to 90 days will return 'Quarter'.
+  # However for the shorter periods, periods less than month, no tolerance is
+  # applied.  The amount of tolerance for the longer periods can be controlled
+  # with the `tolerance_pct` parameter, which default to 10%.  If no calendar
+  # period corresponds to the length of the period, return 'Period'.
+  #
+  # @example
+  #   Period.new('2015-05-15', '2015-06-17').chunk_name    #=> 'Month' (within 10%)
+  #   Period.new('2015-05-15', '2015-06-17').chunk_name(8) #=> 'Period' (but not 8%)
+  #
+  # @param tolerance_pct [Numeric] long period tolerance as a percent, 10 by default
+  # @return [String] the name for this period based solely on the number of days
+  #   in the period.
+  def chunk_name(tolerance_pct = 10)
+    case Period.days_to_chunk(length, tolerance_pct)
+    when :year
+      'Year'
+    when :half
+      'Half'
+    when :quarter
+      'Quarter'
+    when :bimonth
+      'Bimonth'
+    when :month
+      'Month'
+    when :semimonth
+      'Semimonth'
+    when :biweek
+      'Biweek'
+    when :week
+      'Week'
+    when :day
+      'Day'
+    else
+      'Period'
+    end
+  end
+
+  # Return the chunk symbol represented by the number of days given, but allow a
+  # deviation from the minimum and maximum number of days for periods larger
+  # than bimonths. The default tolerance is +/-10%, but that can be adjusted. The
+  # reason for allowing a bit of tolerance for the larger periods is that
+  # financial statements meant to cover a given calendar period are often short
+  # or long by a few days due to such things as weekends, holidays, or
+  # accounting convenience. For example, a bank might issuer "monthly"
+  # statements approximately every 30 days, but issue them earlier or later to
+  # avoid having the closing date fall on a weekend or holiday. We still want to
+  # be able to recognize them as "monthly", even though the period covered might
+  # be a few days shorter or longer than any possible calendar month.  You can
+  # eliminate this "fudge factor" by setting the `tolerance_pct` to zero.  If
+  # the number of days corresponds to none of the defined calendar periods,
+  # return the symbol `:irregular`.
+  #
+  # @example
+  #   Period.days_to_chunk(360)    #=> :year
+  #   Period.days_to_chunk(360, 0) #=> :irregular
+  #   Period.days_to_chunk(88)     #=> :quarter
+  #   Period.days_to_chunk(88, 0)  #=> :irregular
+  #
+  # @param days [Integer] the number of days in the period under test
+  # @param tolerance_pct [Numberic] the percent deviation allowed, e.g. 10 => 10%
+  # @return [Symbol] symbol for the period corresponding to days number of days
+  def self.days_to_chunk(days, tolerance_pct = 10)
+    result = :irregular
+    CHUNK_RANGE.each_pair do |chunk, rng|
+      if [:semimonth, :biweek, :week, :day].include?(chunk)
+        # Be strict for shorter periods.
+        if rng.cover?(days)
+          result = chunk
+          break
+        end
+      else
+        # Allow some tolerance for longer periods.
+        min = (rng.first * ((100.0 - tolerance_pct) / 100.0)).floor
+        max = (rng.last * ((100.0 + tolerance_pct) / 100.0)).floor
+        if (min..max).cover?(days)
+          result = chunk
+          break
+        end
+      end
+    end
+    result
+  end
+
+  # Return an array of Periods wholly-contained within self in chunks of size,
+  # defaulting to monthly chunks. Partial chunks at the beginning and end of
+  # self are not included unless `partial_first` or `partial_last`,
+  # respectively, are set true. The last chunk can be made to extend beyond the
+  # end of self to make it a whole chunk if `round_up_last` is set true, in
+  # which case, partial_last is ignored.
+  #
+  # @example
+  #   Period.parse('2015').chunks(size: :month) #=>
+  #    [Period(2015-01-01..2015-01-31),
+  #     Period(2015-02-01..2015-02-28),
+  #     Period(2015-03-01..2015-03-31),
+  #     Period(2015-04-01..2015-04-30),
+  #     Period(2015-05-01..2015-05-31),
+  #     Period(2015-06-01..2015-06-30),
+  #     Period(2015-07-01..2015-07-31),
+  #     Period(2015-08-01..2015-08-31),
+  #     Period(2015-09-01..2015-09-30),
+  #     Period(2015-10-01..2015-10-31),
+  #     Period(2015-11-01..2015-11-30),
+  #     Period(2015-12-01..2015-12-31)
+  #    ]
+  #
+  #   Period.parse('2015').chunks(size: :week) #=>
+  #    [Period(2015-01-05..2015-01-11), # Note that first week starts after Jan 1.
+  #     Period(2015-01-12..2015-01-18),
+  #     Period(2015-01-19..2015-01-25),
+  #     Period(2015-01-26..2015-02-01),
+  #     ...
+  #     Period(2015-12-07..2015-12-13),
+  #     Period(2015-12-14..2015-12-20),
+  #     Period(2015-12-21..2015-12-27)] # Note that last week ends before Dec 31
+  #
+  #   Period.parse('2015').chunks(size: :week, partial_first: true, partial_last: true) #=>
+  #    [Period(2015-01-01..2015-01-04), # Note the partial week starting Jan 1
+  #     Period(2015-01-05..2015-01-11),
+  #     Period(2015-01-12..2015-01-18),
+  #     Period(2015-01-19..2015-01-25),
+  #     Period(2015-01-26..2015-02-01),
+  #     ...
+  #     Period(2015-12-07..2015-12-13),
+  #     Period(2015-12-14..2015-12-20),
+  #     Period(2015-12-21..2015-12-27)
+  #     Period(2015-12-28..2015-12-31) # Note partial week ending Dec 31
+  #     ]
+  #
+  #   Period.parse('2015').chunks(size: :week, partial_first: true, round_up_last: true) #=>
+  #    [Period(2015-01-01..2015-01-04), # Note the partial week starting Jan 1
+  #     Period(2015-01-05..2015-01-11),
+  #     Period(2015-01-12..2015-01-18),
+  #     Period(2015-01-19..2015-01-25),
+  #     Period(2015-01-26..2015-02-01),
+  #     ...
+  #     Period(2015-12-07..2015-12-13),
+  #     Period(2015-12-14..2015-12-20),
+  #     Period(2015-12-21..2015-12-27)
+  #     Period(2015-12-28..2016-01-03) # Note full week extending beyond self
+  #     ]
+  #
+  # @raise ArgumentError if size of chunks is larger than self or if an invalid
+  #   chunk size.
+  # @param size [Symbol] a chunk symbol, :year, :half. :quarter, etc.
+  # @param partial_first [Boolean] allow a period less than a full :size period
+  #   as the first period in the returned array.
+  # @param partial_last [Boolean] allow a period less than a full :size period
+  #   as the last period in the returned array.
+  # @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: false, partial_last: false,
+             round_up_last: false)
+    size = size.to_sym
+    unless CHUNKS.include?(size)
+      raise ArgumentError, "unknown chunk size '#{size}'"
+    end
+    if CHUNK_RANGE[size].first > length
+      if partial_first || partial_last
+        return [self]
+      else
+        raise ArgumentError, "any #{size} is longer than this period's #{length} days"
+      end
+    end
+    result = []
+    chunk_start = first.dup
+    while chunk_start <= last
+      case size
+      when :year
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_year?
+        end
+        chunk_end = chunk_start.end_of_year
+      when :half
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_half?
+        end
+        chunk_end = chunk_start.end_of_half
+      when :quarter
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_quarter?
+        end
+        chunk_end = chunk_start.end_of_quarter
+      when :bimonth
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_bimonth?
+        end
+        chunk_end = (chunk_start.end_of_month + 1.day).end_of_month
+      when :month
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_month?
+        end
+        chunk_end = chunk_start.end_of_month
+      when :semimonth
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_semimonth?
+        end
+        chunk_end = chunk_start.end_of_semimonth
+      when :biweek
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_biweek?
+        end
+        chunk_end = chunk_start.end_of_biweek
+      when :week
+        unless partial_first
+          chunk_start += 1.day until chunk_start.beginning_of_week?
+        end
+        chunk_end = chunk_start.end_of_week
+      when :day
+        chunk_end = chunk_start
+      else
+        raise ArgumentError, "invalid chunk size '#{size}'"
+      end
+      if chunk_end <= last
+        result << Period.new(chunk_start, chunk_end)
+      elsif round_up_last
+        result << Period.new(chunk_start, chunk_end)
+      elsif partial_last
+        result << Period.new(chunk_start, last)
+      else
+        break
+      end
+      chunk_start = result.last.last + 1.day
+    end
+    result
+  end
+
+  # @group Set operations
+
+  # Is this period contained wholly within or coincident with `other`?
+  #
+  # @example
+  #   Period.parse('2015-2Q').subset_of?(Period.parse('2015'))    #=> true
+  #   Period.parse('2015-2Q').subset_of?(Period.parse('2015-2Q')) #=> true
+  #   Period.parse('2015-2Q').subset_of?(Period.parse('2015-02')) #=> false
+  #
+  # @param other [Period] other Period
+  # @return [Boolean] self within or coincident with `other`?
+  def subset_of?(other)
+    to_range.subset_of?(other.to_range)
+  end
+
+  # Is this period contained wholly within but not coincident with `other`?
+  #
+  # @example
+  #   Period.parse('2015-2Q').proper_subset_of?(Period.parse('2015'))    #=> true
+  #   Period.parse('2015-2Q').proper_subset_of?(Period.parse('2015-2Q')) #=> false
+  #   Period.parse('2015-2Q').proper_subset_of?(Period.parse('2015-02')) #=> false
+  #
+  # @param other [Period] other Period
+  # @return [Boolean] self within `other`?
+  def proper_subset_of?(other)
+    to_range.proper_subset_of?(other.to_range)
+  end
+
+  # Does this period wholly contain or is coincident with `other`?
+  #
+  # @example
+  #   Period.parse('2015').superset_of?(Period.parse('2015-2Q'))    #=> true
+  #   Period.parse('2015-2Q').superset_of?(Period.parse('2015-2Q')) #=> true
+  #   Period.parse('2015-02').superset_of?(Period.parse('2015-2Q')) #=> false
+  #
+  # @param other [Period] other Period
+  # @return [Boolean] self contains or coincident with `other`?
+  def superset_of?(other)
+    to_range.superset_of?(other.to_range)
+  end
+
+  # Does this period wholly contain but not coincident with `other`?
+  #
+  # @example
+  #   Period.parse('2015').proper_superset_of?(Period.parse('2015-2Q'))    #=> true
+  #   Period.parse('2015-2Q').proper_superset_of?(Period.parse('2015-2Q')) #=> false
+  #   Period.parse('2015-02').proper_superset_of?(Period.parse('2015-2Q')) #=> false
+  #
+  # @param other [Period] other Period
+  # @return [Boolean] self contains `other`?
+  def proper_superset_of?(other)
+    to_range.proper_superset_of?(other.to_range)
+  end
+
+  # Return the Period that is the intersection of self with `other` or nil if
+  # there is no intersection.
+  #
+  # @example
+  #   Period.parse('2015-3Q') & Period.parse('2015-2Q') #=> nil
+  #   Period.parse('2015') & Period.parse('2015-2Q')    #=> Period(2015-2Q)
+  #   pp1 = Period.parse_phrase('from 2015 to 2015-3Q') #=> Period(2015-01-01..2015-09-30)
+  #   pp2 = Period.parse_phrase('from 2015-2H')         #=> Period(2015-07-01..2015-12-31)
+  #   pp1 & pp2                                         #=> Period(2015-07-01..2015-09-30)
+  #
+  # @param other [Period] other Period
+  # @return [Period, nil] self intersect `other`?
+  def intersection(other)
+    result = to_range.intersection(other.to_range)
+    if result.nil?
+      nil
+    else
+      Period.new(result.first, result.last)
+    end
+  end
+  alias & intersection
+  alias narrow_to intersection
+
+  # Return the Period that is the union of self with `other` or nil if
+  # they neither overlap nor are contiguous
+  #
+  # @example
+  #   Period.parse('2015-3Q') + Period.parse('2015-2Q')    #=> Period(2015-04-01..2015-09-30)
+  #   Period.parse('2015') + Period.parse('2015-2Q')       #=> Period(2015-01-01..2015-12-31)
+  #   Period.parse('2015') + Period.parse('2017')          #=> nil
+  #   pp1 = Period.parse_phrase('from 2015-4Q to 2016-1H') #=> Period(2015-10-01-2015..2015-12-31)
+  #   pp2 = Period.parse_phrase('from 2015-3Q to 2015-11') #=> Period(2015-07-01-2015..2015-11-30)
+  #   pp1 + pp2                                            #=> Period(2015-10-01..2015-11-30)
+  #
+  # @param other [Period] other Period
+  # @return [Period, nil] self union `other`?
+  def union(other)
+    result = to_range.union(other.to_range)
+    return nil if result.nil?
+    Period.new(result.first, result.last)
+  end
+  alias + union
+
+  # Return an array of periods that are this period excluding any overlap with
+  # other. If there is no overlap, return an array with a period equal to self
+  # as the sole member.
+  #
+  # @example
+  #   Period.parse('2015-1Q') - Period.parse('2015-02')
+  #     #=> [Period(2015-01-01..2015-01-31), Period(2015-03-01..2015-03-31)]
+  #   Period.parse('2015-2Q') - Period.parse('2015-02')
+  #     #=> [Period(2015-04-01..2015-06-30)]
+  #
+  # @param other [Period] the other period to exclude from self
+  # @return [Array<Period>] self less the part of other that overlaps
+  def difference(other)
+    ranges = to_range.difference(other.to_range)
+    ranges.each.map { |r| Period.new(r.first, r.last) }
+  end
+  alias - difference
+
+  # Return whether this period overlaps the `other` period.  To overlap, the
+  # periods must have at least one day in common.
+  #
+  # @example
+  #   Period.parse('2012').overlaps?(Period.parse('2016')) #=> false
+  #   Period.parse('2016-32W').overlaps?(Period.parse('2016')) #=> true
+  #   pp1 = Period.new('2016-03-12', '2016-03-15')
+  #   pp2 = Period.new('2016-03-16', '2016-03-25')
+  #   pp1.overlaps?(pp2) #=> false (being contiguous is not overlapping)
+  #
+  # @param other [Period] the other period to test for overlap
+  # @return [Boolean] does self overlap with other?
+  def overlaps?(other)
+    to_range.overlaps?(other.to_range)
+  end
+
+  # Return whether any of the given periods overlap any other.
+  #
+  # @example
+  #   pds = []
+  #   pds << Period.parse('2015-1H')
+  #   pds << Period.parse('2016-2H')
+  #   pds << Period.parse('2015-04')
+  #   Period.overlaps_among?(pds) #=> true
+  #
+  # @param periods [Array<Period>] periods to test for overlaps
+  # @return [Boolean] true if any one of periods overlaps another
+  def self.overlaps_among?(periods)
+    Range.overlaps_among?(periods.map(&:to_range))
+  end
+
+  # Return whether any of the given periods overlap any other but only if the
+  # overlaps occur within the self; overlaps outside self are ignored.
+  #
+  # @example
+  #   pds = []
+  #   pds << Period.parse('2015-1H')
+  #   pds << Period.parse('2016-2H')
+  #   pds << Period.parse('2015-04')
+  #   yr2015 = Period.parse('2015')
+  #   yr2016 = Period.parse('2016')
+  #   yr2015.overlaps_among?(pds) #=> true
+  #   yr2016.overlaps_among?(pds) #=> false (overlap is in 2015)
+  #
+  # @param periods [Array<Period>] periods to test for overlaps
+  # @return [Boolean] true if any one of periods overlaps another
+  def overlaps_among?(periods)
+    to_range.overlaps_among?(periods.map(&:to_range))
+  end
+
+  # Return whether the given periods "span" self, that is, do they collectively
+  # cover all of self with no overlaps and no gaps?
+  #
+  # @example
+  #   ppds = []
+  #   ppds << Period.parse('2016-1Q')
+  #   ppds << Period.parse('2016-2Q')
+  #   ppds << Period.parse('2016-2H')
+  #   Period.parse('2016').spanned_by?(ppds) #=> true
+  #
+  #   # There's a bit of the year at the beginning that isn't covered by
+  #   # one of these weeks:
+  #   ppds = Period.parse('2016').chunks(size: :week)
+  #   Period.parse('2016').spanned_by?(ppds) #=> false
+  #
+  # @param periods [Array<Period>] periods to test for spanning self
+  # @return [Boolean] do periods span self?
+  def spanned_by?(periods)
+    to_range.spanned_by?(periods.map(&:to_range))
+  end
+
+  # Return an Array of Periods representing the gaps within self not covered by
+  # the Array of Periods `periods`.  Overlaps among the periods do not affect
+  # the result nor do gaps outside the range of self.  Ordering among the
+  # `periods` does not matter.
+  #
+  # @example
+  #   some_qs = []
+  #   some_qs << Period.parse('2015-1Q')
+  #   some_qs << Period.parse('2015-3Q')
+  #   some_qs << Period.parse('2015-11')
+  #   some_qs << Period.parse('2015-12')
+  #   Period.parse('2015').gaps(some_qs) #=>
+  #     [Period(2015-04-01..2015-06-30), Period(2015-10-01..2015-10-31)]
+  #
+  # @param periods [Array<Period>] periods to examine for coverage of self
+  # @return [Array<Periods>] periods that are not covered by `periods`
+  def gaps(periods)
+    to_range.gaps(periods.map(&:to_range))
+      .map { |r| Period.new(r.first, r.last) }
+  end
+end

data/lib/fat_period/version.rb

@@ -0,0 +1,3 @@
+module FatPeriod
+  VERSION = '1.0.0'.freeze
+end

data/lib/fat_period.rb

@@ -0,0 +1,3 @@
+require 'fat_period/version'
+require 'fat_period/date'
+require 'fat_period/period'

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: fat_period
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Daniel E. Doherty
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-05-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: pry-doc
+  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: pry-byebug
+  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: fat_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.1'
+description: 
+email:
+- ded-law@ddoherty.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- fat_period.gemspec
+- lib/fat_period.rb
+- lib/fat_period/date.rb
+- lib/fat_period/period.rb
+- lib/fat_period/version.rb
+homepage: https://github.com/ddoherty03/fat_period
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Implements a Period class as a Range of Dates.
+test_files: []