fat_core 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1683ad80cc0beeb11788dc2b0309f61879109de5
-  data.tar.gz: 35f7be2a9a512700ebcc327bff6df8a59ae9b4cf
+  metadata.gz: 1a7476217f8c6438e15010dcb43a6b3e5a7fbdc3
+  data.tar.gz: 99d35b1291dfa588bef9fbed7185e82c12e6b8ad
 SHA512:
-  metadata.gz: 8f0d3d2b01f59d9bd931e477226d3a7631005bdf2c8bc6912c0baaeaa8dc3bf0f97be32bd3851992d75e37b0790b57e406007f7ff7fa8f96c233ce8f3cc4bbff
-  data.tar.gz: b243a502b75d8501e86b899b00cebdfb09ae35659615b0611e82284fdd2497d55df952e381208b32efadbd59c082b8962f6750ede8989a245d0bd81ee5efd87f
+  metadata.gz: 003b3ab76e3d11011b7f67504ea0422d1e34cb8c4f32606a4f0b28e216416d13f18d5e713c78ca30200ded965076e2593b75ff80b0002ff35fffc5abdf487cb9
+  data.tar.gz: 901ad06b503df0199ef15ccf46232d2552cd8ae0eb76bbb0b29da4e4e7036a82b274d5be3b07587917116d2450ae608a877714a3dcce0ca4d03b8658083f1ba6

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.3.3

data/.yardopts

@@ -1 +1,5 @@
---no-private --protected lib/**/*.rb - README LICENSE
+--no-private
+--embed-mixins
+--readme README.md
+--markup-provider=redcarpet
+--markup=markdown

data/README.md

@@ -4,34 +4,151 @@ fat-core is a simple gem to collect core extensions and a few new classes that
 I find useful in multiple projects.  The emphasis is on extending the Date
 class to make it more useful in financial applications.
 
-For example, the Date class adds two methods for determining whether a given
-date is a US federal holiday or a NYSE holiday.
+## Usage
+
+You can extend classes individually by requiring the corresponding file:
+
+```
+    require 'fat_core/array'
+    require 'fat_core/bigdecimal'
+    require 'fat_core/date'
+    require 'fat_core/enumerable'
+    require 'fat_core/hash'
+    require 'fat_core/kernel'
+    require 'fat_core/numeric'
+    require 'fat_core/range'
+    require 'fat_core/string'
+    require 'fat_core/symbol'
+```
+
+Or, you can require them all:
+
+```
+    require 'fat_core/all'
+```
 
+Many of these have little that is of general interest, but there are a few
+goodies.
+
+### Date
+
+For example, the `Date` class adds two methods for determining whether a given
+date is a US federal holiday as defined by federal law, including such things as
+federal holidays established by executive decree:
+
+```
+    require 'fat_core/date'
     Date.parse('2014-05-18').fed_holiday?  => true # It's a weekend
     Date.parse('2014-01-01').fed_holiday?  => true # It's New Years
-
-All holidays defined by federal statute are recognized.
+```
 
 Likewise, days on which the NYSE is closed can be gotten with:
 
