fat_core 4.7.0 → 4.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 881fe55c54af6a96acb9ff0875df33063f4598d800785e5c46a3e2f4cd317cff
-  data.tar.gz: 43bac870c480a6770a39640a61c51f236f891c648a109d4b85d70b1188150cff
+  metadata.gz: 66c2dafd995954b7775a200600f938570b7bc5ad0fd5e240fc8fabb1496b69ba
+  data.tar.gz: a3b3ff6b1dfd0a81afd0ed89b24501e7ade68e9b14e40e8a3da54a59e79f39a2
 SHA512:
-  metadata.gz: 45fc3d2e6e09e59ff14cc4acaa4d2a3794f990a55422b8d2b68186262b2971d566a1651075363600ac9defb03705ddff971bf0b1eb09bf1ab7cb030ab6250910
-  data.tar.gz: 95bc26f296c51bfcf25b15ab2e4c70f0e1ef28d053d36ee8f9917b6008e09ddbcd469dc2ab0e33e5da15809fb9ab8d749ba8e2250515e6515ecefea56e125a5f
+  metadata.gz: f5ada6fefbf2b7cd2a5adbc7f62bc207ad7b8efb55e52874ec0b6e0a8e46a7bd5bc4d5e35f135fe20ea8a6b619f28e14adecf38ea5a2b01b92dfc5aaaf9b5f31
+  data.tar.gz: 621a7ace7268390f3dd900bc0dc7ac38c2a33381cb54bda460a4f8b0f7d8b273b907007299db2c893518c99f846325312095dd7a24b63783da800909487ade51

data/README.org

