fat_core 5.1.0 → 5.3.0

data/lib/fat_core/date.rb

@@ -9,49 +9,46 @@ require 'active_support/core_ext/integer/time'
 require 'fat_core/string'
 require 'fat_core/patches'
 
-# ## 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
+  # ## 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 Date
-    # Set the default beginning of week to Monday for commercial weeks.
-    # ::Date.beginning_of_week = :monday
-
     # 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')
@@ -369,7 +366,7 @@ module FatCore
     # @param from_date [::Date] the middle of the six-month range
     # @return [Boolean]
     def within_6mos_of?(from_date)
-      from_date = Date.parse(from_date) unless from_date.is_a?(Date)
+      from_date = ::Date.parse(from_date) unless from_date.is_a?(Date)
       from_day = from_date.day
       if [28, 29, 30, 31].include?(from_day)
         # Near the end of the month, we need to make sure that when we go
@@ -550,6 +547,8 @@ module FatCore
       end
     end
 
+    # NOTE: Date#end_of_week and Date#beginning_of_week is defined in ActiveSupport
+
     # Return the date that is +n+ calendar halves after this date, where a
     # calendar half is a period of 6 months.
     #
@@ -653,8 +652,10 @@ module FatCore
             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
+              [
+                prior_month.beginning_of_month + 16.days + (day - 1).days,
+                prior_month.end_of_month
+              ].min
             end
           elsif factor.positive?
             # In the second half of the month (17th to the 31st), go as many
@@ -1199,11 +1200,12 @@ module FatCore
     # later trading day.
     #
     # @return [::Date]
-    def next_until_trading_day
+    def next_until_nyse_workday
       date = dup
       date += 1 until date.trading_day?
       date
     end
+    alias_method :next_until_trading_day, :next_until_nyse_workday
 
     # Return this date if its a trading day, otherwise skip back to the first prior
     # trading day.
@@ -1330,7 +1332,7 @@ module FatCore
     #
     # @return [Boolean]
     def nyse_special_holiday?
-      return false unless self > ::Date.parse('1960-01-01')
+      return false if self <= ::Date.parse('1960-01-01')
 
       return true if PRESIDENTIAL_FUNERALS.include?(self)
 
@@ -1427,6 +1429,7 @@ module FatCore
       # `::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`:
       #
+      # * `YYYY-MM-DD` a particular date, so `:from` and `:to` return the same
       # * `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,
@@ -1437,8 +1440,19 @@ module FatCore
       # * `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,
+      # * `W32-4` or `32W-4` is the 4th day of the 32nd week in the current year,
+      # * `YYYY-MM-I` or `YYYY-MM-II` is the first or second half of the given month,
+      # * `YYYY-MM-i` or `YYYY-MM-v` is the first or fifth week of the given month,
+      # * `MM-i` or `MM-v` is the first or fifth week of the current month,
+      # * `YYYY-MM-3Tu` or `YYYY-MM-4Mo` is the third Tuesdsay and fourth Monday of the given month,
+      # * `MM-3Tu` or `MM-4Mo` is the third Tuesdsay and fourth Monday of the given month in the current year,
+      # * `3Tu` or `4Mo` is the third Tuesdsay and fourth Monday of the current month,
+      # * `YYYY-E` is Easter of the given year YYYY,
+      # * `E` is Easter of the current year YYYY,
+      # * `YYYY-E+50` and `YYYY-E-40` is 50 days after and 40 days before Easter of the given year,
+      # * `E+50` and `E-40` is 50 days after and 40 days before Easter of the current year,
+      # * `YYYY-001` and `YYYY-182` is first and 182nd day of the given year,
+      # * `001` and `182` is first and 182nd day of the current year,
       # * `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,
@@ -1470,43 +1484,64 @@ module FatCore
       # @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
+        spec = spec.to_s.strip.clean
         unless %i[from to].include?(spec_type)
           raise ArgumentError, "invalid date spec type: '#{spec_type}'"
         end
 
         today = ::Date.current