+```
     Date.parse('2014-04-18').nyse_holiday? => true # It's Good Friday
-
-Conversely, Date#fed_workday? and Date#nyse_workday? return true if they are
-open for business on those days.
+```
+
+Conversely, `Date#fed_workday?` and `Date#nyse_workday?` return true if the
+federal government and the NYSE respectively are open for business on those
+days.
+
+In addition, the Date class, as extended by FatCore, adds `#next_<chunk>`
+methods for calendar periods in addition to those provided by the core Date
+class: `#next_half`, `#next_quarter`, `#next_bimonth`, and `#next_semimonth`,
+`#next_biweek`. There are also `#prior_<chunk>` variants of these, as well as
+methods for finding the end and beginning of all these periods (e.g.,
+`#beginning_of_bimonth`) and for querying whether a Date is at the beginning or
+end of these periods (e.g., `#beginning_of_bimonth?`, `#end_of_bimonth?`, etc.).
+
+FatCore also provides convenience formatting methods, such as `Date#iso` for
+quickly converting a Date to a string of the form 'YYYY-MM-DD', `Date#org` for
+formatting a Date as an Emacs org-mode timestamp, and several others.
+
+Finally, it provides a `#parse_spec` method for parsing a string, typically
+provided by a user, allowing all the period chunks to be conveniently and
+tersely specified by a user.  For example, the string '2Q' will be parsed as the
+second calendar quarter of the current year, while '2014-3Q' will be parsed as
+the third quarter of the year 2014.
+
+### Range
+
+You can also extend the Range class with several useful methods that emphasize
+coverage of one range by one or more others (`#spanned_by?` and `#gaps`),
+contiguity of Ranges to one another (`#contiguous?`, `#left_contiguous`, and
+`#right_contiguous`, `#join`), and the testing of overlaps between ranges
+(`#overlaps?`, `#overlaps_among?`). These are put to good use in the
+'fat_period' (https://github.com/ddoherty03/fat_period) gem, which combines
+fat_core's extended Range class with its extended Date class to make a useful
+Period class for date ranges, and you may find fat_core's extended Range class
+likewise useful.
+
+For example, you can use the `#gaps` method to find the gaps left in the
+coverage on one Range by an Array of other Ranges:
+
+```
+    require 'fat_core/range'
+    (0..12).gaps([(0..2), (5..7), (10..12)])  => [(3..4), (8..9)]
+```
+
+### Enumerable
+
+FatCore::Enumerable extends Enumerable with the `#each_with_flags` method that
+yields the elements of the Enumerable but also yields two booleans, `first` and
+`last` that are set to true on respectively, the first and last element of the
+Enumerable.  This makes it easy to treat these two cases specially without
+testing the index as in `#each_with_index`.
+
+### Hash
+
+FatCore::Hash extends the Hash class with some useful methods for element
+deletion (`#delete_with_value`) and for manipulating the keys
+(`#keys_with_value`, `#remap_keys` and `#replace_keys`) of a Hash. It also
+provides `#each_pair_with_flags` as an analog to Enumerable's
+`#each_with_flags`.
+
+### TeX Quoting
+
+Several of the extension, most notably 'fat_core/string', provides a
+`#tex_quote` method for quoting the string version of an object so as to allow
+its inclusion in a TeX document and quote characters such as '$' or '%' that
+have a special meaning for TeX.
+
+### String
+
+FatCore::String has methods for performing matching of one string with another
+(`#matches_with`, `#fuzzy_match`), for converting a string to title-case as
+might by used in the title of a book (`#entitle`), for converting a String into
+a useable Symbol (`#as_sym`) and vice-versa (`#as_string` also
+`Symbol#as_string`), for wrapping with an optional hanging indent (`#wrap`),
+cleaning up errant spaces (`#clean`), and computing the Damerau-Levenshtein
+distance between strings (`#distance`). And several others.
+
+### Numbers
+
+FatCore::Numeric has methods for inserting grouping commas into a number
+(`#commas` and `#group`), for converting seconds to HH:MM:SS.dd format
+(`#secs_to_hms`), for testing for integrality (`#whole?` and `#int_if_whole`), and
+testing for sign (`#signum`).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
+```
     gem 'fat_core', :git => 'https://github.com/ddoherty03/fat_core.git'
+```
 
 And then execute:
 
+```
     $ bundle
+```
 
 Or install it yourself as:
 
+```
     $ gem install fat_core
+```
 
 ## Usage
 

data/Rakefile

@@ -1,6 +1,22 @@
 require 'bundler/gem_tasks'
-
 require 'rspec/core/rake_task'
+require 'rdoc/task'
+require 'yard'
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc', 'lib/')
+  rdoc.options << "--ri"
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', 'README.md']
+  t.options << '--no-private'
+  t.options << '--embed-mixins'
+  t.options << '--markup=markdown'
+  t.options << '--markup-provider=redcarpet'
+  #t.stats_options = ['--list-undoc']
+end
 
 RSpec::Core::RakeTask.new(:spec, :tag) do |t|
   t.rspec_opts = '--tag ~online -f p'

data/bin/console

@@ -1,14 +1,13 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "fat_core"
+require 'bundler/setup'
+require 'fat_core/all'
+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')
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
 Pry.start
-
-#require "irb"
-#IRB.start(__FILE__)

data/bin/easters

@@ -1,6 +1,6 @@
 #! /usr/bin/env ruby
 
-require 'fat_core'
+require 'fat_core/date'
 
 base = Date.new(30, 1, 1)
 3000.times do |k|

data/fat_core.gemspec

@@ -13,10 +13,11 @@ Gem::Specification.new do |spec|
   spec.homepage      = ''
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 2.3.1'
+  spec.metadata['yard.run'] = 'yri' # use "yard" to build full HTML docs.
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.files.reject! { |fn| fn =~ /^NYSE_closings.pdf/ }
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.executables   = spec.files.grep(%r{^bin/easter}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
@@ -28,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-doc'
   spec.add_development_dependency 'pry-byebug'
-  spec.add_development_dependency 'rcodetools'
+  spec.add_development_dependency 'redcarpet'
 
   spec.add_runtime_dependency 'activesupport'
   spec.add_runtime_dependency 'erubis'

data/lib/fat_core/all.rb

@@ -1,14 +1,11 @@
 require 'fat_core/array'
-require 'fat_core/big_decimal'
+require 'fat_core/bigdecimal'
 require 'fat_core/date'
-require 'fat_core/boolean'
 require 'fat_core/enumerable'
 require 'fat_core/hash'
 require 'fat_core/kernel'
-#require 'fat_core/latex_eruby'
 require 'fat_core/nil'
 require 'fat_core/numeric'
-require 'fat_core/period'
 require 'fat_core/range'
 require 'fat_core/string'
 require 'fat_core/symbol'

data/lib/fat_core/array.rb

@@ -32,4 +32,7 @@ module FatCore
   end
 end
 
-Array.include FatCore::Array
+class Array
+  include FatCore::Array
+  # @!parse include FatCore::Array
+end

data/lib/fat_core/bigdecimal.rb

@@ -0,0 +1,19 @@
+require 'bigdecimal'
+
+module FatCore
+  module BigDecimal
+    # Provide a human-readable display for BigDecimal. e.g., while debugging.
+    # The inspect method in BigDecimal is unreadable, as it exposes the
+    # underlying implementation, not the number's value. This corrects that.
+    #
+    # @return [String]
+    def inspect
+      to_f.to_s
+    end
+  end
+end
+
+class BigDecimal
+  prepend(FatCore::BigDecimal)
+  # @!parse include FatCore::BigDecimal
+end

data/lib/fat_core/date.rb

@@ -3,69 +3,129 @@ require 'active_support/core_ext/date'
 require 'active_support/core_ext/time'
 require 'active_support/core_ext/numeric/time'
 require 'active_support/core_ext/integer/time'
-require 'fat_core/string'
 
+# ## FatCore Date Extensions
+#
+# The FatCore extensions to the Date class add the notion of several additional
+# calendar periods besides years, months, and weeks to those provided for in the
+# Date class and the active_support extensions to Date.  In particular, there
+# are several additional calendar subdivisions (called "chunks" in this
+# documentation) supported by FatCore's extension to the Date class:
+#
+# * year,
+# * half,
+# * quarter,
+# * bimonth,
+# * month,
+# * semimonth,
+# * biweek,
+# * week, and
+# * day
+#
+# For each of those chunks, there are methods for finding the beginning and end
+# of the chunk, for advancing or retreating a Date by the chunk, and for testing
+# whether a Date is at the beginning or end of each of the chunk.
+#
+# FatCore's Date extension defines a few convenience formatting methods, such as
+# Date#iso and Date#org for formatting Dates as ISO strings and as Emacs
+# org-mode inactive timestamps respectively. It also has a few utility methods
+# for determining the date of Easter, the number of days in any given month, and
+# the Date of the nth workday in a given month (say the third Thursday in
+# October, 2014).
+#
+# The Date extension defines a couple of class methods for parsing strings into
+# Dates, especially Date.parse_spec, which allows Dates to be specified in a
+# lazy way, either absolutely or relative to the computer's clock.
+#
+# Finally FatCore's Date extensions provide thorough methods for determining if
+# a Date is a United States federal holiday or workday based on US law,
+# including executive orders. It does the same for the New York Stock Exchange,
+# based on the rules of the New York Stock Exchange, including dates on which
+# the NYSE was closed for special reasons, such as the 9-11 attacks in 2001.
 module FatCore
   module Date
-    # Constants for Begining of Time (BOT) and End of Time (EOT)
-    # Both outside the range of what we would find in an accounting app.
-    ::Date::BOT = ::Date.parse('1900-01-01')
-    ::Date::EOT = ::Date.parse('3000-12-31')
+    # Constant for Beginning of Time (BOT) outside the range of what we would ever
+    # want to find in commercial situations.
+    BOT = ::Date.parse('1900-01-01')
 
-    # Predecessor of self.  Allows Date to work as a countable element
-    # of a Range.
-    def pred
-      self - 1.day
-    end
+    # Constant for End of Time (EOT) outside the range of what we would ever want
+    # to find in commercial situations.
+    EOT = ::Date.parse('3000-12-31')
 
-    # Successor of self.  Allows Date to work as a countable element
-    # of a Range.
-    def succ
-      self + 1.day
-    end
+    # :category: Formatting
+    # @group Formatting
 
-    # Format as an ISO string.
+    # Format as an ISO string of the form `YYYY-MM-DD`.
+    # @return [String]
     def iso
       strftime('%Y-%m-%d')
     end
 
+    # :category: Formatting
+
     # Format date to TeX documents as ISO strings
+    # @return [String]
     def tex_quote
       iso
     end
 
-    # Format as an all-numeric string, i.e. 'YYYYMMDD'
+    # :category: Formatting
+
+    # Format as an all-numeric string of the form `YYYYMMDD`
+    # @return [String]
     def num
       strftime('%Y%m%d')
     end
 
-    # Format as an inactive Org date (see emacs org-mode)
+    # :category: Formatting
+
+    # Format as an inactive Org date timestamp of the form `[YYYY-MM-DD <dow>]`
+    # (see Emacs org-mode)
+    # @return [String]
     def org
       strftime('[%Y-%m-%d %a]')
     end
 
-    # Format as an English string
+    # :category: Formatting
+
+    # Format as an English string, like `'January 12, 2016'`
+    # @return [String]
     def eng
       strftime('%B %e, %Y')
     end
 
-    # Format date in MM/DD/YYYY form, as typical for the short American
+    # :category: Formatting
+
+    # Format date in `MM/DD/YYYY` form, as typical for the short American
     # form.
+    # @return [String]
     def american
       strftime '%-m/%-d/%Y'
     end
 
+    # :category: Queries
+    # @group Queries
+
     # Does self fall on a weekend?
+    # @return [Boolean]
     def weekend?
       saturday? || sunday?
     end
 
+    # :category: Queries
+
     # Does self fall on a weekday?
+    # @return [Boolean]
     def weekday?
       !weekend?
     end
 
-    # Self's calendar half: 1 or 2
+    # :category: Queries
+
+    # Self's calendar "half" by analogy to calendar quarters: 1 or 2, depending
+    # on whether the date falls in the first or second half of the calendar
+    # year.
+    # @return [1, 2]
     def half
       case month
       when (1..6)
@@ -75,7 +135,11 @@ module FatCore
       end
     end
 
-    # Self's calendar quarter: 1, 2, 3, or 4
+    # :category: Queries
+
+    # Self's calendar quarter: 1, 2, 3, or 4, depending on which calendar quarter
+    # the date falls in.
+    # @return [1, 2, 3, 4]
     def quarter
       case month
       when (1..3)
@@ -89,7 +153,212 @@ module FatCore
       end
     end
 
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a year.
+    # @return [Boolean]
+    def beginning_of_year?
+      beginning_of_year == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a year.
+    # @return [Boolean]
+    def end_of_year?
+      end_of_year == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a half-year.
+    # @return [Boolean]
+    def beginning_of_half?
+      beginning_of_half == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a half-year.
+    # @return [Boolean]
+    def end_of_half?
+      end_of_half == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a calendar quarter.
+    # @return [Boolean]
+    def beginning_of_quarter?
+      beginning_of_quarter == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a calendar quarter.
+    # @return [Boolean]
+    def end_of_quarter?
+      end_of_quarter == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a calendar bi-monthly
+    # period, i.e., the beginning of an odd-numbered month.
+    # @return [Boolean]
+    def beginning_of_bimonth?
+      month.odd? && beginning_of_month == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a calendar bi-monthly
+    # period, i.e., the end of an even-numbered month.
+    # @return [Boolean]
+    def end_of_bimonth?
+      month.even? && end_of_month == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a calendar month.
+    # @return [Boolean]
+    def beginning_of_month?
+      beginning_of_month == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a calendar month.
+    # @return [Boolean]
+    def end_of_month?
+      end_of_month == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a calendar semi-monthly
+    # period, i.e., on the 1st or 15th of a month.
+    # @return [Boolean]
+    def beginning_of_semimonth?
+      beginning_of_semimonth == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a calendar semi-monthly
+    # period, i.e., on the 14th or the last day of a month.
+    # @return [Boolean]
+    def end_of_semimonth?
+      end_of_semimonth == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a commercial bi-week,
+    # i.e., on /Monday/ in a commercial week that is an odd-numbered week. From
+    # ::Date: "The calendar week is a seven day period within a calendar year,
+    # starting on a Monday and identified by its ordinal number within the year;
+    # the first calendar week of the year is the one that includes the first
+    # Thursday of that year. In the Gregorian calendar, this is equivalent to
+    # the week which includes January 4."
+    # @return [Boolean]
+    def beginning_of_biweek?
+      beginning_of_biweek == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the last day of a commercial bi-week,
+    # i.e., on /Sunday/ in a commercial week that is an even-numbered week. From
+    # ::Date: "The calendar week is a seven day period within a calendar year,
+    # starting on a Monday and identified by its ordinal number within the year;
+    # the first calendar week of the year is the one that includes the first
+    # Thursday of that year. In the Gregorian calendar, this is equivalent to
+    # the week which includes January 4."
+    # @return [Boolean]
+    def end_of_biweek?
+      end_of_biweek == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a commercial week, i.e.,
+    # on /Monday/ in a commercial week. From ::Date: "The calendar week is a seven
+    # day period within a calendar year, starting on a Monday and identified by
+    # its ordinal number within the year; the first calendar week of the year is
+    # the one that includes the first Thursday of that year. In the Gregorian
+    # calendar, this is equivalent to the week which includes January 4."
+    # @return [Boolean]
+    def beginning_of_week?
+      beginning_of_week == self
+    end
+
+    # :category: Queries
+
+    # Return whether the date falls on the first day of a commercial week, i.e.,
+    # on /Sunday/ in a commercial week. From ::Date: "The calendar week is a seven
+    # day period within a calendar year, starting on a Monday and identified by
+    # its ordinal number within the year; the first calendar week of the year is
+    # the one that includes the first Thursday of that year. In the Gregorian
+    # calendar, this is equivalent to the week which includes January 4."
+    # @return [Boolean]
+    def end_of_week?
+      end_of_week == self
+    end
+
+    # Return whether this date falls within a period of *less* than six months
+    # from the date `d` using the *Stella v. Graham Page Motors* convention that
+    # "less" than six months is true only if this date falls within the range of
+    # dates 2 days after date six months before and 2 days before the date six
+    # months after the date `d`.
+    #
+    # @param d [::Date] the middle of the six-month range
+    # @return [Boolean]
+    def within_6mos_of?(d)
+      # ::Date 6 calendar months before self
+      start_date = self - 6.months + 2.days
+      end_date = self + 6.months - 2.days
+      (start_date..end_date).cover?(d)
+    end
+
+    # Return whether this date is Easter Sunday for the year in which it falls
+    # according to the Western Church.  A few holidays key off this date as
+    # "moveable feasts."
+    #
+    # @return [Boolean]
+    def easter?
+      # Am I Easter?
+      self == easter_this_year
+    end
+
+    # Return whether this date is the `n`th weekday `wday` of the given `month` in
+    # this date's year.
+    #
+    # @param n [Integer] number of wday in month, if negative count from end of
+    #   the month
+    # @param wday [Integer] day of week, 0 is Sunday, 1 Monday, etc.
+    # @param month [Integer] the month number, 1 is January, 2 is February, etc.
+    # @return [Boolean]
+    def nth_wday_in_month?(n, wday, month)
+      # Is self the nth weekday in the given month of its year?
+      # If n is negative, count from last day of month
+      self == ::Date.nth_wday_in_year_month(n, wday, year, month)
+    end
+
+    # :category: Relative ::Dates
+    # @group Relative ::Dates
+
+    # Predecessor of self, opposite of `#succ`.
+    # @return [::Date]
+    def pred
+      self - 1.day
+    end
+
+    # Note: the ::Date class already has a #succ method.
+
     # The date that is the first day of the half-year in which self falls.
+    # @return [::Date]
     def beginning_of_half
       if month > 9
         (beginning_of_quarter - 15).beginning_of_quarter
@@ -100,7 +369,10 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
     # The date that is the last day of the half-year in which self falls.
+    # @return [::Date]
     def end_of_half
       if month < 4
         (end_of_quarter + 15).end_of_quarter
@@ -111,10 +383,13 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
     # The date that is the first day of the bimonth in which self
     # falls. A 'bimonth' is a two-month calendar period beginning on the
     # first day of the odd-numbered months.  E.g., 2014-01-01 to
     # 2014-02-28 is the first bimonth of 2014.
+    # @return [::Date]
     def beginning_of_bimonth
       if month.odd?
         beginning_of_month
@@ -123,10 +398,13 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
     # The date that is the last day of the bimonth in which self falls.
     # A 'bimonth' is a two-month calendar period beginning on the first
     # day of the odd-numbered months.  E.g., 2014-01-01 to 2014-02-28 is
     # the first bimonth of 2014.
+    # @return [::Date]
     def end_of_bimonth
       if month.odd?
         (self + 1.month).end_of_month
@@ -135,10 +413,13 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
     # The date that is the first day of the semimonth in which self
     # falls.  A semimonth is a calendar period beginning on the 1st or
     # 16th of each month and ending on the 15th or last day of the month
     # respectively.  So each year has exactly 24 semimonths.
+    # @return [::Date]
     def beginning_of_semimonth
       if day >= 16
         ::Date.new(year, month, 16)
@@ -147,10 +428,13 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
     # The date that is the last day of the semimonth in which self
     # falls.  A semimonth is a calendar period beginning on the 1st or
     # 16th of each month and ending on the 15th or last day of the month
     # respectively.  So each year has exactly 24 semimonths.
+    # @return [::Date]
     def end_of_semimonth
       if day <= 15
         ::Date.new(year, month, 15)
@@ -159,8 +443,13 @@ module FatCore
       end
     end
 
-    # Note: we use a Monday start of the week in the next two methods because
-    # commercial week counting assumes a Monday start.
+    # :category: Relative ::Dates
+
+    # Return the date that is the first day of the commercial biweek in which
+    # self falls. A biweek is a period of two commercial weeks starting with an
+    # odd-numbered week and with each week starting in Monday and ending on
+    # Sunday.
+    # @return [::Date]
     def beginning_of_biweek
       if cweek.odd?
         beginning_of_week(:monday)
@@ -169,6 +458,13 @@ module FatCore
       end
     end
 
+    # :category: Relative ::Dates
+
+    # Return the date that is the last day of the commercial biweek in which
+    # self falls. A biweek is a period of two commercial weeks starting with an
+    # odd-numbered week and with each week starting in Monday and ending on
+    # Sunday. So this will always return a Sunday in an even-numbered week.
+    # @return [::Date]
     def end_of_biweek
       if cweek.odd?
         (self + 1.week).end_of_week(:monday)
@@ -177,74 +473,210 @@ module FatCore
       end
     end
 
-    def beginning_of_year?
-      beginning_of_year == self
-    end
-
-    def end_of_year?
-      end_of_year == self
+    # Return the date that is +n+ calendar halves after this date, where a
+    # calendar half is a period of 6 months.
+    #
+    # @param n [Integer] number of halves to advance, can be negative
+    # @return [::Date] new date n halves after this date
+    def next_half(n = 1)
+      n = n.floor
+      return self if n.zero?
+      next_month(n * 6)
     end
 
-    def beginning_of_half?
-      beginning_of_half == self
+    # Return the date that is +n+ calendar halves before this date, where a
+    # calendar half is a period of 6 months.
+    #
+    # @param n [Integer] number of halves to retreat, can be negative
+    # @return [::Date] new date n halves before this date
+    def prior_half(n = 1)
+      next_half(-n)
     end
 
-    def end_of_half?
-      end_of_half == self
+    # Return the date that is +n+ calendar quarters after this date, where a
+    # calendar quarter is a period of 3 months.
+    #
+    # @param n [Integer] number of quarters to advance, can be negative
+    # @return [::Date] new date n quarters after this date
+    def next_quarter(n = 1)
+      n = n.floor
+      return self if n.zero?
+      next_month(n * 3)
     end
 
-    def beginning_of_quarter?
-      beginning_of_quarter == self
+    # Return the date that is +n+ calendar quarters before this date, where a
+    # calendar quarter is a period of 3 months.
+    #
+    # @param n [Integer] number of quarters to retreat, can be negative
+    # @return [::Date] new date n quarters after this date
+    def prior_quarter(n = 1)
+      next_quarter(-n)
     end
 
-    def end_of_quarter?
-      end_of_quarter == self
+    # Return the date that is +n+ calendar bimonths after this date, where a
+    # calendar bimonth is a period of 2 months.
+    #
+    # @param n [Integer] number of bimonths to advance, can be negative
+    # @return [::Date] new date n bimonths after this date
+    def next_bimonth(n = 1)
+      n = n.floor
+      return self if n.zero?
+      next_month(n * 2)
     end
 
-    def beginning_of_bimonth?
-      month.odd? && beginning_of_month == self
+    # Return the date that is +n+ calendar bimonths before this date, where a
+    # calendar bimonth is a period of 2 months.
+    #
+    # @param n [Integer] number of bimonths to retreat, can be negative
+    # @return [::Date] new date n bimonths before this date
+    def prior_bimonth(n = 1)
+      next_bimonth(-n)
     end
 
-    def end_of_bimonth?
-      month.even? && end_of_month == self
+    # Return the date that is +n+ semimonths after this date. Each semimonth begins
+    # on the 1st or 16th of the month, and advancing one semimonth from the first
+    # half of a month means to go as far past the 16th as the current date is past
+    # the 1st; advancing one semimonth from the second half of a month means to go
+    # as far into the next month past the 1st as the current date is past the
+    # 16th, but never past the 15th of the next month.
+    #
+    # @param n [Integer] number of semimonths to advance, can be negative
+    # @return [::Date] new date n semimonths after this date
+    def next_semimonth(n = 1)
+      n = n.floor
+      return self if n.zero?
+      factor = n.negative? ? -1 : 1
+      n = n.abs
+      if n.even?
+        next_month(n / 2)
+      else
+        # Advance or retreat one semimonth
+        next_sm =
+          if day == 1
+            if factor.positive?
+              beginning_of_month + 16.days
+            else
+              prior_month.beginning_of_month + 16.days
+            end
+          elsif day == 16
+            if factor.positive?
+              next_month.beginning_of_month
+            else
+              beginning_of_month
+            end
+          elsif day < 16
+            # In the first half of the month (the 2nd to the 15th), go as far past
+            # the 16th as the date is past the 1st. Thus, as many as 14 days past
+            # the 16th, so at most to the 30th of the month unless there are less
+            # than 30 days in the month, then go to the end of the month.
+            if factor.positive?
+              [beginning_of_month + 16.days + (day - 1).days, end_of_month].min
+            else
+              [prior_month.beginning_of_month + 16.days + (day - 1).days,
+               prior_month.end_of_month].min
+            end
+          else
+            # In the second half of the month (17th to the 31st), go as many
+            # days into the next month as we are past the 16th. Thus, as many as
+            # 15 days.  But we don't want to go past the first half of the next
+            # month, so we only go so far as the 15th of the next month.
+            # ::Date.parse('2015-02-18').next_semimonth should be the 3rd of the
+            # following month.
+            if factor.positive?
+              next_month.beginning_of_month + [(day - 16), 15].min
+            else
+              beginning_of_month + [(day - 16), 15].min
+            end
+          end
+        n -= 1
+        # Now that n is even, advance (or retreat) n / 2 months unless we're done.
+        if n >= 2
+          next_sm.next_month(factor * n / 2)
+        else
+          next_sm
+        end
+      end
     end
 
-    def beginning_of_month?
-      beginning_of_month == self
+    # Return the date that is +n+ semimonths before this date. Each semimonth
+    # begins on the 1st or 15th of the month, and retreating one semimonth from
+    # the first half of a month means to go as far past the 15th of the prior
+    # month as the current date is past the 1st; retreating one semimonth from the
+    # second half of a month means to go as far past the 1st of the current month
+    # as the current date is past the 15th, but never past the 14th of the the
+    # current month.
+    #
+    # @param n [Integer] number of semimonths to retreat, can be negative
+    # @return [::Date] new date n semimonths before this date
+    def prior_semimonth(n = 1)
+      next_semimonth(-n)
     end
 
-    def end_of_month?
-      end_of_month == self
+    # Return the date that is +n+ biweeks after this date where each biweek is 14
+    # days.
+    #
+    # @param n [Integer] number of biweeks to advance, can be negative
+    # @return [::Date] new date n biweeks after this date
+    def next_biweek(n = 1)
+      n = n.floor
+      return self if n.zero?
+      self + (14 * n)
     end
 
-    def beginning_of_semimonth?
-      beginning_of_semimonth == self
+    # Return the date that is +n+ biweeks before this date where each biweek is 14
+    # days.
+    #
+    # @param n [Integer] number of biweeks to retreat, can be negative
+    # @return [::Date] new date n biweeks before this date
+    def prior_biweek(n = 1)
+      next_biweek(-n)
     end
 
-    def end_of_semimonth?
-      end_of_semimonth == self
+    # Return the date that is +n+ weeks after this date where each week is 7 days.
+    # This is different from the #next_week method in active_support, which
+    # goes to the first day of the week in the next week and does not take an
+    # argument +n+ to go multiple weeks.
+    #
+    # @param n [Integer] number of weeks to advance
+    # @return [::Date] new date n weeks after this date
+    def next_week(n = 1)
+      n = n.floor
+      return self if n.zero?
+      self + (7 * n)
     end
 
-    def beginning_of_biweek?
-      beginning_of_biweek == self
+    # Return the date that is +n+ weeks before this date where each week is 7
+    # days.
+    #
+    # @param n [Integer] number of weeks to retreat
+    # @return [::Date] new date n weeks from this date
+    def prior_week(n)
+      next_week(-n)
     end
 
-    def end_of_biweek?
-      end_of_biweek == self
-    end
+    # NOTE: #next_day is defined in active_support.
 
-    def beginning_of_week?
-      beginning_of_week == self
+    # Return the date that is +n+ weeks before this date where each week is 7
+    # days.
+    #
+    # @param n [Integer] number of days to retreat
+    # @return [::Date] new date n days before this date
+    def prior_day(n)
+      next_day(-n)
     end
 
-    def end_of_week?
-      end_of_week == self
-    end
+    # :category: Relative ::Dates
 
-    def add_chunk(chunk)
+    # Return the date that is n chunks later than self.
+    #
+    # @param chunk [Symbol] one of +:year+, +:half+, +:quarter+, +:bimonth+,
+    #   +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.
+    # @param n [Integer] the number of chunks to add, can be negative
+    # @return [::Date] the date n chunks from this date
+    def add_chunk(chunk, n = 1)
       case chunk
       when :year
-        next_year
+        next_year(n)
       when :half
         next_month(6)
       when :quarter
@@ -252,22 +684,29 @@ module FatCore
       when :bimonth
         next_month(2)
       when :month
-        next_month
+        next_month(n)
       when :semimonth
-        self + 15.days
+        next_semimonth(n)
       when :biweek
-        self + 14.days
+        next_biweek(n)
       when :week
-        self + 7.days
+        next_week(n)
       when :day
-        self + 1.days
+        next_day(n)
       else
         raise ArgumentError, "add_chunk unknown chunk: '#{chunk}'"
       end
     end
 
-    def beginning_of_chunk(sym)
-      case sym
+    # Return the date that is the beginning of the +chunk+ in which this date
+    # falls.
+    #
+    # @param chunk [Symbol] one of +:year+, +:half+, +:quarter+, +:bimonth+,
+    #   +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.
+    # @return [::Date] the first date in the chunk-sized period in which this date
+    #   falls
+    def beginning_of_chunk(chunk)
+      case chunk
       when :year
         beginning_of_year
       when :half
@@ -287,12 +726,19 @@ module FatCore
       when :day
         self
       else
-        raise ArgumentError, "unknown chunk sym: '#{sym}'"
+        raise ArgumentError, "unknown chunk sym: '#{chunk}'"
       end
     end
 
-    def end_of_chunk(sym)
-      case sym
+    # Return the date that is the end of the +chunk+ in which this date
+    # falls.
+    #
+    # @param chunk [Symbol] one of +:year+, +:half+, +:quarter+, +:bimonth+,
+    #   +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.
+    # @return [::Date] the first date in the chunk-sized period in which this date
+    #   falls
+    def end_of_chunk(chunk)
+      case chunk
       when :year
         end_of_year
       when :half
@@ -312,45 +758,157 @@ module FatCore
       when :day
         self
       else
-        raise ArgumentError, "unknown chunk sym: '#{sym}'"
+        raise ArgumentError, "unknown chunk: '#{chunk}'"
       end
     end
 
-    def within_6mos_of?(d)
-      # Date 6 calendar months before self
-      start_date = self - 6.months + 2.days
-      end_date = self + 6.months - 2.days
-      (start_date..end_date).cover?(d)
-    end
-
+    # Return the date for Easter in the Western Church for the year in which this
+    # date falls.
+    #
+    # @return [::Date]
     def easter_this_year
       # Return the date of Easter in self's year
       ::Date.easter(year)
     end
 
-    def easter?
-      # Am I Easter?
-      self == easter_this_year
-    end
+    # @group Federal Holidays and Workdays
 
-    def nth_wday_in_month?(n, wday, month)
-      # Is self the nth weekday in the given month of its year?
-      # If n is negative, count from last day of month
-      self == ::Date.nth_wday_in_year_month(n, wday, year, month)
-    end
-
-    #######################################################
-    # Calculations for Federal holidays
-    # 5 USC 6103
-    #######################################################
-    # Holidays decreed by executive order
-    # See http://www.whitehouse.gov/the-press-office/2012/12/21/
-    #  executive-order-closing-executive-departments-and-agencies-federal-gover
+    # Holidays decreed by Presidential proclamation
     FED_DECREED_HOLIDAYS =
       [
+        # Obama decree extra day before Christmas See
+        # http://www.whitehouse.gov/the-press-office/2012/12/21
         ::Date.parse('2012-12-24')
       ].freeze
 
+    # Presidential funeral since JFK
+    PRESIDENTIAL_FUNERALS = [
+      # JKF Funeral
+      ::Date.parse('1963-11-25'),
+      # DWE Funeral
+      ::Date.parse('1969-03-31'),
+      # HST Funeral
+      ::Date.parse('1972-12-28'),
+      # LBJ Funeral
+      ::Date.parse('1973-01-25'),
+      # RMN Funeral
+      ::Date.parse('1994-04-27'),
+      # RWR Funeral
+      ::Date.parse('2004-06-11'),
+      # GTF Funeral
+      ::Date.parse('2007-01-02')
+    ]
+
+    # Return whether this date is a United States federal holiday.
+    #
+    # Calculations for Federal holidays are based on 5 USC 6103, include all
+    # weekends, Presidential funerals, and holidays decreed executive orders.
+    #
+    # @return [Boolean]
+    def fed_holiday?
+      # All Saturdays and Sundays are "holidays"
+      return true if weekend?
+
+      # Some days are holidays by executive decree
+      return true if FED_DECREED_HOLIDAYS.include?(self)
+
+      # Presidential funerals
+      return true if PRESIDENTIAL_FUNERALS.include?(self)
+
+      # Is self a fixed holiday
+      return true if fed_fixed_holiday? || fed_moveable_feast?
+
+      if friday? && month == 12 && day == 26
+        # If Christmas falls on a Thursday, apparently, the Friday after is
+        # treated as a holiday as well.  See 2003, 2008, for example.
+        true
+      elsif friday?
+        # A Friday is a holiday if a fixed-date holiday
+        # would fall on the following Saturday
+        (self + 1).fed_fixed_holiday? || (self + 1).fed_moveable_feast?
+      elsif monday?
+        # A Monday is a holiday if a fixed-date holiday
+        # would fall on the preceding Sunday
+        (self - 1).fed_fixed_holiday? || (self - 1).fed_moveable_feast?
+      elsif (year % 4 == 1) && year > 1965 && mon == 1 && mday == 20
+        # Inauguration Day after 1965 is a federal holiday, but if it falls on a
+        # Sunday, the following Monday is observed, but if it falls on a
+        # Saturday, the prior Friday is /not/ observed. So, we can't just count
+        # this as a regular fixed holiday.
+        true
+      elsif monday? && (year % 4 == 1) && year > 1965 && mon == 1 && mday == 21
+        # Inauguration Day after 1965 is a federal holiday, but if it falls on a
+        # Sunday, the following Monday is observed, but if it falls on a
+        # Saturday, the prior Friday is /not/ observed.
+        true
+      else
+        false
+      end
+    end
+
+    # Return whether this date is a date on which the US federal government is
+    # open for business.  It is the opposite of #fed_holiday?
+    #
+    # @return [Boolean]
+    def fed_workday?
+      !fed_holiday?
+    end
+
+    # :category: Queries
+
+    # Return the date that is n federal workdays after or before (if n < 0) this
+    # date.
+    #
+    # @param n [Integer] number of federal workdays to add to this date
+    # @return [::Date]
+    def add_fed_workdays(n)
+      d = dup
+      return d if n.zero?
+      incr = n.negative? ? -1 : 1
+      n = n.abs
+      while n.positive?
+        d += incr
+        n -= 1 if d.fed_workday?
+      end
+      d
+    end
+
+    # Return the next federal workday after this date. The date returned is always
+    # a date at least one day after this date, never this date.
+    #
+    # @return [::Date]
+    def next_fed_workday
+      add_fed_workdays(1)
+    end
+
+    # Return the last federal workday before this date.  The date returned is always
+    # a date at least one day before this date, never this date.
+    #
+    # @return [::Date]
+    def prior_fed_workday
+      add_fed_workdays(-1)
+    end
+
+    # Return this date if its a federal workday, otherwise skip forward to the
+    # first later federal workday.
+    #
+    # @return [::Date]
+    def next_until_fed_workday
+      date = dup
+      date += 1 until date.fed_workday?
+      date
+    end
+
+    # Return this if its a federal workday, otherwise skip back to the first prior
+    # federal workday.
+    def prior_until_fed_workday
+      date = dup
+      date -= 1 until date.fed_workday?
+      date
+    end
+
+    protected
+
     def fed_fixed_holiday?
       # Fixed-date holidays on weekdays
       if mon == 1 && mday == 1
@@ -399,52 +957,144 @@ module FatCore
       end
     end
 
-    def fed_holiday?
+    # @group NYSE Holidays and Workdays
+
+    # :category: Queries
+
+    public
+
+    # Returns whether this date is one on which the NYSE was or is expected to be
+    # closed for business.
+    #
+    # Calculations for NYSE holidays are from Rule 51 and supplementary materials
+    # for the Rules of the New York Stock Exchange, Inc.
+    #
+    # * General Rule 1: if a regular holiday falls on Saturday, observe it on the preceding Friday.
+    # * General Rule 2: if a regular holiday falls on Sunday, observe it on the following Monday.
+    #
+    # These are the regular holidays:
+    #
+    # * New Year's Day, January 1.
+    # * Birthday of Martin Luther King, Jr., the third Monday in January.
+    # * Washington's Birthday, the third Monday in February.
+    # * Good Friday Friday before Easter Sunday.  NOTE: this is not a fed holiday
+    # * Memorial Day, the last Monday in May.
+    # * Independence Day, July 4.
+    # * Labor Day, the first Monday in September.
+    # * Thanksgiving Day, the fourth Thursday in November.
+    # * Christmas Day, December 25.
+    #
+    # Columbus and Veterans days not observed.
+    #
+    # In addition, there have been several days on which the exchange has been
+    # closed for special events such as Presidential funerals, the 9-11 attacks,
+    # the paper-work crisis in the 1960's, hurricanes, etc.  All of these are
+    # considered holidays for purposes of this method.
+    #
+    # In addition, every weekend is considered a holiday.
+    #
+    # @return [Boolean]
+    def nyse_holiday?
       # All Saturdays and Sundays are "holidays"
       return true if weekend?
 
-      # Some days are holidays by executive decree
-      return true if FED_DECREED_HOLIDAYS.include?(self)
+      # Presidential funerals, observed by NYSE as well.
+      return true if PRESIDENTIAL_FUNERALS.include?(self)
 
       # Is self a fixed holiday
-      return true if fed_fixed_holiday? || fed_moveable_feast?
+      return true if nyse_fixed_holiday? || nyse_moveable_feast?
 
-      if friday? && month == 12 && day == 26
-        # If Christmas falls on a Thursday, apparently, the Friday after is
-        # treated as a holiday as well.  See 2003, 2008, for example.
-        true
-      elsif friday?
-        # A Friday is a holiday if a fixed-date holiday
-        # would fall on the following Saturday
-        (self + 1).fed_fixed_holiday? || (self + 1).fed_moveable_feast?
+      return true if nyse_special_holiday?
+
+      if friday? && (self >= ::Date.parse('1959-07-03'))
+        # A Friday is a holiday if a holiday would fall on the following
+        # Saturday.  The rule does not apply if the Friday "ends a monthly or
+        # yearly accounting period." Adopted July 3, 1959. E.g, December 31,
+        # 2010, fell on a Friday, so New Years was on Saturday, but the NYSE
+        # opened because it ended a yearly accounting period.  I believe 12/31
+        # is the only date to which the exception can apply since only New
+        # Year's can fall on the first of the month.
+        !end_of_quarter? &&
+          ((self + 1).nyse_fixed_holiday? || (self + 1).nyse_moveable_feast?)
       elsif monday?
-        # A Monday is a holiday if a fixed-date holiday
-        # would fall on the preceding Sunday
-        (self - 1).fed_fixed_holiday? || (self - 1).fed_moveable_feast?
+        # A Monday is a holiday if a holiday would fall on the
+        # preceding Sunday.  This has apparently always been the rule.
+        (self - 1).nyse_fixed_holiday? || (self - 1).nyse_moveable_feast?
       else
         false
       end
     end
 
-    #######################################################
-    # Calculations for NYSE holidays
-    # Rule 51 and supplementary material
-    #######################################################
+    # Return whether the NYSE is open for trading on this date.
+    #
+    # @return [Boolean]
+    def nyse_workday?
+      !nyse_holiday?
+    end
+    alias trading_day? nyse_workday?
 
-    # Rule: if it falls on Saturday, observe on preceding Friday.
-    # Rule: if it falls on Sunday, observe on following Monday.
+    # Return the date that is n NYSE trading days after or before (if n < 0) this
+    # date.
     #
-    # New Year's Day, January 1.
-    # Birthday of Martin Luther King, Jr., the third Monday in January.
-    # Washington's Birthday, the third Monday in February.
-    # Good Friday Friday before Easter Sunday.  NOTE: not a fed holiday
-    # Memorial Day, the last Monday in May.
-    # Independence Day, July 4.
-    # Labor Day, the first Monday in September.
-    # NOTE: Columbus and Veterans days not observed
-    # Thanksgiving Day, the fourth Thursday in November.
-    # Christmas Day, December 25.
+    # @param n [Integer] number of NYSE trading days to add to this date
+    # @return [::Date]
+    def add_nyse_workdays(n)
+      d = dup
+      return d if n.zero?
+      incr = n.negative? ? -1 : 1
+      n = n.abs
+      while n.positive?
+        d += incr
+        n -= 1 if d.nyse_workday?
+      end
+      d
+    end
+    alias add_trading_days add_nyse_workdays
+
+    # Return the next NYSE trading day after this date. The date returned is always
+    # a date at least one day after this date, never this date.
+    #
+    # @return [::Date]
+    def next_nyse_workday
+      add_nyse_workdays(1)
+    end
+    alias next_trading_day next_nyse_workday
+
+    # Return the last NYSE trading day before this date. The date returned is always
+    # a date at least one day before this date, never this date.
+    #
+    # @return [::Date]
+    def prior_nyse_workday
+      add_nyse_workdays(-1)
+    end
+    alias prior_trading_day prior_nyse_workday
+
+    # Return this date if its a trading day, otherwise skip forward to the first
+    # later trading day.
+    #
+    # @return [::Date]
+    def next_until_trading_day
+      date = dup
+      date += 1 until date.trading_day?
+      date
+    end
+
+    # Return this date if its a trading day, otherwise skip back to the first prior
+    # trading day.
+    #
+    # @return [::Date]
+    def prior_until_trading_day
+      date = dup
+      date -= 1 until date.trading_day?
+      date
+    end
 
+    protected
+
+    # Return whether this date is a fixed holiday for the NYSE, that is, a holiday
+    # that falls on the same date each year.
+    #
+    # @return [Boolean]
     def nyse_fixed_holiday?
       # Fixed-date holidays
       if mon == 1 && mday == 1
@@ -461,6 +1111,12 @@ module FatCore
       end
     end
 
+    # :category: Queries
+
+    # Return whether this date is a non-fixed holiday for the NYSE, that is, a holiday
+    # that can fall on different dates each year, a so-called "moveable feast".
+    #
+    # @return [Boolean]
     def nyse_moveable_feast?
       # See if today is a "movable feast," all of which are
       # rigged to fall on Monday except Thanksgiving
@@ -537,11 +1193,17 @@ module FatCore
       end
     end
 
+    # :category: Queries
+
     # They NYSE has closed on several occasions outside its normal holiday
     # rules.  This detects those dates beginning in 1960.  Closing for part of a
-    # day is not counted. See http://www1.nyse.com/pdfs/closings.pdf
+    # day is not counted. See http://www1.nyse.com/pdfs/closings.pdf.  Return
+    # whether this date is one of those special closings.
+    #
+    # @return [Boolean]
     def nyse_special_holiday?
       return false unless self > ::Date.parse('1960-01-01')
+      return true if PRESIDENTIAL_FUNERALS.include?(self)
       case self
       when ::Date.parse('1961-05-29')
         # Day before Decoaration Day
@@ -568,33 +1230,17 @@ module FatCore
       when ::Date.parse('1969-02-10')
         # Heavy snow
         true
-      when ::Date.parse('1969-05-31')
-        # Eisenhower Funeral
-        true
       when ::Date.parse('1969-07-21')
         # Moon landing
         true
-      when ::Date.parse('1972-12-28')
-        # Truman Funeral
-        true
-      when ::Date.parse('1973-01-25')
-        # Johnson Funeral
-        true
       when ::Date.parse('1977-07-14')
         # Electrical blackout NYC
         true
       when ::Date.parse('1985-09-27')
         # Hurricane Gloria
         true
-      when ::Date.parse('1994-04-27')
-        # Nixon Funeral
-        true
       when (::Date.parse('2001-09-11')..::Date.parse('2001-09-14'))
         # 9-11 Attacks
-        a = a
-        true
-      when (::Date.parse('2004-06-11')..::Date.parse('2001-09-14'))
-        # Reagan Funeral
         true
       when ::Date.parse('2007-01-02')
         # Observance death of President Ford
@@ -607,123 +1253,29 @@ module FatCore
       end
     end
 
-    def nyse_holiday?
-      # All Saturdays and Sundays are "holidays"
-      return true if weekend?
-
-      # Is self a fixed holiday
-      return true if nyse_fixed_holiday? || nyse_moveable_feast?
-
-      return true if nyse_special_holiday?
-
-      if friday? && (self >= ::Date.parse('1959-07-03'))
-        # A Friday is a holiday if a holiday would fall on the following
-        # Saturday.  The rule does not apply if the Friday "ends a monthly or
-        # yearly accounting period." Adopted July 3, 1959. E.g, December 31,
-        # 2010, fell on a Friday, so New Years was on Saturday, but the NYSE
-        # opened because it ended a yearly accounting period.  I believe 12/31
-        # is the only date to which the exception can apply since only New
-        # Year's can fall on the first of the month.
-        !end_of_quarter? &&
-          ((self + 1).nyse_fixed_holiday? || (self + 1).nyse_moveable_feast?)
-      elsif monday?
-        # A Monday is a holiday if a holiday would fall on the
-        # preceding Sunday.  This has apparently always been the rule.
-        (self - 1).nyse_fixed_holiday? || (self - 1).nyse_moveable_feast?
-      else
-        false
-      end
-    end
-
-    def fed_workday?
-      !fed_holiday?
-    end
-
-    def nyse_workday?
-      !nyse_holiday?
-    end
-    alias trading_day? nyse_workday?
-
-    def add_fed_business_days(n)
-      d = dup
-      return d if n.zero?
-      incr = n.negative? ? -1 : 1
-      n = n.abs
-      while n.positive?
-        d += incr
-        n -= 1 if d.fed_workday?
-      end
-      d
-    end
-
-    def next_fed_workday
-      add_fed_business_days(1)
-    end
-
-    def prior_fed_workday
-      add_fed_business_days(-1)
-    end
-
-    def add_nyse_business_days(n)
-      d = dup
-      return d if n.zero?
-      incr = n.negative? ? -1 : 1
-      n = n.abs
-      while n.positive?
-        d += incr
-        n -= 1 if d.nyse_workday?
-      end
-      d
-    end
-    alias add_trading_days add_nyse_business_days
-
-    def next_nyse_workday
-      add_nyse_business_days(1)
-    end
-    alias next_trading_day next_nyse_workday
-
-    def prior_nyse_workday
-      add_nyse_business_days(-1)
-    end
-    alias prior_trading_day prior_nyse_workday
-
-    # Return self if its a trading day, otherwise skip back to the first prior
-    # trading day.
-    def prior_until_trading_day
-      date = dup
-      date -= 1 until date.trading_day?
-      date
-    end
-
-    # Return self if its a trading day, otherwise skip forward to the first
-    # later trading day.
-    def next_until_trading_day
-      date = dup
-      date += 1 until date.trading_day?
-      date
-    end
-
     module ClassMethods
-      # Convert a string with an American style date into a Date object
+      # @group Parsing
+      #
+      # Convert a string +str+ with an American style date into a ::Date object
       #
-      # An American style date is of the form MM/DD/YYYY, that is it places the
-      # month first, then the day of the month, and finally the year.  The
-      # European convention is to place the day of the month first, DD/MM/YYYY.
-      # Because a date found in the wild can be ambiguous, e.g. 3/5/2014, a date
+      # An American style date is of the form `MM/DD/YYYY`, that is it places the
+      # month first, then the day of the month, and finally the year. The European
+      # convention is typically to place the day of the month first, `DD/MM/YYYY`.
+      # A date found in the wild can be ambiguous, e.g. 3/5/2014, but a date
       # string known to be using the American convention can be parsed using this
-      # method.  Both the month and the day can be a single digit.  The year can
-      # be either 2 or 4 digits, and if given as 2 digits, it adds 2000 to it to
-      # give the year.
+      # method. Both the month and the day can be a single digit. The year can be
+      # either 2 or 4 digits, and if given as 2 digits, it adds 2000 to it to give
+      # the year.
       #
       # @example
-      #     Date.parse_american('9/11/2001') #=> Date(2011, 9, 11)
-      #     Date.parse_american('9/11/01')   #=> Date(2011, 9, 11)
-      #     Date.parse_american('9/11/1')    #=> ArgumentError
+      #   ::Date.parse_american('9/11/2001') #=> ::Date(2011, 9, 11)
+      #   ::Date.parse_american('9/11/01')   #=> ::Date(2011, 9, 11)
+      #   ::Date.parse_american('9/11/1')    #=> ArgumentError
       #
-      # @param str [#to_s] a stringling of the form MM/DD/YYYY
-      # @return [Date] the date represented by the string paramenter.
+      # @param str [String, #to_s] a stringling of the form MM/DD/YYYY
+      # @return [::Date] the date represented by the str paramenter.
       def parse_american(str)
-        unless str.to_s =~ %r{\A\s*(\d\d?)\s*/\s*(\d\d?)\s*/\s*(\d?\d?\d\d)\s*\z}
+        unless str.to_s =~ %r{\A\s*(\d\d?)\s*/\s*(\d\d?)\s*/\s*((\d\d)?\d\d)\s*\z}
           raise ArgumentError, "date string must be of form 'MM?/DD?/YY(YY)?'"
         end
         year = $3.to_i
@@ -733,31 +1285,58 @@ module FatCore
         ::Date.new(year, month, day)
       end
 
-      # Convert a 'date spec' to a Date.  A date spec is a short-hand way of
-      # specifying a date, relative to the computer clock.  A date spec can
-      # interpreted as either a 'from spec' or a 'to spec'.
-      # @example
+      # Convert a 'period spec' `spec` to a ::Date. A date spec is a short-hand way of
+      # specifying a calendar period either absolutely or relative to the computer
+      # clock. This method returns the first date of that period, when `spec_type`
+      # is set to `:from`, the default, and returns the last date of the period
+      # when `spec_type` is `:to`.
+      #
+      # There are a number of forms the `spec` can take. In each case,
+      # `::Date.parse_spec` returns the first date in the period if `spec_type` is
+      # `:from` and the last date in the period if `spec_type` is `:to`:
       #
-      # Assuming that Date.current at the time of execution is 2014-07-26 and
-      # using the default spec_type of :from.  The return values are actually Date
-      # objects, but are shown below as textual dates.
+      # * `YYYY` is the whole year `YYYY`,
+      # * `YYYY-1H` or `YYYY-H1` is the first calendar half in year `YYYY`,
+      # * `H2` or `2H` is the second calendar half of the current year,
+      # * `YYYY-3Q` or `YYYY-Q3` is the third calendar quarter of year YYYY,
+      # * `Q3` or `3Q` is the third calendar quarter in the current year,
+      # * `YYYY-04` or `YYYY-4` is April, the fourth month of year `YYYY`,
+      # * `4-12` or `04-12` is the 12th of April in the current year,
+      # * `4` or `04` is April in the current year,
+      # * `YYYY-W32` or `YYYY-32W` is the 32nd week in year YYYY,
+      # * `W32` or `32W` is the 32nd week in the current year,
+      # * `YYYY-MM-DD` a particular date, so `:from` and `:to` return the same
+      #   date,
+      # * `this_<chunk>` where `<chunk>` is one of `year`, `half`, `quarter`,
+      #   `bimonth`, `month`, `semimonth`, `biweek`, `week`, or `day`, the
+      #   corresponding calendar period in which the current date falls,
+      # * `last_<chunk>` where `<chunk>` is one of `year`, `half`, `quarter`,
+      #   `bimonth`, `month`, `semimonth`, `biweek`, `week`, or `day`, the
+      #   corresponding calendar period immediately before the one in which the
+      #   current date falls,
+      # * `today` is the same as `this_day`,
+      # * `yesterday` is the same as `last_day`,
+      # * `forever` is the period from ::Date::BOT to ::Date::EOT, essentially all
+      #   dates of commercial interest, and
+      # * `never` causes the method to return nil.
+      #
+      # In all of the above example specs, letter used for calendar chunks, `W`,
+      # `Q`, and `H` can be written in lower case as well. Also, you can use `/`
+      # to separate date components instead of `-`.
+      #
+      # @example
+      #   ::Date.parse_spec('2012-W32').iso      # => "2012-08-06"
+      #   ::Date.parse_spec('2012-W32', :to).iso # => "2012-08-12"
+      #   ::Date.parse_spec('W32').iso           # => "2012-08-06" if executed in 2012
+      #   ::Date.parse_spec('W32').iso           # => "2012-08-04" if executed in 2014
       #
-      # A fully specified date returns that date:
-      #     Date.parse_spec('2001-09-11')  # =>
-      # Commercial weeks can be specified using, for example W32 or 32W, with the
-      # week beginning on Monday, ending on Sunday.
-      #     Date.parse_spec('2012-W32')    # =>
-      #     Date.parse_spec('2012-W32', :to) # =>
-      #     Date.parse_spec('W32') # =>
+      # @param spec [String, #to_s] the spec to be interpreted as a calendar period
       #
-      # A spec of the form Q3 or 3Q returns the beginning or end of calendar
-      # quarters.
-      #     Date.parse_spec('Q3')         # =>
+      # @param spec_type [:from, :to] return the first (:from) or last (:to)
+      #   date in the spec's period respectively
       #
-      # @param spec [#to_s] a stringling containing the spec to be interpreted
-      # @param spec_type [:from, :to] interpret the spec as a from- or to-spec
-      #   respectively, defaulting to interpretation as a to-spec.
-      # @return [Date] a date object equivalent to the date spec
+      # @return [::Date] date that is the first (:from) or last (:to) in the period
+      #   designated by spec
       def parse_spec(spec, spec_type = :from)
         spec = spec.to_s.strip
         unless [:from, :to].include?(spec_type)
@@ -772,7 +1351,7 @@ module FatCore
         when /\AW(\d\d?)\z/, /\A(\d\d?)W\z/
           week_num = $1.to_i
           if week_num < 1 || week_num > 53
-            raise ArgumentError, "invalid week number (1-53): 'W#{week_num}'"
+            raise ArgumentError, "invalid week number (1-53): '#{spec}'"
           end
           if spec_type == :from
             ::Date.commercial(today.year, week_num).beginning_of_week
@@ -783,7 +1362,7 @@ module FatCore
           year = $1.to_i
           week_num = $2.to_i
           if week_num < 1 || week_num > 53
-            raise ArgumentError, "invalid week number (1-53): 'W#{week_num}'"
+            raise ArgumentError, "invalid week number (1-53): '#{spec}'"
           end
           if spec_type == :from
             ::Date.commercial(year, week_num).beginning_of_week
@@ -795,7 +1374,7 @@ module FatCore
           year = $1.to_i
           quarter = $2.to_i
           unless [1, 2, 3, 4].include?(quarter)
-            raise ArgumentError, "bad date format: #{spec}"
+            raise ArgumentError, "invalid quarter number (1-4): '#{spec}'"
           end
           month = quarter * 3
           if spec_type == :from
@@ -807,6 +1386,9 @@ module FatCore
           # Quarter only
           this_year = today.year
           quarter = $1.to_i
+          unless [1, 2, 3, 4].include?(quarter)
+            raise ArgumentError, "invalid quarter number (1-4): '#{spec}'"
+          end
           date = ::Date.new(this_year, quarter * 3, 15)
           if spec_type == :from
             date.beginning_of_quarter
@@ -818,7 +1400,7 @@ module FatCore
           year = $1.to_i
           half = $2.to_i
           unless [1, 2].include?(half)
-            raise ArgumentError, "bad date format: #{spec}"
+            raise ArgumentError, "invalid half number: '#{spec}'"
           end
           month = half * 6
           if spec_type == :from
@@ -830,6 +1412,9 @@ module FatCore
           # Half only
           this_year = today.year
           half = $1.to_i
+          unless [1, 2].include?(half)
+            raise ArgumentError, "invalid half number: '#{spec}'"
+          end
           date = ::Date.new(this_year, half * 6, 15)
           if spec_type == :from
             date.beginning_of_half
@@ -838,24 +1423,38 @@ module FatCore
           end
         when /^(\d\d\d\d)[-\/](\d\d?)*$/
           # Year-Month only
+          year = $1.to_i
+          month = $2.to_i
+          unless [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].include?(month)
+            raise ArgumentError, "invalid month number (1-12): '#{spec}'"
+          end
           if spec_type == :from
-            ::Date.new($1.to_i, $2.to_i, 1)
+            ::Date.new(year, month, 1)
           else
-            ::Date.new($1.to_i, $2.to_i, 1).end_of_month
+            ::Date.new(year, month, 1).end_of_month
           end
         when /^(\d\d?)[-\/](\d\d?)*$/
           # Month-Day only
+          month = $1.to_i
+          day = $2.to_i
+          unless [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].include?(month)
+            raise ArgumentError, "invalid month number (1-12): '#{spec}'"
+          end
           if spec_type == :from
-            ::Date.new(today.year, $1.to_i, $2.to_i)
+            ::Date.new(today.year, month, day)
           else
-            ::Date.new(today.year, $1.to_i, $2.to_i).end_of_month
+            ::Date.new(today.year, month, day).end_of_month
           end
         when /\A(\d\d?)\z/
           # Month only
+          month = $1.to_i
+          unless [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].include?(month)
+            raise ArgumentError, "invalid month number (1-12): '#{spec}'"
+          end
           if spec_type == :from
-            ::Date.new(today.year, $1.to_i, 1)
+            ::Date.new(today.year, month, 1)
           else
-            ::Date.new(today.year, $1.to_i, 1).end_of_month
+            ::Date.new(today.year, month, 1).end_of_month
           end
         when /^(\d\d\d\d)$/
           # Year only
@@ -966,11 +1565,15 @@ module FatCore
           nil
         else
           raise ArgumentError, "bad date spec: '#{spec}''"
-        end # !> previous definition of length was here
+        end
       end
 
+      # @group Utilities
+
+      # An Array of the number of days in each month indexed by month number,
+      # starting with January = 1, etc.
       COMMON_YEAR_DAYS_IN_MONTH = [31, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31,
-                                   30, 31]
+                                   30, 31].freeze
       def days_in_month(y, m)
         raise ArgumentError, 'illegal month number' if m < 1 || m > 12
         days = COMMON_YEAR_DAYS_IN_MONTH[m]
@@ -981,9 +1584,14 @@ module FatCore
         end
       end
 
+      # Return the nth weekday in the given month. If n is negative, count from
+      # last day of month.
+      #
+      # @param n [Integer] the ordinal number for the weekday
+      # @param wday [Integer] the weekday of interest with Monday 0 to Sunday 6
+      # @param year [Integer] the year of interest
+      # @param month [Integer] the month of interest with January 1 to December 12
       def nth_wday_in_year_month(n, wday, year, month)
-        # Return the nth weekday in the given month
-        # If n is negative, count from last day of month
         wday = wday.to_i
         raise ArgumentError, 'illegal weekday number' if wday < 0 || wday > 6
         month = month.to_i
@@ -1013,11 +1621,14 @@ module FatCore
           end
           d
         else
-          raise ArgumentError,
-                'Arg 1 to nth_wday_in_month_year cannot be zero'
+          raise ArgumentError, 'Argument n cannot be zero'
         end
       end
 
+      # Return the date of Easter for the Western Church in the given year.
+      #
+      # @param year [Integer] the year of interest
+      # @return [::Date] the date of Easter for year
       def easter(year)
         y = year
         a = y % 19
@@ -1034,13 +1645,17 @@ module FatCore
       end
     end
 
-    # This hook gets called by the host class when it includes this
-    # module, extending that class to include the methods defined in
-    # ClassMethods as class methods of the host class.
-    def self.included(host_class)
-      host_class.extend(ClassMethods)
+    public
+
+    # @private
+    def self.included(base)
+      base.extend(ClassMethods)
     end
   end
 end
 
-Date.include(FatCore::Date)
+class Date
+  include FatCore::Date
+  # @!parse include FatCore::Date
+  # @!parse extend FatCore::Date::ClassMethods
+end