@@ -0,0 +1,377 @@
+[[https://travis-ci.org/ddoherty03/fat_core.svg?branch=master]]
+
+* FatCore
+
+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.
+
+** Installation
+
+Add this line to your application's Gemfile:
+
+#+begin_SRC ruby
+  gem 'fat_core', :git => 'https://github.com/ddoherty03/fat_core.git'
+#+end_SRC
+
+And then execute:
+
+#+begin_src shell
+  $ bundle
+#+end_src
+
+Or install it yourself as:
+
+#+begin_src shell
+  $ gem install fat_core
+#+end_src
+
+** Usage
+
+You can extend classes individually by requiring the corresponding file:
+
+#+begin_SRC ruby
+  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'
+#+end_SRC
+
+
+Or, you can require them all:
+
+#+begin_SRC ruby
+  require 'fat_core/all'
+#+end_SRC
+
+Many of these have little that is of general interest, but there are a few
+goodies.
+
+*** Date
+
+**** Constants
+
+~FatCore~ adds two constants to the ~Date~ class, Date::BOT and Date::EOT.
+These represent the earliest and latest dates of practical commercial
+interest.  The exact values are rather arbitrary, but they prove useful in
+date ranges, for example.  They are defined as:
+
+- ~Date::BOT~ :: January 1, 1900
+- ~Date::EOT~ :: December 31, 3000
+- ~Date::FEDERAL_DECREED_HOLIDAYS~ :: an Array of dates declared as non-work
+  days for federal employees by presidential proclamation
+- ~Date::PRESIDENTIAL_FUNERALS~ :: an Array of dates of presidential funerals,
+  which are observed with a closing of most federal agencies
+
+
+
+**** Formatting
+
+~FatCore~ provides some concise methods for printing string versions of dates
+that are often useful:
+
+#+begin_SRC ruby :results output :wrap example  :exports both
+  require 'fat_core/date'
+  d = Date.parse('1957-09-22')
+  puts "ISO: #{d.iso}"
+  puts "All Numbers: #{d.num}"
+  puts "Emacs Org Mode Inactive: #{d.org}"
+  puts "Emacs Org Mode Active: #{d.org(true)}"
+  puts "LaTeX: #{d.tex_quote}"
+  puts "English: #{d.eng}"
+  puts "American: #{d.american}"
+#+end_SRC
+
+#+RESULTS:
+#+begin_example
+ISO: 1957-09-22
+All Numbers: 19570922
+Emacs Org Mode Inactive: [1957-09-22 Sun]
+Emacs Org Mode Active: <1957-09-22 Sun>
+LaTeX: 1957--09--22
+English: September 22, 1957
+American: 9/22/1957
+#+end_example
+
+Most of these are self-explanatory, but a couple are not.  The ~#org~ method
+formats a date as an Emacs org-mode timestamp, by default an inactive
+timestamp that does not show up in the org agenda, but can be made active with
+the optional parameter set to a truthy value.  See
+[[https://orgmode.org/manual/Timestamps.html#Timestamps]].
+
+The ~#tex_quote~ method formats the date in iso form but using TeX's
+convention of using en-dashes to separate the components.
+
+**** Chunks
+
+Many of the methods provided by ~FatCore~ deal with various calendar periods
+that are less common than those provided by the Ruby Standard Library or gems
+such as ~active_suupor~.  This documentation refers to these calendar periods
+as "chunks", and they are the following:
+
+- year,
+- half,
+- quarter,
+- bimonth,
+- month,
+- semimonth,
+- biweek,
+- week, and
+- day
+
+~FatCore~ provides methods that query whether the date falls on the beginning
+or end of each of these chunks:
+
+#+begin_SRC ruby :wrap example :exports both
+  require 'fat_core/date'
+
+  tab = []
+  d = Date.parse('2017-06-30')
+  %i[beginning end].each do |side|
+    %i(year half quarter bimonth month semimonth biweek week ).each do |chunk|
+      meth = "#{side}_of_#{chunk}?".to_sym
+      tab << [d.iso, meth.to_s, "#{d.send(meth)}"]
+    end
+  end
+  tab
+#+end_SRC
+
+#+RESULTS:
+#+begin_example
+| 2017-06-30 | beginning_of_year?      | false |
+| 2017-06-30 | beginning_of_half?      | false |
+| 2017-06-30 | beginning_of_quarter?   | false |
+| 2017-06-30 | beginning_of_bimonth?   | false |
+| 2017-06-30 | beginning_of_month?     | false |
+| 2017-06-30 | beginning_of_semimonth? | false |
+| 2017-06-30 | beginning_of_biweek?    | false |
+| 2017-06-30 | beginning_of_week?      | false |
+| 2017-06-30 | end_of_year?            | false |
+| 2017-06-30 | end_of_half?            | true  |
+| 2017-06-30 | end_of_quarter?         | true  |
+| 2017-06-30 | end_of_bimonth?         | true  |
+| 2017-06-30 | end_of_month?           | true  |
+| 2017-06-30 | end_of_semimonth?       | true  |
+| 2017-06-30 | end_of_biweek?          | false |
+| 2017-06-30 | end_of_week?            | false |
+#+end_example
+
+It also provides corresponding methods that return the date at the beginning
+or end of the calendar chunk, starting at the given date:
+
+#+begin_SRC ruby :wrap example :exports both
+  require 'fat_core/date'
+
+  tab = []
+  d = Date.parse('2017-04-21')
+  %i[beginning end].each do |side|
+    %i(year half quarter bimonth month semimonth biweek week ).each do |chunk|
+      meth = "#{side}_of_#{chunk}".to_sym
+      tab << [d.iso, "d.#{meth}", "#{d.send(meth)}"]
+    end
+  end
+  tab
+#+end_SRC
+
+#+RESULTS:
+#+begin_example
+| 2017-04-21 | d.beginning_of_year      | 2017-01-01 |
+| 2017-04-21 | d.beginning_of_half      | 2017-01-01 |
+| 2017-04-21 | d.beginning_of_quarter   | 2017-04-01 |
+| 2017-04-21 | d.beginning_of_bimonth   | 2017-03-01 |
+| 2017-04-21 | d.beginning_of_month     | 2017-04-01 |
+| 2017-04-21 | d.beginning_of_semimonth | 2017-04-16 |
+| 2017-04-21 | d.beginning_of_biweek    | 2017-04-10 |
+| 2017-04-21 | d.beginning_of_week      | 2017-04-17 |
+| 2017-04-21 | d.end_of_year            | 2017-12-31 |
+| 2017-04-21 | d.end_of_half            | 2017-06-30 |
+| 2017-04-21 | d.end_of_quarter         | 2017-06-30 |
+| 2017-04-21 | d.end_of_bimonth         | 2017-04-30 |
+| 2017-04-21 | d.end_of_month           | 2017-04-30 |
+| 2017-04-21 | d.end_of_semimonth       | 2017-04-30 |
+| 2017-04-21 | d.end_of_biweek          | 2017-04-23 |
+| 2017-04-21 | d.end_of_week            | 2017-04-23 |
+#+end_example
+
+You can query which numerical half, quarter, etc. that a given date falls in:
+
+#+begin_SRC ruby :exports both :wrap example
+  require 'fat_core/date'
+
+  tab = []
+  %i(year half quarter bimonth month semimonth biweek week ).each do |chunk|
+    d = Date.parse('2017-04-21') + rand(100)
+    meth = "#{chunk}".to_sym
+    tab << [d.iso, "d.#{meth}", "in #{chunk} number #{d.send(meth)}"]
+  end
+  tab
+#+end_SRC
+
+#+RESULTS:
+#+begin_example
+| 2017-07-05 | d.year      | in year number 2017   |
+| 2017-06-03 | d.half      | in half number 1      |
+| 2017-05-30 | d.quarter   | in quarter number 2   |
+| 2017-07-08 | d.bimonth   | in bimonth number 4   |
+| 2017-06-28 | d.month     | in month number 6     |
+| 2017-05-14 | d.semimonth | in semimonth number 9 |
+| 2017-07-25 | d.biweek    | in biweek number 15   |
+| 2017-06-19 | d.week      | in week number 25     |
+#+end_example
+
+**** Parsing
+
+~FatCore~ also adds some convenience methods for parsing strings as ~Date~
+objects.
+
+***** American Dates
+
+Americans often write dates in the form M/d/Y, and the normal parse method
+will parse such a string as d/M/Y, often resulting in invalid date errors.
+~FatCore~ adds the specialty parsing method, ~Date.parse_american~ to handle
+such strings.
+
+#+begin_SRC ruby :results output :exports both :wrap example
+  require 'fat_core/date'
+
+  begin
+    ss = '9/22/1957'
+    Date.parse(ss)
+  rescue Date::Error => ex
+    puts "Date.parse('#{ss}') raises #{ex.class} (#{ex}), but"
+    puts "Date.parse_american('#{ss}') => #{Date.parse_american(ss)}"
+  end
+#+end_SRC
+
+#+RESULTS:
+#+begin_example
+Date.parse('9/22/1957') raises Date::Error (invalid date), but
+Date.parse_american('9/22/1957') => 1957-09-22
+#+end_example
+
+***** Date Specs
+
+
+
+**** Holidays and Workdays
+
+- weekend?
+- weekday?
+
+**** Weekdays in Month
+
+**** Easter
+
+
+The ~Date~ class extension 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:
+
+#+begin_SRC ruby
+  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
+#+end_SRC
+
+Likewise, days on which the NYSE is closed can be gotten with:
+
+#+begin_SRC ruby
+  Date.parse('2014-04-18').nyse_holiday? => true # It's Good Friday
+#+end_SRC
+
+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:
+
+#+begin_SRC ruby
+  require 'fat_core/range'
+  (0..12).gaps([(0..2), (5..7), (10..12)])  => [(3..4), (8..9)]
+#+end_SRC
+
+**
+* 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~.
+
+*** 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.
+
+*** 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.
+
+*** 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~).
+
+** Contributing
+
+1. Fork it ([[http://github.com/ddoherty03/fat_core/fork]]  )
+2. Create your feature branch (~git checkout -b my-new-feature~)
+3. Commit your changes (~git commit -am 'Add some feature'~)
+4. Push to the branch (~git push origin my-new-feature~)
+5. Create new Pull Request

data/fat_core.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Daniel E. Doherty']
   spec.email         = ['ded@ddoherty.net']
   spec.summary       = 'fat_core provides some useful core extensions'
-  spec.description   = 'Write a longer description. Optional.'
-  spec.homepage      = ''
+  spec.description   = 'Useful extensions to Date, String, Range and other classes'
+  spec.homepage      = 'https://github.com/ddoherty03/fat_core.git'
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 2.2.2'
   spec.metadata['yard.run'] = 'yri' # use "yard" to build full HTML docs.
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'byebug'

data/lib/fat_core/bigdecimal.rb

@@ -1,6 +1,7 @@
 require 'bigdecimal'
 
 module FatCore
+  # Extensions to BigDecimal class
   module BigDecimal
     # Provide a human-readable display for BigDecimal. e.g., while debugging.
     # The inspect method in BigDecimal is unreadable, as it exposes the
@@ -13,6 +14,7 @@ module FatCore
   end
 end
 
+# Override the core inspect method.
 class BigDecimal
   prepend(FatCore::BigDecimal)
   # @!parse include FatCore::BigDecimal

data/lib/fat_core/date.rb

@@ -84,8 +84,12 @@ module FatCore
     # 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]')
+    def org(active = false)
+      if active
+        strftime('<%Y-%m-%d %a>')
+      else
+        strftime('[%Y-%m-%d %a]')
+      end
     end
 
     # :category: Formatting
@@ -108,20 +112,6 @@ module FatCore
     # :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
-
     # :category: Queries
 
     # Self's calendar "half" by analogy to calendar quarters: 1 or 2, depending
@@ -155,6 +145,50 @@ module FatCore
       end
     end
 
+    # Self's calendar bimonth: 1, 2, 3, 4, 5, or 6 depending on which calendar
+    # bimonth the date falls in.
+    # @return [1, 2, 3, 4, 5, 6]
+    def bimonth
+      case month
+      when (1..2)
+        1
+      when (3..4)
+        2
+      when (5..6)
+        3
+      when (7..8)
+        4
+      when (9..10)
+        5
+      when (11..12)
+        6
+      end
+    end
+
+    # Self's calendar semimonth: 1, through 24 depending on which calendar
+    # semimonth the date falls in.
+    # @return [Integer]
+    def semimonth
+      (month - 1) * 2 + (day <= 15 ? 1 : 2)
+    end
+
+    # Self's calendar biweek: 1, through 24 depending on which calendar
+    # semimonth the date falls in.
+    # @return [Integer]
+    def biweek
+      if cweek.odd?
+        (cweek + 1) / 2
+      else
+        cweek / 2
+      end
+    end
+
+    # Self's calendar week: just calls cweek.
+    # @return [Integer]
+    def week
+      cweek
+    end
+
     # :category: Queries
 
     # Return whether the date falls on the first day of a year.
@@ -315,13 +349,13 @@ module FatCore
     # 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
+    # @param from_date [::Date] the middle of the six-month range
     # @return [Boolean]
-    def within_6mos_of?(d)
+    def within_6mos_of?(from_date)
       # ::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)
+      (start_date..end_date).cover?(from_date)
     end
 
     # Return whether this date is Easter Sunday for the year in which it falls
@@ -337,15 +371,15 @@ module FatCore
     # 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
+    # @param nth [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)
+    def nth_wday_in_month?(nth, 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)
+      # If nth is negative, count from last day of month
+      self == ::Date.nth_wday_in_year_month(nth, wday, year, month)
     end
 
     # :category: Relative ::Dates
@@ -478,61 +512,64 @@ module FatCore
     # 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
+    # @param num [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)
+    def next_half(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      next_month(num * 6)
     end
 
     # 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
+    # @param num [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)
+    def prior_half(num = 1)
+      next_half(-num)
     end
 
     # 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
+    # @param num [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)
+    def next_quarter(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      next_month(num * 3)
     end
 
     # 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
+    # @param num [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)
+    def prior_quarter(num = 1)
+      next_quarter(-num)
     end
 
     # 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
+    # @param num [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)
+    def next_bimonth(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      next_month(num * 2)
     end
 
     # 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
+    # @param num [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)
+    def prior_bimonth(num = 1)
+      next_bimonth(-num)
     end
 
     # Return the date that is +n+ semimonths after this date. Each semimonth begins
@@ -542,15 +579,16 @@ module FatCore
     # 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
+    # @param num [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)
+    def next_semimonth(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      factor = num.negative? ? -1 : 1
+      num = num.abs
+      if num.even?
+        next_month(num / 2)
       else
         # Advance or retreat one semimonth
         next_sm =
@@ -577,23 +615,21 @@ module FatCore
               [prior_month.beginning_of_month + 16.days + (day - 1).days,
                prior_month.end_of_month].min
             end
-          else
+          elsif factor.positive?
             # 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
+            next_month.beginning_of_month + [(day - 16), 15].min
+          else
+            beginning_of_month + [(day - 16), 15].min
           end
-        n -= 1
+        num -= 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)
+        if num >= 2
+          next_sm.next_month(factor * num / 2)
         else
           next_sm
         end
@@ -608,30 +644,31 @@ module FatCore
     # 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
+    # @param num [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)
+    def prior_semimonth(num = 1)
+      next_semimonth(-num)
     end
 
     # 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
+    # @param num [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)
+    def next_biweek(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      self + (14 * num)
     end
 
     # 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
+    # @param num [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)
+    def prior_biweek(num = 1)
+      next_biweek(-num)
     end
 
     # Return the date that is +n+ weeks after this date where each week is 7 days.
@@ -639,21 +676,22 @@ module FatCore
     # 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
+    # @param num [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)
+    def next_week(num = 1)
+      num = num.floor
+      return self if num.zero?
+
+      self + (7 * num)
     end
 
     # Return the date that is +n+ weeks before this date where each week is 7
     # days.
     #
-    # @param n [Integer] number of weeks to retreat
+    # @param num [Integer] number of weeks to retreat
     # @return [::Date] new date n weeks from this date
-    def prior_week(n)
-      next_week(-n)
+    def prior_week(num)
+      next_week(-num)
     end
 
     # NOTE: #next_day is defined in active_support.
@@ -661,10 +699,10 @@ module FatCore
     # Return the date that is +n+ weeks before this date where each week is 7
     # days.
     #
-    # @param n [Integer] number of days to retreat
+    # @param num [Integer] number of days to retreat
     # @return [::Date] new date n days before this date
-    def prior_day(n)
-      next_day(-n)
+    def prior_day(num)
+      next_day(-num)
     end
 
     # :category: Relative ::Dates
@@ -673,28 +711,28 @@ module FatCore
     #
     # @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
+    # @param num [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)
+    def add_chunk(chunk, num = 1)
       case chunk
       when :year
-        next_year(n)
+        next_year(num)
       when :half
-        next_month(6)
+        next_month(6 * num)
       when :quarter
-        next_month(3)
+        next_month(3 * num)
       when :bimonth
-        next_month(2)
+        next_month(2 * num)
       when :month
-        next_month(n)
+        next_month(num)
       when :semimonth
-        next_semimonth(n)
+        next_semimonth(num)
       when :biweek
-        next_biweek(n)
+        next_biweek(num)
       when :week
-        next_week(n)
+        next_week(num)
       when :day
-        next_day(n)
+        next_day(num)
       else
         raise ArgumentError, "add_chunk unknown chunk: '#{chunk}'"
       end
@@ -764,6 +802,22 @@ module FatCore
       end
     end
 
+    # @group Holidays and Workdays
+
+    # 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
+
     # Return the date for Easter in the Western Church for the year in which this
     # date falls.
     #
@@ -773,8 +827,6 @@ module FatCore
       ::Date.easter(year)
     end
 
-    # @group Federal Holidays and Workdays
-
     # Holidays decreed by Presidential proclamation
     FED_DECREED_HOLIDAYS =
       [
@@ -782,7 +834,8 @@ module FatCore
         # http://www.whitehouse.gov/the-press-office/2012/12/21
         ::Date.parse('2012-12-24'),
         # And Trump
-        ::Date.parse('2018-12-24')
+        ::Date.parse('2018-12-24'),
+        ::Date.parse('2019-12-24')
       ].freeze
 
     # Presidential funeral since JFK
@@ -803,7 +856,7 @@ module FatCore
       ::Date.parse('2007-01-02'),
       # GHWBFuneral
       ::Date.parse('2018-12-05')
-    ]
+    ].freeze
 
     # Return whether this date is a United States federal holiday.
     #
@@ -865,16 +918,17 @@ module FatCore
     # 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
+    # @param num [Integer] number of federal workdays to add to this date
     # @return [::Date]
-    def add_fed_workdays(n)
+    def add_fed_workdays(num)
       d = dup
-      return d if n.zero?
-      incr = n.negative? ? -1 : 1
-      n = n.abs
-      while n.positive?
+      return d if num.zero?
+
+      incr = num.negative? ? -1 : 1
+      num = num.abs
+      while num.positive?
         d += incr
-        n -= 1 if d.fed_workday?
+        num -= 1 if d.fed_workday?
       end
       d
     end
@@ -975,8 +1029,10 @@ module FatCore
     # 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.
+    # * 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:
     #
@@ -1042,16 +1098,17 @@ module FatCore
     # Return the date that is n NYSE trading days after or before (if n < 0) this
     # date.
     #
-    # @param n [Integer] number of NYSE trading days to add to this date
+    # @param num [Integer] number of NYSE trading days to add to this date
     # @return [::Date]
-    def add_nyse_workdays(n)
+    def add_nyse_workdays(num)
       d = dup
-      return d if n.zero?
-      incr = n.negative? ? -1 : 1
-      n = n.abs
-      while n.positive?
+      return d if num.zero?
+
+      incr = num.negative? ? -1 : 1
+      num = num.abs
+      while num.positive?
         d += incr
-        n -= 1 if d.nyse_workday?
+        num -= 1 if d.nyse_workday?
       end
       d
     end
@@ -1095,8 +1152,6 @@ module FatCore
       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.
     #
@@ -1209,7 +1264,9 @@ module FatCore
     # @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
@@ -1281,9 +1338,11 @@ module FatCore
       # @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}
+        re = %r{\A\s*(\d\d?)\s*[-/]\s*(\d\d?)\s*[-/]\s*((\d\d)?\d\d)\s*\z}
+        unless str.to_s =~ re
           raise ArgumentError, "date string must be of form 'MM?/DD?/YY(YY)?'"
         end
+
         year = $3.to_i
         month = $1.to_i
         day = $2.to_i
@@ -1345,13 +1404,13 @@ module FatCore
       #   designated by spec
       def parse_spec(spec, spec_type = :from)
         spec = spec.to_s.strip
-        unless [:from, :to].include?(spec_type)
+        unless %i[from to].include?(spec_type)
           raise ArgumentError, "invalid date spec type: '#{spec_type}'"
         end
 
         today = ::Date.current
         case spec.clean
-        when /\A(\d\d\d\d)[-\/](\d\d?)[-\/](\d\d?)\z/
+        when %r{\A(\d\d\d\d)[-/](\d\d?)[-/](\d\d?)\z}
           # A specified date
           ::Date.new($1.to_i, $2.to_i, $3.to_i)
         when /\AW(\d\d?)\z/, /\A(\d\d?)W\z/
@@ -1359,29 +1418,32 @@ module FatCore
           if week_num < 1 || week_num > 53
             raise ArgumentError, "invalid week number (1-53): '#{spec}'"
           end
+
           if spec_type == :from
             ::Date.commercial(today.year, week_num).beginning_of_week
           else
             ::Date.commercial(today.year, week_num).end_of_week
           end
-        when /\A(\d\d\d\d)[-\/]W(\d\d?)\z/, /\A(\d\d\d\d)[-\/](\d\d?)W\z/
+        when %r{\A(\d\d\d\d)[-/]W(\d\d?)\z}, %r{\A(\d\d\d\d)[-/](\d\d?)W\z}
           year = $1.to_i
           week_num = $2.to_i
           if week_num < 1 || week_num > 53
             raise ArgumentError, "invalid week number (1-53): '#{spec}'"
           end
+
           if spec_type == :from
             ::Date.commercial(year, week_num).beginning_of_week
           else
             ::Date.commercial(year, week_num).end_of_week
           end
-        when /^(\d\d\d\d)[-\/](\d)[Qq]$/, /^(\d\d\d\d)[-\/][Qq](\d)$/
+        when %r{^(\d\d\d\d)[-/](\d)[Qq]$}, %r{^(\d\d\d\d)[-/][Qq](\d)$}
           # Year-Quarter
           year = $1.to_i
           quarter = $2.to_i
           unless [1, 2, 3, 4].include?(quarter)
             raise ArgumentError, "invalid quarter number (1-4): '#{spec}'"
           end
+
           month = quarter * 3
           if spec_type == :from
             ::Date.new(year, month, 1).beginning_of_quarter
@@ -1395,19 +1457,20 @@ module FatCore
           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 /^(\d\d\d\d)[-\/](\d)[Hh]$/, /^(\d\d\d\d)[-\/][Hh](\d)$/
+        when %r{^(\d\d\d\d)[-/](\d)[Hh]$}, %r{^(\d\d\d\d)[-/][Hh](\d)$}
           # Year-Half
           year = $1.to_i
           half = $2.to_i
-          unless [1, 2].include?(half)
-            raise ArgumentError, "invalid half number: '#{spec}'"
-          end
+          msg = "invalid half number: '#{spec}'"
+          raise ArgumentError,  msg unless [1, 2].include?(half)
+
           month = half * 6
           if spec_type == :from
             ::Date.new(year, month, 15).beginning_of_half
@@ -1418,34 +1481,36 @@ module FatCore
           # Half only
           this_year = today.year
           half = $1.to_i
-          unless [1, 2].include?(half)
-            raise ArgumentError, "invalid half number: '#{spec}'"
-          end
+          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 /^(\d\d\d\d)[-\/](\d\d?)*$/
+        when %r{^(\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(year, month, 1)
           else
             ::Date.new(year, month, 1).end_of_month
           end
-        when /^(\d\d?)[-\/](\d\d?)*$/
+        when %r{^(\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, month, day)
           else
@@ -1457,6 +1522,7 @@ module FatCore
           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
@@ -1580,11 +1646,12 @@ module FatCore
       # starting with January = 1, etc.
       COMMON_YEAR_DAYS_IN_MONTH = [31, 31, 28, 31, 30, 31, 30, 31, 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]
-        if m == 2
-          ::Date.new(y, m, 1).leap? ? 29 : 28
+      def days_in_month(year, month)
+        raise ArgumentError, 'illegal month number' if month < 1 || month > 12
+
+        days = COMMON_YEAR_DAYS_IN_MONTH[month]
+        if month == 2
+          ::Date.new(year, month, 1).leap? ? 29 : 28
         else
           days
         end
@@ -1593,41 +1660,43 @@ module FatCore
       # 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 nth [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)
+      def nth_wday_in_year_month(nth, wday, year, month)
         wday = wday.to_i
-        raise ArgumentError, 'illegal weekday number' if wday < 0 || wday > 6
+        raise ArgumentError, 'illegal weekday number' if wday.negative? || wday > 6
+
         month = month.to_i
         raise ArgumentError, 'illegal month number' if month < 1 || month > 12
-        n = n.to_i
-        if n.positive?
+
+        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 != n
+          while nd != nth
             d += 7
             nd += 1
           end
           d
-        elsif n.negative?
-          n = -n
+        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 != n
+          while nd != nth
             d -= 7
             nd += 1
           end
           d
         else
-          raise ArgumentError, 'Argument n cannot be zero'
+          raise ArgumentError, 'Argument nth cannot be zero'
         end
       end
 
@@ -1669,7 +1738,6 @@ module FatCore
       end
     end
 
-    # @private
     def self.included(base)
       base.extend(ClassMethods)
     end