-        case spec.clean
-        when %r{\A(?<yr>\d\d\d\d)[-/](?<mo>\d\d?)[-/](?<dy>\d\d?)\z}
-          # A specified date
-          ::Date.new(Regexp.last_match[:yr].to_i, Regexp.last_match[:mo].to_i,
-                     Regexp.last_match[:dy].to_i)
-        when /\AW(?<wk>\d\d?)\z/, /\A(?<wk>\d\d?)W\z/
-          week_num = Regexp.last_match[:wk].to_i
-          if week_num < 1 || week_num > 53
-            raise ArgumentError, "invalid week number (1-53): '#{spec}'"
+        case spec
+        when %r{\A((?<yr>\d\d\d\d)[-/])?(?<doy>\d\d\d)\z}
+          # With 3-digit YYYY-ddd, return the day-of-year
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
+          doy = Regexp.last_match[:doy].to_i
+          max_doy = ::Date.gregorian_leap?(year) ? 366 : 365
+          if doy > max_doy
+            raise ArgumentError, "invalid day-of-year '#{doy}' (1..#{max_doy}) in '#{spec}'"
           end
 
-          if spec_type == :from
-            ::Date.commercial(today.year, week_num).beginning_of_week
+          ::Date.new(year, 1, 1) + doy - 1
+        when %r{\A((?<yr>\d\d\d\d)[-/])?(?<mo>\d\d?)([-/](?<dy>\d\d?))?\z}
+          # MM, YYYY-MM, MM-DD
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
+          month = Regexp.last_match[:mo].to_i
+          day = Regexp.last_match[:dy]&.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 day
+            ::Date.new(year, month, day)
+          elsif spec_type == :from
+            ::Date.new(year, month, 1)
           else
-            ::Date.commercial(today.year, week_num).end_of_week
+            ::Date.new(year, month, 1).end_of_month
           end
-        when %r{\A(?<yr>\d\d\d\d)[-/]W(?<wk>\d\d?)\z}, %r{\A(?<yr>\d\d\d\d)[-/](?<wk>\d\d?)W\z}
-          year = Regexp.last_match[:yr].to_i
+        when %r{\A((?<yr>\d\d\d\d)[-/])?(?<wk>\d\d?)W(-(?<dy>\d))?\z}xi,
+          %r{\A((?<yr>\d\d\d\d)[-/])?W(?<wk>\d\d?)(-(?<dy>\d))?\z}xi
+          # Commercial week numbers.  The first commercial 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.  This appears to be the equivalent of ISO 8601 week
+          # number as described at https://en.wikipedia.org/wiki/ISO_week_date
+          year = Regexp.last_match[:yr]&.to_i
           week_num = Regexp.last_match[:wk].to_i
-          if week_num < 1 || week_num > 53
+          day = Regexp.last_match[:dy]&.to_i
+          unless (1..53).cover?(week_num)
             raise ArgumentError, "invalid week number (1-53): '#{spec}'"
           end
+          if day && !(1..7).cover?(day)
+            raise ArgumentError, "invalid ISO day number (1-7): '#{spec}'"
+          end
 
           if spec_type == :from
-            ::Date.commercial(year, week_num).beginning_of_week
+            ::Date.commercial(year ? year : today.year, week_num, day ? day : 1)
           else
-            ::Date.commercial(year, week_num).end_of_week
+            ::Date.commercial(year ? year : today.year, week_num, day ? day : 7)
           end
-        when %r{^(?<yr>\d\d\d\d)[-/](?<qt>\d)[Qq]$}, %r{^(?<yr>\d\d\d\d)[-/][Qq](?<qt>\d)$}
+        when %r{^((?<yr>\d\d\d\d)[-/])?(?<qt>\d)[Qq]$}, %r{^((?<yr>\d\d\d\d)[-/])?[Qq](?<qt>\d)$}
           # Year-Quarter
-          year = Regexp.last_match[:yr].to_i
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
           quarter = Regexp.last_match[:qt].to_i
           unless [1, 2, 3, 4].include?(quarter)
             raise ArgumentError, "invalid quarter number (1-4): '#{spec}'"
@@ -1518,26 +1553,12 @@ module FatCore
           else
             ::Date.new(year, month, 1).end_of_quarter
           end
-        when /^(?<qt>[1234])[qQ]$/, /^[qQ](?<qt>[1234])$/
-          # Quarter only
-          this_year = today.year
-          quarter = Regexp.last_match[:qt].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
-          else
-            date.end_of_quarter
-          end
-        when %r{^(?<yr>\d\d\d\d)[-/](?<hf>\d)[Hh]$}, %r{^(?<yr>\d\d\d\d)[-/][Hh](?<hf>\d)$}
+        when %r{^((?<yr>\d\d\d\d)[-/])?(?<hf>\d)[Hh]$}, %r{^((?<yr>\d\d\d\d)[-/])?[Hh](?<hf>\d)$}
           # Year-Half
-          year = Regexp.last_match[:yr].to_i
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
           half = Regexp.last_match[:hf].to_i
           msg = "invalid half number: '#{spec}'"
-          raise ArgumentError,  msg unless [1, 2].include?(half)
+          raise ArgumentError, msg unless [1, 2].include?(half)
 
           month = half * 6
           if spec_type == :from
@@ -1545,58 +1566,7 @@ module FatCore
           else
             ::Date.new(year, month, 1).end_of_half
           end
-        when /^(?<hf>[12])[hH]$/, /^[hH](?<hf>[12])$/
-          # Half only
-          this_year = today.year
-          half = Regexp.last_match[:hf].to_i
-          msg = "invalid half number: '#{spec}'"
-          raise ArgumentError, msg unless [1, 2].include?(half)
-
-          date = ::Date.new(this_year, half * 6, 15)
-          if spec_type == :from
-            date.beginning_of_half
-          else
-            date.end_of_half
-          end
-        when %r{^(?<yr>\d\d\d\d)[-/](?<mo>\d\d?)*$}
-          # Year-Month only
-          year = Regexp.last_match[:yr].to_i
-          month = Regexp.last_match[:mo].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(year, month, 1)
-          else
-            ::Date.new(year, month, 1).end_of_month
-          end
-        when %r{^(?<mo>\d\d?)[-/](?<dy>\d\d?)*$}
-          # Month-Day only
-          month = Regexp.last_match[:mo].to_i
-          day = Regexp.last_match[:dy].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, month, day)
-          else
-            ::Date.new(today.year, month, day).end_of_month
-          end
-        when /\A(?<mo>\d\d?)\z/
-          # Month only
-          month = Regexp.last_match[:mo].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, month, 1)
-          else
-            ::Date.new(today.year, month, 1).end_of_month
-          end
-        when /^(?<yr>\d\d\d\d)$/
+        when /\A(?<yr>\d\d\d\d)\z/
           # Year only
           year = Regexp.last_match[:yr].to_i
           if spec_type == :from
@@ -1604,105 +1574,88 @@ module FatCore
           else
             ::Date.new(year, 12, 31)
           end
-        when /^(to|this_?)?day/
-          today
-        when /^(yester|last_?)?day/
-          today - 1.day
-        when /^(this_?)?week/
-          spec_type == :from ? today.beginning_of_week : today.end_of_week
-        when /last_?week/
-          if spec_type == :from
-            (today - 1.week).beginning_of_week
-          else
-            (today - 1.week).end_of_week
-          end
-        when /^(this_?)?biweek/
-          if spec_type == :from
-            today.beginning_of_biweek
-          else
-            today.end_of_biweek
-          end
-        when /last_?biweek/
-          if spec_type == :from
-            (today - 2.week).beginning_of_biweek
-          else
-            (today - 2.week).end_of_biweek
-          end
-        when /^(this_?)?semimonth/
-          spec_type == :from ? today.beginning_of_semimonth : today.end_of_semimonth
-        when /^last_?semimonth/
-          if spec_type == :from
-            (today - 15.days).beginning_of_semimonth
-          else
-            (today - 15.days).end_of_semimonth
-          end
-        when /^(this_?)?month/
-          if spec_type == :from
-            today.beginning_of_month
-          else
-            today.end_of_month
-          end
-        when /^last_?month/
-          if spec_type == :from
-            (today - 1.month).beginning_of_month
-          else
-            (today - 1.month).end_of_month
-          end
-        when /^(this_?)?bimonth/
-          if spec_type == :from
-            today.beginning_of_bimonth
-          else
-            today.end_of_bimonth
-          end
-        when /^last_?bimonth/
-          if spec_type == :from
-            (today - 2.month).beginning_of_bimonth
-          else
-            (today - 2.month).end_of_bimonth
-          end
-        when /^(this_?)?quarter/
-          if spec_type == :from
-            today.beginning_of_quarter
+        when %r{\A(?<yr>\d\d\d\d)[-/](?<mo>\d\d?)[-/](?<hf_mo>(I|II))\z}
+          # Year, month, half-month, designated with uppercase Roman
+          year = Regexp.last_match[:yr].to_i
+          month = Regexp.last_match[:mo].to_i
+          hf_mo = Regexp.last_match[:hf_mo]
+          if hf_mo == "I"
+            spec_type == :from ? ::Date.new(year, month, 1) : ::Date.new(year, month, 15)
           else
-            today.end_of_quarter
+            # hf_mo == "II"
+            spec_type == :from ? ::Date.new(year, month, 16) : ::Date.new(year, month, 16).end_of_month
           end
-        when /^last_?quarter/
-          if spec_type == :from
-            (today - 3.months).beginning_of_quarter
+        when %r{\A((?<yr>\d\d\d\d)[-/])?((?<mo>\d\d?)[-/])?(?<wk>(i|ii|iii|iv|v|vi))\z}
+          # Year, month, week-of-month, partial-or-whole, designated with lowercase Roman
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
+          month = Regexp.last_match[:mo]&.to_i || ::Date.today.month
+          wk = ['i', 'ii', 'iii', 'iv', 'v', 'vi'].index(Regexp.last_match[:wk]) + 1
+          result =
+            if spec_type == :from
+              ::Date.new(year, month, 1).beginning_of_week + (wk - 1).weeks
+            else
+              ::Date.new(year, month, 1).end_of_week + (wk - 1).weeks
+            end
+          # If beginning of week of the 1st is in prior month, return the 1st
+          result = [result, ::Date.new(year, month, 1)].max
+          # If the whole week of the result is in the next month, there was no such week
+          if result.beginning_of_week.month > month
+            msg = sprintf("no week number #{wk} in %04d-%02d", year, month)
+            raise ArgumentError, msg
           else
-            (today - 3.months).end_of_quarter
+            # But if part of the result week is in this month, return end of month
+            [result, ::Date.new(year, month, 1).end_of_month].min
           end
-        when /^(this_?)?half/
-          if spec_type == :from
-            today.beginning_of_half
-          else
-            today.end_of_half
+        when %r{\A((?<yr>\d\d\d\d)[-/])?((?<mo>\d\d?)[-/])?((?<ndow>\d+)(?<dow>Su|Mo|Tu|We|Th|Fr|Sa))\z}
+          # Year, month, week-of-month, partial-or-whole, designated with lowercase Roman
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
+          month = Regexp.last_match[:mo]&.to_i || ::Date.today.month
+          ndow = Regexp.last_match[:ndow].to_i
+          dow = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'].index(Regexp.last_match[:dow]) ||
+                ['su', 'mo', 'tu', 'we', 'th', 'fr', 'sa', 'su'].index(Regexp.last_match[:dow])
+          unless (1..12).cover?(month)
+            raise ArgumentError, "invalid month number (1-12): '#{month}' in '#{spec}'"
           end
-        when /^last_?half/
-          if spec_type == :from
-            (today - 6.months).beginning_of_half
-          else
-            (today - 6.months).end_of_half
+          unless (1..5).cover?(ndow)
+            raise ArgumentError, "invalid ordinal day number (1-5): '#{ndow}' in '#{spec}'"
           end
-        when /^(this_?)?year/
-          if spec_type == :from
-            today.beginning_of_year
-          else
-            today.end_of_year
+
+          ::Date.nth_wday_in_year_month(ndow, dow, year, month)
+        when %r{\A(?<yr>\d\d\d\d[-/])?E(?<off>[+-]\d+)?\z}i
+          # Easter for the given year, current year (if no year component),
+          # optionally plus or minus a day offset
+          year = Regexp.last_match[:yr]&.to_i || ::Date.today.year
+          offset = Regexp.last_match[:off]&.to_i || 0
+          ::Date.easter(year) + offset
+        when %r{\A(?<rel>(to[_-]?|this[_-]?)|(last[_-]?|yester[_-]?|next[_-]?))
+                  (?<chunk>morrow|day|week|biweek|semimonth|bimonth|month|quarter|half|year)\z}xi
+          rel = Regexp.last_match[:rel]
+          chunk = Regexp.last_match[:chunk].to_sym
+          if chunk.match?(/morrow/i)
+            chunk = :day
+            rel = 'next'
           end
-        when /^last_?year/
+          start =
+            if rel.match?(/this|to/i)
+              ::Date.today
+            elsif rel.match?(/next/i)
+              ::Date.today.add_chunk(chunk, 1)
+            else
+              # rel.match?(/last|yester/i)
+              ::Date.today.add_chunk(chunk, -1)
+            end
           if spec_type == :from
-            (today - 1.year).beginning_of_year
+            start.beginning_of_chunk(chunk)
           else
-            (today - 1.year).end_of_year
+            start.end_of_chunk(chunk)
           end
-        when /^forever/
+        when /^forever/i
           if spec_type == :from
             ::Date::BOT
           else
             ::Date::EOT
           end
-        when /^never/
+        when /^never/i
           nil
         else
           raise ArgumentError, "bad date spec: '#{spec}''"
@@ -1713,8 +1666,21 @@ module FatCore
 
       # 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].freeze
+      COMMON_YEAR_DAYS_IN_MONTH = [
+        31,
+        31,
+        28,
+        31,
+        30,
+        31,
+        30,
+        31,
+        31,
+        30,
+        31,
+        30,
+        31
+      ].freeze
       def days_in_month(year, month)
         raise ArgumentError, 'illegal month number' if month < 1 || month > 12
 
@@ -1758,8 +1724,6 @@ module FatCore
           11
         when /\Adec/i
           12
-        else
-          nil
         end
       end
 
@@ -1767,7 +1731,7 @@ module FatCore
       # last day of month.
       #
       # @param nth [Integer] the ordinal number for the weekday
-      # @param wday [Integer] the weekday of interest with Monday 0 to Sunday 6
+      # @param wday [Integer] the weekday of interest with Sunday 0 to Saturday 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(nth, wday, year, month)
@@ -1778,32 +1742,44 @@ module FatCore
         raise ArgumentError, 'illegal month number' if month < 1 || month > 12
 
         nth = nth.to_i
-        if nth.positive?
-          # Set d to the 1st wday in month
-          d = ::Date.new(year, month, 1)
-          d += 1 while d.wday != wday
-          # Set d to the nth wday in month
-          nd = 1
-          while nd != nth
-            d += 7
-            nd += 1
-          end
-          d
-        elsif nth.negative?
-          nth = -nth
-          # Set d to the last wday in month
-          d = ::Date.new(year, month, 1).end_of_month
-          d -= 1 while d.wday != wday
-          # Set d to the nth wday in month
-          nd = 1
-          while nd != nth
-            d -= 7
-            nd += 1
+        if nth.abs > 5
+          raise ArgumentError, "#{nth.abs} out of range: can be no more than 5 of any day of the week in any month"
+        end
+
+        result =
+          if nth.positive?
+            # Set d to the 1st wday in month
+            d = ::Date.new(year, month, 1)
+            d += 1 while d.wday != wday
+            # Set d to the nth wday in month
+            nd = 1
+            while nd != nth
+              d += 7
+              nd += 1
+            end
+            d
+          elsif nth.negative?
+            nth = -nth
+            # Set d to the last wday in month
+            d = ::Date.new(year, month, 1).end_of_month
+            d -= 1 while d.wday != wday
+            # Set d to the nth wday in month
+            nd = 1
+            while nd != nth
+              d -= 7
+              nd += 1
+            end
+            d
+          else
+            raise ArgumentError, 'Argument nth cannot be zero'
           end
-          d
-        else
-          raise ArgumentError, 'Argument nth cannot be zero'
+
+        dow = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][wday]
+        if result.month != month
+          raise ArgumentError, "There is no #{nth}th #{dow} in #{year}-#{month}"
         end
+
+        result
       end
 
       # Return the date of Easter for the Western Church in the given year.
@@ -1826,23 +1802,33 @@ module FatCore
       end
 
       # Ensure that date is of class Date based either on a string or Date
-      # object.
+      # object or an object that responds to #to_date or #to_datetime.  If the
+      # given object is a String, use Date.parse to try to convert it.
+      #
+      # If given a DateTime, it returns the unrounded DateTime; if given a
+      # Time, it converts it to a DateTime.
       #
       # @param dat [String, Date, Time] the object to be converted to Date
       # @return [Date, DateTime]
       def ensure_date(dat)
-        case dat
-        when String
-          ::Date.parse(dat)
-        when Date, DateTime
+        if dat.is_a?(Date) || dat.is_a?(DateTime)
           dat
-        when Time
+        elsif dat.is_a?(Time)
+          dat.to_datetime
+        elsif dat.respond_to?(:to_datetime)
+          dat.to_datetime
+        elsif dat.respond_to?(:to_date)
           dat.to_date
+        elsif dat.is_a?(String)
+          begin
+            ::Date.parse(dat)
+          rescue ::Date::Error
+            raise ArgumentError, "cannot convert string '#{dat}' to a Date or DateTime"
+          end
         else
-          raise ArgumentError, 'requires String, Date, DateTime, or Time'
+          raise ArgumentError, "cannot convert class '#{dat.class}' to a Date or DateTime"
         end
       end
-      alias ensure ensure_date
     end
 
     def self.included(base)
@@ -1853,6 +1839,9 @@ end
 
 class Date
   include FatCore::Date
+  def self.ensure(dat)
+    ensure_date(dat)
+  end
   # @!parse include FatCore::Date
   # @!parse extend FatCore::Date::ClassMethods
 end