fat_core 5.6.1 → 7.0.1

data/README.org

@@ -1,17 +1,108 @@
-[[https://travis-ci.org/ddoherty03/fat_core.svg?branch=master]]
+#+TITLE: FatCore Guide
+#+OPTIONS: toc:5
+#+PROPERTY: header-args:ruby :colnames no :hlines yes :exports both :wrap example :ruby ruby
+#+PROPERTY: header-args:sh :exports code
+
+[[https://github.com/ddoherty03/fat_core/actions/workflows/ruby.yml][https://github.com/ddoherty03/fat_core/actions/workflows/ruby.yml/badge.svg?branch=master]]
+
+* README Setup Do First for Code Blocks                            :noexport:
+Run this block before all others to ensure that we are reading the libraries
+from the source directory.
+
+#+begin_src ruby :results output
+  puts "Current directory: #{Dir.pwd}"
+  puts "Ruby LOADPATH:"
+  $:.unshift("./lib") unless $:[0] == './lib'
+  $:[0..10].each { |d| puts d }
+  puts "..."
+  require_relative 'lib/fat_core/all'  # => true
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Current directory: /home/ded/src/fat_core
+Ruby LOADPATH:
+./lib
+/home/ded/.rbenv/rbenv.d/exec/gem-rehash
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/site_ruby/3.2.0
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/site_ruby/3.2.0/x86_64-linux
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/site_ruby
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/vendor_ruby/3.2.0
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/vendor_ruby/3.2.0/x86_64-linux
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/vendor_ruby
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/3.2.0
+/home/ded/.rbenv/versions/3.2.2/lib/ruby/3.2.0/x86_64-linux
+...
+#+end_example
+
+
+* Table of Contents                                            :toc:noexport:
+- [[#version][Version]]
+- [[#fatcore][FatCore]]
+- [[#installation][Installation]]
+- [[#usage][Usage]]
+    - [[#array][Array]]
+      - [[#method-comma_joinsep-nil-last_sep-nil-two_sep-nil][Method ~#comma_join(sep: nil, last_sep: nil, two_sep: nil)~]]
+      - [[#method-last_i][Method ~#last_i~]]
+      - [[#method-intersect_with_dups][Method ~#intersect_with_dups~]]
+      - [[#method-diff_with_dups][Method ~diff_with_dups~]]
+    - [[#bigdecimal-inspect][BigDecimal ~#inspect~]]
+    - [[#enumerable][Enumerable]]
+      - [[#method-each_with_flags][Method ~#each_with_flags~]]
+    - [[#hash][Hash]]
+      - [[#method-each_pair_with_flags][Method ~#each_pair_with_flags~]]
+      - [[#method-delete_with_value-and-delete_with_value][Method ~#delete_with_value~ and ~#delete_with_value!~]]
+      - [[#method-keys_with_value][Method ~#keys_with_value~]]
+      - [[#method-remap_keys][Method ~#remap_keys~]]
+      - [[#method-replace_keys][Method ~#replace_keys~]]
+      - [[#alias-merge-to-][Alias ~#merge~ to ~<<~]]
+    - [[#numeric][Numeric]]
+      - [[#method-signum][Method ~#signum~]]
+      - [[#method-commasplaces--nil][Method ~#commas(places = nil)~]]
+      - [[#methods-whole-and-int_if_whole][Methods ~#whole?~ and ~#int_if_whole~]]
+      - [[#method-secs_to_hms][Method ~#secs_to_hms~]]
+    - [[#range][Range]]
+      - [[#methods-contiguous-left_contiguous-right_contiguous][Methods ~#contiguous~, ~#left_contiguous~, ~#right_contiguous~]]
+      - [[#method-joinother][Method ~#join(other)~]]
+      - [[#method-spanned_byothers][Method ~#spanned_by?(others)~]]
+      - [[#methods-gapsothers-overlapsothers][Methods ~#gaps(others)~, ~#overlaps(others)~]]
+    - [[#string][String]]
+      - [[#method-fuzzy_match][Method ~#fuzzy_match~]]
+      - [[#method-matches_with][Method ~#matches_with~]]
+      - [[#method-entitle][Method ~#entitle~]]
+      - [[#method-distance][Method ~#distance~]]
+      - [[#method-commasplaces][Method ~#commas(places)~]]
+      - [[#method-wrapwidth-hang][Method =#wrap(width, hang)=]]
+      - [[#method-as_sym][Method =#as_sym=]]
+    - [[#symbol][Symbol]]
+      - [[#method-as_str][Method =#as_str=]]
+    - [[#tex-quoting][TeX Quoting]]
+- [[#contributing][Contributing]]
+
+* Version
+#+begin_src ruby
+  require_relative './lib/fat_core/version'
+  "Current version is: #{FatCore::VERSION}"
+#+end_src
+
+#+begin_example
+Current version is: 7.0.0
+#+end_example
 
 * 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.
+~fat-core~ is somewhat of a grab bag of core class extensions that I have
+found useful across several projects.  It's higgeldy-piggeldy nature reflects
+the fact that none of them are important enough to deserve a gem of their own,
+but nonetheless need to be collected in one place to reduce redundancy across
+projects and provide a focused place to develop and test them.
 
-** Installation
+* Installation
 
 Add this line to your application's Gemfile:
 
-#+begin_SRC ruby
-  gem 'fat_core', :git => 'https://github.com/ddoherty03/fat_core.git'
+#+begin_src ruby
+  gem 'fat_core'
 #+end_SRC
 
 And then execute:
@@ -26,14 +117,13 @@ Or install it yourself as:
   $ gem install fat_core
 #+end_src
 
-** Usage
+* 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'
@@ -43,7 +133,6 @@ You can extend classes individually by requiring the corresponding file:
   require 'fat_core/symbol'
 #+end_SRC
 
-
 Or, you can require them all:
 
 #+begin_SRC ruby
@@ -53,454 +142,642 @@ Or, you can require them all:
 Many of these have little that is of general interest, but there are a few
 goodies.
 
-*** Date
-**** Constants
-~FatCore~ adds two date 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
-
-**** Ensure
-The ~Date.ensure~ class method tries to convert its argument to a ~Date~
-object by (1) applying the ~#to_date~ method or (2) applying the ~Date.parse~
-method to a String.  This is handy when you want to define a method that takes
-a date argument but want the caller to be able to supply anything that can
-reasonably be converted to a ~Date~:
+*** Array
+**** Method ~#comma_join(sep: nil, last_sep: nil, two_sep: nil)~
+Convert this array into a single string by (1) applying ~#to_s~ to each
+element and (2) joining the elements with the string given by the ~sep:~
+parameter. By default the sep parameter is ', '.
+
+You may use a different separation string in the case when there are only two
+items in the list by supplying a ~two_sep~ parameter.
+
+You may also supply a difference separation string to separate the second-last
+and last items in the array by supplying a ~last_sep:~ parameter.
+
+By default, the sep parameter is the string ', ', the ~two_sep~ is ' and ',
+and the ~last_sep~ is ', and ', all of which makes for a well-punctuated
+English clause.
+
+If ~sep~ is given, the other two parameters are set to its
+value by default.  If ~last_sep~ is given, ~two_sep~ takes its value by
+default.
+
+If the input array is empty, ~#comma_join~ returns an empty string.
 
 #+begin_src ruby
-  $:.unshift("~/src/fat_core/lib")
-  require 'fat_core/date'  # => true
-
-  def tomorow_tomorrow(arg)
-    from = Date.ensure(arg)  # => ArgumentError: cannot convert class 'Array' to a Date or DateTime
-    from + 2.days            # => Mon, 03 Jun 2024, Wed, 16 Oct 2024 05:47:30 -0500, Sun, 03 Mar 2024
-  end                        # => :tomorow_tomorrow
-
-  tomorow_tomorrow('June 1')  # => Mon, 03 Jun 2024
-  tomorow_tomorrow(Time.now)  # => Wed, 16 Oct 2024 05:47:30 -0500
-  # But it's only as good as Date.parse!
-  tomorow_tomorrow('Ides of March') # => Sun, 03 Mar 2024
-
-  tomorow_tomorrow([])
-  # =>
-
-  # ~> ArgumentError
-  # ~> cannot convert class 'Array' to a Date or DateTime
-  # ~>
-  # ~> /home/ded/src/fat_core/lib/fat_core/date.rb:1849:in `ensure_date'
-  # ~> /home/ded/src/fat_core/lib/fat_core/date.rb:1863:in `ensure'
-  # ~> /tmp/seeing_is_believing_temp_dir20241014-1457038-xj4k5x/program.rb:5:in `tomorow_tomorrow'
-  # ~> /tmp/seeing_is_believing_temp_dir20241014-1457038-xj4k5x/program.rb:14:in `<main>'
-#+end_src
-
-**** 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
+  require_relative 'lib/fat_core/array'
+
+  %w{hammers nails glue bolts}.comma_join
+#+end_src
 
 #+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_support~.  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
+hammers, nails, glue, and bolts
+#+end_example
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/array'
+
+  %w{hammers nails}.comma_join
+#+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
+hammers and nails
+#+end_example
+
+And, if you are ideologically opposed to the Oxford comma:
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/array'
+
+  %w{hammers nails glue bolts}.comma_join(last_sep: ' and ')
+#+end_src
+
+#+begin_example
+hammers, nails, glue and bolts
+#+end_example
+
+**** Method ~#last_i~
+Return the index of the last element of the Array.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/array'
+
+  %w{hammers nails glue bolts}.last_i
+#+end_src
+
+#+begin_example
+3
+#+end_example
+
+**** Method ~#intersect_with_dups~
+Return a new Array that is the intersection of this Array with all ~others~,
+but without removing duplicates as the ~Array#&~ method does. All items of
+this Array are included in the result but only if they also appear in all of
+the other Arrays.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/array'
+
+  a = %w{hammers nails glue bolts nails}
+  b = %w{nails fingers knuckles nails}
+  a.intersect_with_dups(b)
+#+end_src
+
+#+begin_example
+| nails | nails |
+#+end_example
+
+**** Method ~diff_with_dups~
+Return an Array that is the difference between this Array and =other=, but
+without removing duplicates as the Array#- method does. All items of this
+Array are included in the result /unless/ they also appear in any of the
+=other= Arrays.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/array'
+
+  a = %w{hammers nails glue bolts hammers nails}
+  b = %w{nails fingers knuckles nails}
+  a.diff_with_dups(b)
+#+end_src
+
+#+begin_example
+| hammers | glue | bolts | hammers |
+#+end_example
+
+*** BigDecimal ~#inspect~
+~FatCore~ provides nothing but a better ~#inspect~ method for the ~BigDecimal~
+class since the default inspect method is not very readable.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/bigdecimal'
+
+  BigDecimal('2.1718281828').inspect
+#+end_src
+
+#+begin_example
+2.1718281828
+#+end_example
+
+Without ~FatCore~, the result is  "0.2718281828e1", forcing you to interpret
+the exponent to understand where the decimal place is.
+
+*** Enumerable
+**** Method ~#each_with_flags~
+~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 and ~false~ otherwise.  This makes it easy to treat
+these two cases specially without testing the index as in ~#each_with_index~.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/enumerable'
+
+  result = []
+  fibs = %w{1, 1, 2, 3, 5, 8, 13, 21}
+  fibs.each_with_flags do |f, first, last|
+    result <<
+      if first
+        ["Start", f]
+      elsif last
+        ["Last", f]
+      else
+        ["Continue", f]
+      end
   end
-  tab
-#+end_SRC
+  result
+#+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)}"]
+| Start    |  1, |
+| Continue |  1, |
+| Continue |  2, |
+| Continue |  3, |
+| Continue |  5, |
+| Continue |  8, |
+| Continue | 13, |
+| Last     |  21 |
+#+end_example
+
+*** Hash
+FatCore::Hash extends the Hash class with some useful methods.
+
+**** Method ~#each_pair_with_flags~
+As with the extension for ~Enumerables~, ~FatCore~ provides a method for
+enumerating the key-value pair of the ~Hash~ with flags that are set ~true~
+for the first and last elements but ~false~ otherwise:
+
+#+begin_src ruby
+  require_relative './lib/fat_core/hash'
+
+  h = {'Chaucer' => 'Cantebury Tales', 'Shakespeare' => 'The Merchant of Venice',
+       'Austen' => 'Pride and Prejudice', 'C. Brontë' => 'Jane Eyre',
+       'E. Brontë' => 'Wuthering Heights' }
+  result = []
+  result << ['Position', 'Author', 'Novel']
+  result << nil
+  h.each_pair_with_flags do |k, v, first, last|
+    pos=
+      if first
+        'Begin'
+      elsif last
+        'End'
+      else
+        'Middle'
+      end
+    result << [pos, k, v]
   end
-  tab
-#+end_SRC
+  result
+#+end_src
+
+#+begin_example
+| Position | Author      | Novel                  |
+|----------+-------------+------------------------|
+| Begin    | Chaucer     | Cantebury Tales        |
+| Middle   | Shakespeare | The Merchant of Venice |
+| Middle   | Austen      | Pride and Prejudice    |
+| Middle   | C. Brontë   | Jane Eyre              |
+| End      | E. Brontë   | Wuthering Heights      |
+#+end_example
+
+**** Method ~#delete_with_value~ and ~#delete_with_value!~
+This method modifies a ~Hash~ by deleting the key-value pairs when the value
+equals the given value or values:
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  h.delete_with_value!(2)
+  puts h
+#+end_src
+
+#+begin_example
+{:a=>1, :c=>3, :e=>1}
+#+end_example
+
+You can supply multiple values for deletion:
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  h.delete_with_value!(1, 3)
+  puts h
+#+end_src
+
+#+begin_example
+{:b=>2, :d=>2}
+#+end_example
+
+The non-bang method returns a clone of the Hash with the given deletions made:
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  h2 = h.delete_with_value(1, 3)
+  puts h
+  puts h2
+#+end_src
+
+#+begin_example
+{:a=>1, :b=>2, :c=>3, :d=>2, :e=>1}
+{:b=>2, :d=>2}
+#+end_example
+
+**** Method ~#keys_with_value~
+Return an ~Array~ of keys of the ~Hash~ with a value ~==~ to the given value
+or values.
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  puts h.keys_with_value(1).inspect
+  puts h.keys_with_value(2, 3).inspect
+#+end_src
+
+#+begin_example
+[:a, :e]
+[:b, :d, :c]
+#+end_example
+
+**** Method ~#remap_keys~
+This method pre-dates the new ~#transform_keys~ method now available for
+~Hash~, but it is kept as an alternative.  It takes a ~Hash~ as an argument
+that maps existing keys to their replacement in the resulting ~Hash~.  The
+original ~Hash~ is not effected.
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  puts h.remap_keys({:a => :A, :b => :B}).inspect
+#+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     |
+{:A=>1, :B=>2, :c=>3, :d=>2, :e=>1}
 #+end_example
 
-**** Parsing
+These days, a more systematic job could be done with ~#transform_keys~:
+#+begin_src ruby :results output
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  puts h.transform_keys { |k| k.to_s.upcase.to_sym }.inspect
+#+end_src
+
+#+begin_example
+{:A=>1, :B=>2, :C=>3, :D=>2, :E=>1}
+#+end_example
 
-~FatCore~ also adds some convenience methods for parsing strings as ~Date~
-objects.
+**** Method ~#replace_keys~
+A wholesale replacement of the existing keys can be done with this method:
 
-***** 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
+  require_relative './lib/fat_core/hash'
 
-#+begin_SRC ruby :results output :exports both :wrap example
-  require 'fat_core/date'
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  puts h
+  puts h.replace_keys([:z, :y, :x, :w, :v]).inspect
+#+end_src
+
+#+begin_example
+{:a=>1, :b=>2, :c=>3, :d=>2, :e=>1}
+{:z=>1, :y=>2, :x=>3, :w=>2, :v=>1}
+#+end_example
+
+**** Alias ~#merge~ to ~<<~
+Finally, ~FatCore~ adds the "shovel" operator as an alias for ~#merge~ to
+provide a pretty way to represent the merger of the right ~Hash~ into the left
+~Hash~:
+
+#+begin_src ruby :results output
+  require_relative './lib/fat_core/hash'
+
+  h = {a: 'A', b: 'B', c: 'C'} << {c: 'CC', d: 'DD'} << {d: 'DDD', e: 'EEE'}
+  puts h
+#+end_src
 
-  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)}"
+#+begin_example
+{:a=>"A", :b=>"B", :c=>"CC", :d=>"DDD", :e=>"EEE"}
+#+end_example
+
+It groups values into pairs and applies the ~#to_h~ method to the right-hand
+argument if it is an ~Enumerable~, so it also works if the right-hand argument
+is an ~Array~ or ~Enumerable~:
+
+#+begin_src ruby :results output
+  require 'fileutils'
+  require_relative './lib/fat_core/hash'
+
+  FileUtils.mkdir_p('./tmp')
+  ff = File.open('./tmp/junk', 'w')
+  ff.write("f\n", "FFFF\n", "g\n", "GGGG\n")
+  ff.close
+  ff = File.open('./tmp/junk', 'r')
+  h = {a: 'A', b: 'B', c: 'C'} <<
+      [:c, 'CC', :d, 'DD'] <<
+      {d: 'DDD', e: 'EEE'} <<
+      ff.readlines.map(&:chomp) <<
+      [[:h, 'HHHHH'], [:j, 'JJJJJ']]
+  # h.transform_keys!(&:to_sym)
+  ff.close
+  FileUtils.rm_rf('./tmp/junk')
+  puts h
+#+end_src
+
+#+begin_example
+{:a=>"A", :b=>"B", :c=>"CC", :d=>"DDD", :e=>"EEE", "f"=>"FFFF", "g"=>"GGGG", :h=>"HHHHH", :j=>"JJJJJ"}
+#+end_example
+
+*** Numeric
+**** Method ~#signum~
+Return ~-1~ for negative numbers, ~0~ for zero, and ~+1~ for positive numbers.
+This is sometimes handy.
+
+**** Method ~#commas(places = nil)~
+To get s ~String~ representation of a ~Numeric~ with grouping commas inserted,
+~FatCore~ provides the ~#commas~ method:
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/numeric'
+  result = []
+  result << ['N', 'Places', 'N.commas(places)']
+  result << nil
+  nums = [3.14159, 2.718281828, 100000, 0.0059, 16236565468798.66877]
+  places = [0, 3, 5]
+  nums.each do |n|
+    places.each do |pl|
+    result << [n, pl, n.commas(pl)]
+    end
   end
-#+end_SRC
+  result
+#+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
-It is often desirable to get the first or last date of a specified time
-period.  For this ~FatCore~ provides the ~parse_spec~ method that takes a
-string and an optional ~spec_type~ parameter of either ~:from~, indicating
-that the first date of the period should be returned or ~:to~, indicating that
-the last date of the period should be returned.
-
-This method supports a rich set of ways to specify periods of time:
-
-- YYYY-MM-DD :: returns a single day as the time period,
-- YYYY-MM :: returns the specified month, beginning or end
-- YYYY :: returns the specified year, beginning or end
-- YYYY-ddd :: returns the ddd'th day of the specified year, beginning or end
-- MM :: returns the specified month of the current year, beginning or end
-- MM-DD :: returns the specified day of the specified month in the current
-  year, beginning or end,
-- YYYY-Wnn or YYYY-nnW :: returns the nn'th commercial week of the given year
-  according to the ISO 8601 standard, in which the week containing the first
-  Thursday of the year counts as the first commercial week, even if that week
-  started in the prior calendar year,
-- Wnn or nnW :: returns the nn'th commercial week of the current year,
-- YYYY-1H or YYYY-2H :: returns the specified half year for the given year,
-- 1H or 2H :: returns the specified half year for the current year,
-- YYYY-1Q, YYYY-2Q, etc  :: returns the calendar quarter for the given year,
-- 1Q, 2Q, etc  :: returns the calendar quarter for the current year,
-- YYYY-MM-I or YYYY-MM-II :: returns the semi-month for the given month and
-  year, where the first semi-month always runs from the 1st to the 15th and
-  the second semi-month always runs from the 16th to the last day of the given
-  month, regardless of the number of days in the month,
-- YYYY-MM-i or YYYY-MM-ii up to YYYY-MM-vi :: returns the given week within
-  the month, including any partial weeks,
-- MM-i or MM-ii up to MM-vi :: returns the given week within the month of the
-  current year, including any partial weeks,
-- i or ii up to vi :: returns the given week within the current month of the current
-  year, including any partial weeks,
-- YYYY-MM-nSu up to YYYY-MM-nSa  :: returns the single date that is the n'th
-  Sunday, Monday, etc., in the given month using the first two letters of the
-  English names for the days of the week,
-- MM-nSu up to MM-nSa  :: returns the single date that is the n'th Sunday,
-  Monday, etc., in the given month of the current year using the first two
-  letters of the English names for the days of the week,
-- nSu up to nSa  :: returns the single date that is the n'th Sunday, Monday,
-  etc., in the current month of the current year using the first two letters
-  of the English names for the days of the week,
-- YYYY-nnn :: is the nnn'th day of the given year, exactly three digits needed,
-- nnn :: is the nnn'th day of the current year, exactly three digits needed,
-- YYYY-E :: returns the single date of Easter in the Western church for the
-  given year,
-- E :: returns the single date of Easter in the Western church for the current
-  year,
-- YYYY-E-n or YYYY-E+n :: returns the single date that falls n days before (-)
-  or after (+) Easter in the Western church for the given year,
-- E-n or E+n :: returns the single date that falls n days before (-) or after
-  (+) Easter in the Western church for the current year,
-- yesterday or yesteryear or lastday or last_year, etc :: the relative
-  prefixes, 'last' or 'yester' prepended to any chunk name returns the period
-  named by the chunk that precedes today's date.
-- today or toyear or this-year or thissemimonth, etc :: the relative prefixes,
-  'to' or 'this' prepended to any chunk name returns the period named by
-  the chunk that contains today's date.
-- nextday or nextyear or next-year or nextsemimonth, etc :: the relative
-  prefixes, 'next' prepended to any chunk name returns the period named by the
-  chunk that follows today's date. As a special case, 'tomorrow' is treated as
-  equivalent to 'nextday'.
-- forever :: returns the period Date::BOT to Date::EOT, which, for financial
-  applications is meant to stand in for eternity.
-- never :: returns nil, representing no date.
-
-Some things to note with respect to ~Date.parse_spec~:
-
-1. The second argument should be either ~:from~ or ~:to~, but it defaults to
-   ~:from~.  If it is ~:from~, ~parse_spec~ returns the first date of the
-   specified period; if it is ~:to~, it returns the last date of the specified
-   period.  When the "period" resolves to a single day, both arguments return
-   the same date, so ~parse_spec('2024-E', :from)~ and ~parse_spec('2024-E',
-   :to)~ both result in March 31, 2024.
-2. Where relevant, ~parse_spec~ accepts letters of either upper or lower case:
-   so 2024-1Q can be written 2024-1q and 'yesteryear' can be written
-   'YeSterYeaR', and likewise for all components of the spec using letters.
-3. Date components can be separated with either a hyphen, as in the examples
-   above, or with a '/' as is common.  Thus, 2024-11-09 can also be
-   2024/11/09, or indeed, 2024/11-09 or 2024-11/09.
-4. The prefixes for relative periods can be separated from the period name by
-   a hyphen, and underscore, or by nothing at all.  Thus, yester-day,
-   yester_day, and yesterday are all acceptable.  Clearly neologisms such as
-   'yestermonth' are quaint, but not harmful.
-5. On the other hand, to get a day-of-year spec right, you must use exactly 3
-   digits: 2024-011 is the 11th day of 2024, but 2024-11 is November of 2024.
-
-**** Holidays and Workdays
-One of the original motivations for this library was to provide an easy way to
-determine whether a given date is a federal holiday in the United States or,
-nearly but not quite the same, a non-trading day on the New York Stock
-Exchange.  To that end, ~FatCore~ provides the following methods:
-
-- Date#weekend? -- is this date on a weekend?
-- Date#weekday? -- is this date on a week day?
-- Date#easter_this_year -- the date of Easter in the Date's year
-
-Methods concerning Federal holidays:
-
-- Date#fed_holiday? -- is this date a Federal holiday?  It knows about
-  obscurities such as holidays decreed by past Presidents, dates of
-  Presidential funerals, and the Federal rule for when holidays fall on a
-  weekend, whether it is moved to the prior Friday or the following Monday.
-- Date#fed_workday? -- is it a date when the Federal government is open?,
-  inverse of Date#fed_holiday?
-- Date#add_fed_workdays(n) -- n Federal workdays following (or preceding if n
-  negative) this date,
-- Date#next_fed_workday -- the next Federal workday following this date,
-- Date#prior_fed_workday -- the previous Federal workday before this date,
-- Date#next_until_fed_workday -- starting with this date, move forward until
-  we hit a Federal workday
-- Date#prior_until_fed_workday -- starting with this date, move back until
-  we hit a Federal workday
-
-And we have similar methods for "holidays" or non-trading days on the NYSE:
-
-- Date#nyse_holiday? -- is this date a NYSE holiday?
-- Date#nyse_workday? -- is it a date when the NYSE is open for trading?,
-  inverse of Date#nyse_holiday?
-- Date#add_nyse_workdays(n) -- n NYSE workdays following (or preceding if n
-  negative) this date,
-- Date#next_nyse_workday -- the next NYSE workday following this date,
-- Date#prior_nyse_workday -- the previous NYSE workday before this date,
-- Date#next_until_nyse_~~workday -- starting with this date, move forward until
-  we hit a NYSE workday
-- Date#prior_until_nyse_workday -- starting with this date, move back until
-  we hit a Federal workday
-
-**** Ordinal Weekdays in Month
-It is often useful to find the 1st, 2nd, etc, Sunday, Monday, etc. in a given
-month.  ~FatCore~ provides the class method ~Date.nth_wday_in_year_month(nth,
-wday, year, month)~ to return such dates.  The first parameter can be
-negative, which will count from the end of the 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:
+|                  N | Places |         N.commas(places) |
+|--------------------+--------+--------------------------|
+|            3.14159 | 0      |                        3 |
+|            3.14159 | 3      |                    3.142 |
+|            3.14159 | 5      |                  3.14159 |
+|        2.718281828 | 0      |                        3 |
+|        2.718281828 | 3      |                    2.718 |
+|        2.718281828 | 5      |                  2.71828 |
+|             100000 | 0      |                  100,000 |
+|             100000 | 3      |              100,000.000 |
+|             100000 | 5      |            100,000.00000 |
+|             0.0059 | 0      |                        0 |
+|             0.0059 | 3      |                    0.006 |
+|             0.0059 | 5      |                  0.00590 |
+| 16236565468798.668 | 0      |       16,236,565,468,799 |
+| 16236565468798.668 | 3      |   16,236,565,468,798.668 |
+| 16236565468798.668 | 5      | 16,236,565,468,798.66800 |
+#+end_example
 
-#+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
+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~).
 
-Likewise, days on which the NYSE is closed can be gotten with:
+**** Methods ~#whole?~ and ~#int_if_whole~
+At times it is useful to know if a Float or BigDecimal can be converted to an
+~Integer~ without losing precision.
 
-#+begin_SRC ruby
-  Date.parse('2014-04-18').nyse_holiday? => true # It's Good Friday
-#+end_SRC
+#+begin_src ruby
+  require_relative 'lib/fat_core/numeric'
+  result = []
+  result << ['N', '#whole?', '#int_if_whole', 'Classes']
+  result << nil
+  nums = [3.14159, 3.000000, 100000, 0.0059, 16236565468798.66877]
+  nums.each do |n|
+    result << [n, n.whole?, n.int_if_whole, "#{n.class} -> #{n.int_if_whole.class}"]
+  end
+  result
+#+end_src
+
+#+begin_example
+|                  N | #whole? |      #int_if_whole | Classes            |
+|--------------------+---------+--------------------+--------------------|
+|            3.14159 | false   |            3.14159 | Float -> Float     |
+|                3.0 | true    |                  3 | Float -> Integer   |
+|             100000 | true    |             100000 | Integer -> Integer |
+|             0.0059 | false   |             0.0059 | Float -> Float     |
+| 16236565468798.668 | false   | 16236565468798.668 | Float -> Float     |
+#+end_example
 
-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.
+**** Method ~#secs_to_hms~
+This method converts a numeric representing a number of seconds or an angle in
+degrees to a ~String~ of the form "HH:MM:SS" representing the same quantity in
+hours, minutes, and seconds.
 
-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.).
+#+begin_src ruby
+  require_relative 'lib/fat_core/numeric'
+  result = []
+  result << ['N', 'HH:MM:SS']
+  result << nil
+  nums = [85777.66, 959.66, -1198.33, 0, 3.14159 * 180]
+  nums.each do |n|
+    result << [n, n.secs_to_hms]
+  end
+  result
+#+end_src
 
-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.
+#+begin_example
+|                 N | HH:MM:SS    |
+|-------------------+-------------|
+|          85777.66 | 23:49:37.66 |
+|            959.66 | 00:15:59.66 |
+|          -1198.33 | -1:40:01.67 |
+|                 0 | 00:00:00    |
+| 565.4861999999999 | 00:09:25.48 |
+#+end_example
 
-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
+~FatCore~ 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.
+
+**** Methods ~#contiguous~, ~#left_contiguous~, ~#right_contiguous~
+These methods determine whether the subject ~Range~ are "contiguous" with
+another ~Range~ on the left, right, or either side.  The notion of contiguity
+is different for ~Ranges~ whose min and max values respond to the ~#succ~
+method: if they do, "contiguity" only requires that the ~#succ~ of the max
+value of the left range equal the min value of the right ~Range~; otherwise
+the max value of the left ~Range~ must equal the min value of the right
+~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.
+#+begin_src ruby
+  require_relative 'lib/fat_core/range'
+  require 'date'
+
+  result = []
+  result << ["Self", "Other", "Contiguous?", "Right?", "Left?"]
+  result << nil
+  pairs = [
+    [(0..10), (11..12)],
+    [(11..20), (0..10)],
+    [(0..10), (15..20)],
+    [(3.145..12.3), (0.5..3.145)],
+    [(3.146..12.3), (0.5..3.145)],
+    [('a'..'q'), ('r'..'z')],
+    [('a'..'q'), ('s'..'z')],
+    [(Date.parse('1963-11-22')..Date.parse('1964-11-03')), (Date.parse('1964-11-04')..Date.today)],
+    [(Date.parse('1963-11-22')..Date.parse('1964-11-03')), (Date.parse('1964-11-28')..Date.today)]
+  ]
+  pairs.each do |r1, r2|
+    result << [r1.to_s, r2.to_s, r1.contiguous?(r2), r1.right_contiguous?(r2), r1.left_contiguous?(r2)]
+  end
+  result
+#+end_src
 
-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_example
+|                   Self |                  Other | Contiguous? | Right? | Left? |
+|------------------------+------------------------+-------------+--------+-------|
+|                  0..10 |                 11..12 | true        | true   | false |
+|                 11..20 |                  0..10 | true        | false  | true  |
+|                  0..10 |                 15..20 | false       | false  | false |
+|            3.145..12.3 |             0.5..3.145 | true        | false  | true  |
+|            3.146..12.3 |             0.5..3.145 | false       | false  | false |
+|                   a..q |                   r..z | true        | true   | false |
+|                   a..q |                   s..z | false       | false  | false |
+| 1963-11-22..1964-11-03 | 1964-11-04..2025-11-22 | true        | true   | false |
+| 1963-11-22..1964-11-03 | 1964-11-28..2025-11-22 | false       | false  | false |
+#+end_example
 
-#+begin_SRC ruby
-  require 'fat_core/range'
-  (0..12).gaps([(0..2), (5..7), (10..12)])  => [(3..4), (8..9)]
-#+end_SRC
+**** Method ~#join(other)~
+If ~self~ is contiguous with ~other~, return a new ~Range~ that splices the
+two ~Range~s into one ~Range~.
 
-* 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~.
+#+begin_src ruby
+  require_relative 'lib/fat_core/range'
+  require 'date'
+
+  result = []
+  result << ["Self", "Other", "Contiguous?", "Joined"]
+  result << nil
+  pairs = [
+    [(0..10), (11..12)],
+    [(11..20), (0..10)],
+    [(0..10), (15..20)],
+    [(3.145..12.3), (0.5..3.145)],
+    [(3.146..12.3), (0.5..3.145)],
+    [('a'..'q'), ('r'..'z')],
+    [('a'..'q'), ('s'..'z')],
+    [(Date.parse('1963-11-22')..Date.parse('1964-11-03')), (Date.parse('1964-11-04')..Date.today)],
+    [(Date.parse('1963-11-22')..Date.parse('1964-11-03')), (Date.parse('1964-11-28')..Date.today)]
+  ]
+  pairs.each do |r1, r2|
+    result << [r1.to_s, r2.to_s, r1.contiguous?(r2), "#{r1.join(r2)}"]
+  end
+  result
+#+end_src
 
-*** Hash
+#+begin_example
+|                   Self |                  Other | Contiguous? |                 Joined |
+|------------------------+------------------------+-------------+------------------------|
+|                  0..10 |                 11..12 | true        |                  0..12 |
+|                 11..20 |                  0..10 | true        |                  0..20 |
+|                  0..10 |                 15..20 | false       |                        |
+|            3.145..12.3 |             0.5..3.145 | true        |              0.5..12.3 |
+|            3.146..12.3 |             0.5..3.145 | false       |                        |
+|                   a..q |                   r..z | true        |                   a..z |
+|                   a..q |                   s..z | false       |                        |
+| 1963-11-22..1964-11-03 | 1964-11-04..2025-11-22 | true        | 1963-11-22..2025-11-22 |
+| 1963-11-22..1964-11-03 | 1964-11-28..2025-11-22 | false       |                        |
+#+end_example
+
+
+**** Method ~#spanned_by?(others)~
+A set of ~Ranges~ "spans" a given ~Range~ if the set is contiguous and fully
+covers the given ~Range~ with no overlaps and no gaps.  A set that over-covers
+the given ~Range~ is still considered to span it, even though it is wider than
+the given ~Range~.  In other words, a set spans the given ~Range~ if the set
+can be joined and the given ~Range~ is within the joined ~Range~.
 
-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~.
+#+begin_src ruby
+  require_relative 'lib/fat_core/range'
+  require 'date'
+
+  result = []
+  result << ["Self", "Others", "Spanned By?"]
+  result << nil
+  pairs = [
+    [(0..10), [(-1..5), (6..10)]],
+    [(1..20), [(0..10), (11..20)]],
+    [(1..20), [(0..10), (10..20)]],
+    [(3.145..12.3), [(0.5..3.45), (3.45..10.5), (10.5..13.5)]],
+    [(3.145..12.3), [(0.5..3.45), (3.45..10.5), (10.6..13.5)]],
+    [('a'..'z'), [('a'..'g'), ('h'..'s'), ('t'..'z')]],
+    [('a'..'z'), [('a'..'g'), ('j'..'s'), ('t'..'z')]],
+  ]
+  pairs.each do |r, others|
+    result << ["#{r}", "#{others}", r.spanned_by?(others)]
+  end
+  result
+#+end_src
 
-It also provides the shovel operator as a convenient alias for ~Hash#merge~,
-so that
+#+begin_example
+|        Self | Others                              | Spanned By? |
+|-------------+-------------------------------------+-------------|
+|       0..10 | [-1..5, 6..10]                      | true        |
+|       1..20 | [0..10, 11..20]                     | true        |
+|       1..20 | [0..10, 10..20]                     | false       |
+| 3.145..12.3 | [0.5..3.45, 3.45..10.5, 10.5..13.5] | true        |
+| 3.145..12.3 | [0.5..3.45, 3.45..10.5, 10.6..13.5] | false       |
+|        a..z | ["a".."g", "h".."s", "t".."z"]      | true        |
+|        a..z | ["a".."g", "j".."s", "t".."z"]      | false       |
+#+end_example
 
-#+begin_src ruby :tangle no
-{a: 'A', b: 'B', c: 'C'} << {c: 'CC', d: 'DD'} << {e: 'EEE'} => {a: 'A', b: 'B', c: 'CC', d: 'DD', e: 'EEE'}
+**** Methods ~#gaps(others)~, ~#overlaps(others)~
+When the set of other ~Ranges~ does not span the given ~Range~, these methods
+return an set of ~Ranges~ that represent the portions of the given ~Range~ no
+covered by the ~others~, the "gaps", or the points within the given ~Range~
+where the ~others~ overlap one another and thus are not contiguous.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/range'
+  require 'date'
+
+  result = []
+  result << ["Self", "Others", "Spanned By?", "Gaps", "Overlaps"]
+  result << nil
+  pairs = [
+    [(0..10), [(-1..5), (6..10)]],
+    [(1..20), [(0..10), (11..20)]],
+    [(1..20), [(0..15), (11..20)]],
+    [(1..20), [(0..10), (10..20)]],
+    [(3.145..12.3), [(0.5..3.45), (3.45..10.5), (10.5..13.5)]],
+    [(3.145..12.3), [(0.5..3.45), (3.45..10.5), (10.6..13.5)]],
+    [('a'..'z'), [('a'..'g'), ('h'..'s'), ('t'..'z')]],
+    [('a'..'z'), [('a'..'g'), ('j'..'s'), ('t'..'z')]],
+  ]
+  pairs.each do |r, others|
+    result << ["#{r}", "#{others}", r.spanned_by?(others), "#{r.gaps(others)}", "#{r.overlaps(others)}"]
+  end
+  result
 #+end_src
 
-*** String
+#+begin_example
+|        Self | Others                              | Spanned By? | Gaps         | Overlaps |
+|-------------+-------------------------------------+-------------+--------------+----------|
+|       0..10 | [-1..5, 6..10]                      | true        | []           | []       |
+|       1..20 | [0..10, 11..20]                     | true        | []           | []       |
+|       1..20 | [0..15, 11..20]                     | false       | []           | [11..15] |
+|       1..20 | [0..10, 10..20]                     | false       | []           | []       |
+| 3.145..12.3 | [0.5..3.45, 3.45..10.5, 10.5..13.5] | true        | []           | []       |
+| 3.145..12.3 | [0.5..3.45, 3.45..10.5, 10.6..13.5] | false       | [10.5..10.6] | []       |
+|        a..z | ["a".."g", "h".."s", "t".."z"]      | true        | []           | []       |
+|        a..z | ["a".."g", "j".."s", "t".."z"]      | false       | ["h".."i"]   | []       |
+#+end_example
 
+*** 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
@@ -509,21 +786,333 @@ into a useable Symbol (~#as_sym~) and vice-versa (~#as_str~ also
 cleaning up errant spaces (~#clean~), and computing the Damerau-Levenshtein
 distance between strings (~#distance~). And several others.
 
+**** Method ~#fuzzy_match~
+The ~#fuzzy_match~ method determines whether the subject string matches the
+given "matcher" string, which provides a simple syntax that allows a limited
+kind of pattern matching.  If there is a match, it returns the matched portion
+of self, minus punctuation characters, if self matches the string, and returns
+nil otherwise.
+
+What makes this handy is that a user trying to match by memory can be loose
+about case, punctuation, and spaces, and still find desired matches.  In the
+matcher both the space and colon ':' have special meaning as shown below.
+
+~#fuzzy_match(matcher)~ uses the following rules for matching:
+
+1. Remove leading and trailing whitespace in the subject and the matcher
+   and collapse its internal whitespace to a single space,
+2. Remove all periods, commas, apostrophes, and asterisks (the
+   punctuation characters) from both self and `matcher`,
+3. Treat internal ':stuff' or ' :stuff' in the matcher as the equivalent
+   of /\bstuff.*/ in a regular expression, that is, match any word
+   starting with stuff in self,
+4. Treat internal 'stuff: ' in the matcher as the equivalent of /.*stuff\b/ in
+   a regular expression, that is, match any word ending with stuff in self,
+5. A colon with no spaces around it is treated as belonging to the
+   following word, requiring it to start with it, so 'some:stuff'
+   requires 'some' anywhere followed by a word beginning with 'stuff',
+   i.e., /some.*\bstuff/i,
+6. Treat leading ':' in the matcher as anchoring the match to the
+   beginning of the target string,
+7. Treat ending ':' in the matcher as anchoring the match to the
+   end of the target string,
+8. Require each component to match some part of self, and
+
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  result = []
+  result << ['Self', 'Matcher', 'Match']
+  result << nil
+  subj = "St. Luke's Hospital"
+  matchers = ['st lukes', 'luk:hosp', 'st:spital', 'uk spital', 'st:laks', ':lukes', 's lukes', 'lukes:hospital']
+  matchers.each do |m|
+    result << [subj, m, subj.fuzzy_match(m)]
+  end
+  result
+#+end_src
+
+#+begin_example
+| Self                | Matcher        | Match          |
+|---------------------+----------------+----------------|
+| St. Luke's Hospital | st lukes       | St Lukes       |
+| St. Luke's Hospital | luk:hosp       | Lukes Hosp     |
+| St. Luke's Hospital | st:spital      | nil            |
+| St. Luke's Hospital | uk spital      | ukes Hospital  |
+| St. Luke's Hospital | st:laks        | nil            |
+| St. Luke's Hospital | :lukes         | nil            |
+| St. Luke's Hospital | s lukes        | St Lukes       |
+| St. Luke's Hospital | lukes:hospital | Lukes Hospital |
+#+end_example
+
+**** Method ~#matches_with~
+The ~#matches_with(matcher)~ method allows the use of either a regular
+expression or fuzzy matching as described above depending on whether the
+matcher is enclosed in '/' characters.  It also returns the matched portion of
+~self~ or nil if there is no match.  Even when a regex is given, the match is
+case insensitive by default and commas, apostrophes, and periods are removed
+from the subject string before matching.
+
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  result = []
+  result << ['Self', 'Matcher', 'Match']
+  result << nil
+  subj = "St. Luke's Hospital"
+  matchers = ['st lukes', '/luk.*hosp/', 'st:spital', '/u.*s\b/', 'st:laks', ':lukes', 's lukes', '/lukes hospital\z/']
+  matchers.each do |m|
+    result << [subj, m, subj.matches_with(m)]
+  end
+  result
+#+end_src
+
+#+begin_example
+| Self                | Matcher            | Match          |
+|---------------------+--------------------+----------------|
+| St. Luke's Hospital | st lukes           | St Lukes       |
+| St. Luke's Hospital | /luk.*hosp/        | Lukes Hosp     |
+| St. Luke's Hospital | st:spital          | nil            |
+| St. Luke's Hospital | /u.*s\b/           | ukes           |
+| St. Luke's Hospital | st:laks            | nil            |
+| St. Luke's Hospital | :lukes             | nil            |
+| St. Luke's Hospital | s lukes            | St Lukes       |
+| St. Luke's Hospital | /lukes hospital\z/ | Lukes Hospital |
+#+end_example
+
+**** Method ~#entitle~
+For a string meant to serve as the title of a book, song, or other item, there
+are certain rules in English as to which words should be capitalized and which
+should be put in lower case.  "PROFILES IN courage" should be rendered
+"Profiles in Courage" for example.  The preposition "in" is typically not
+capitalized unless it starts the title: "in the HEAT OF THE NIght" should be
+something like "In the Heat of the Night".
+
+#+begin_src ruby
+    require_relative './lib/fat_core/string'
+
+    result = []
+    result << ['Self', 'Entitled']
+    result << nil
+    titles = ['PROFILES IN courage', 'in the HEAT OF THE NIght', 'a day in the life', 'FROM HERE TO ETERNITY',
+             'lucy in the sky with diamonds']
+    titles.each do |t|
+      result << [t, t.entitle]
+    end
+    result
+#+end_src
+
+#+begin_example
+| Self                          | Entitled                      |
+|-------------------------------+-------------------------------|
+| PROFILES IN courage           | Profiles in Courage           |
+| in the HEAT OF THE NIght      | In the Heat of the Night      |
+| a day in the life             | A Day in the Life             |
+| FROM HERE TO ETERNITY         | From Here to Eternity         |
+| lucy in the sky with diamonds | Lucy in the Sky With Diamonds |
+#+end_example
+
+
+**** Method ~#distance~
+~FatCore~ provides ~distance~ as a simple wrapper around the
+Damerau-Levenshtein distance function in ~damerau-levenshtein~ gem, using a
+block size of 1 and a max distance of 10.
+
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  result = []
+  result << ['Word1', 'Word2', 'Distance']
+  result << nil
+  pairs = [['Shelf', 'Shell'], ['Shelf', 'Shall'], ['Doherty', 'Daughtery'], ['Doherty', 'Dorrit'], ['Smith', 'Jones']]
+  pairs.each do |w1, w2|
+    result << [w1, w2, w1.distance(w2)]
+  end
+  result
+#+end_src
+
+#+begin_example
+| Word1   | Word2     | Distance |
+|---------+-----------+----------|
+| Shelf   | Shell     | 1        |
+| Shelf   | Shall     | 2        |
+| Doherty | Daughtery | 5        |
+| Doherty | Dorrit    | 4        |
+| Smith   | Jones     | 5        |
+#+end_example
+
+**** Method ~#commas(places)~
+When presenting numbers, it is common to want to add grouping digits to make
+the numbers more readable.  The ~commas(places)~ method does this be
+converting the number into a Float, rounding to places digits, then converting
+back to a ~String~ with grouping commas inserted.
+
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  result = []
+  result << ['N', 'Places', 'With Commas']
+  result << nil
+  nums_places = [["798964655.66541325", 3], ["798964655.66541325", 0], ["798964655.66541325", 5], ["3.14159", 3],
+               ["3.14159e6", 3], ["-3.14159e4", 2], ["+3.14159e3", 2]]
+  nums_places.each do |n, p|
+    result << [n, p, n.commas(p)]
+  end
+  result
+#+end_src
+
+#+begin_example
+|                  N | Places |       With Commas |
+|--------------------+--------+-------------------|
+| 798964655.66541325 | 3      |   798,964,655.665 |
+| 798964655.66541325 | 0      |       798,964,656 |
+| 798964655.66541325 | 5      | 798,964,655.66541 |
+|            3.14159 | 3      |             3.142 |
+|          3.14159e6 | 3      |     3,141,590.000 |
+|         -3.14159e4 | 2      |        -31,415.90 |
+|         +3.14159e3 | 2      |          3,141.59 |
+#+end_example
+
+
+**** Method =#wrap(width, hang)=
+This method wraps the string to a given width with an optional hanging indent
+for lines after the first.
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  getty = <<~EOS
+  Four score and seven years ago our fathers brought forth on this continent,
+  a new nation, conceived in Liberty, and dedicated to the proposition that
+  all men are created equal.
+
+  Now we are engaged in a great civil war, testing whether that nation, or any
+  nation so conceived and so dedicated, can long endure.  We are met on a
+  great battle-field of that war.  We have come to dedicate a portion of that
+  field, as a final resting place for those who here gave their lives that
+  that nation might live.  It is altogether fitting and proper that we should
+  do this.
+
+  But, in a larger sense, we can not dedicate---we can not consecrate---we can
+  not hallow---this ground.  The brave men, living and dead, who struggled
+  here, have consecrated it, far above our poor power to add or detract.  The
+  world will little note, nor long remember what we say here, but it can never
+  forget what they did here.  It is for us the living, rather, to be dedicated
+  here to the unfinished work which they who fought here have thus far so
+  nobly advanced.  It is rather for us to be here dedicated to the great task
+  remaining before us---that from these honored dead we take increased
+  devotion to that cause for which they gave the last full measure of
+  devotion---that we here highly resolve that these dead shall not have died
+  in vain---that this nation, under God, shall have a new birth of
+  freedom---and that government of the people, by the people, for the people,
+  shall not perish from the earth.
+  EOS
+  getty.wrap(110, 3)
+#+end_src
+
+#+begin_example
+Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived
+   in Liberty, and dedicated to the proposition that all men are created equal. Now we are engaged
+   in a great civil war, testing whether that nation, or any nation so conceived and so dedicated,
+   can long endure. We are met on a great battle-field of that war. We have come to dedicate
+   a portion of that field, as a final resting place for those who here gave their lives that
+   that nation might live. It is altogether fitting and proper that we should do this. But, in
+   a larger sense, we can not dedicate---we can not consecrate---we can not hallow---this ground.
+   The brave men, living and dead, who struggled here, have consecrated it, far above our poor
+   power to add or detract. The world will little note, nor long remember what we say here, but
+   it can never forget what they did here. It is for us the living, rather, to be dedicated here
+   to the unfinished work which they who fought here have thus far so nobly advanced. It is rather
+   for us to be here dedicated to the great task remaining before us---that from these honored
+   dead we take increased devotion to that cause for which they gave the last full measure of
+   devotion---that we here highly resolve that these dead shall not have died in vain---that this
+   nation, under God, shall have a new birth of freedom---and that government of the people, by
+   the people, for the people, shall not perish from the earth.
+#+end_example
+
+**** Method =#as_sym=
+Convert a ~String~ to a ~Symbol~ by converting all letters to lower-case,
+replacing hyphens and white space with a single underscore, and removing all
+non-alphanumeric characters:
+
+#+begin_src ruby
+  require_relative './lib/fat_core/string'
+
+  "   Hello-to-the      World!!!".as_sym
+#+end_src
+
+#+begin_example
+:hello_to_the_world
+#+end_example
+
+*** Symbol
+**** Method =#as_str=
+A quasi-inverse of ~String#as_sym~, convert a ~Symbol~ into a ~String~ by
+converting '_' to a hyphen, white-space into '_', and eliminate any
+non-alphanumeric characters.
+
+#+begin_src ruby
+  require_relative 'lib/fat_core/symbol'
+
+  :hello_to_the_world.as_str
+#+end_src
+
+#+begin_example
+hello-to-the-world
+#+end_example
+
 *** TeX Quoting
+The extensions for ~String~, ~Numeric~, ~Range~, ~Symbol~, and ~NilClass~
+provide a ~#tex_quote~ method for quoting the string version of an object so
+as to allow its inclusion in a TeX document while quoting characters such as
+'_', $' or '%' that have a special meaning for TeX.  At the same time it
+deploys TeX notation when special notation is available, for example, a
+~Rational~ is rendered as a fraction.
 
-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.
+#+begin_src ruby
+  require_relative 'lib/fat_core/all'
+  require 'date'
+
+  result = []
+  result << ['Class', 'Example', '#tex_quote']
+  result << nil
+  examples = [
+    "Save $100 or 14% on this Friday_Black",
+    58743.44,
+    Float::INFINITY,
+    Math::PI,
+    Complex(5, 3),
+    Complex(5.0, 3.0),
+    Rational(5, 3),
+    Rational(8.0, 17.0),
+    (Date.parse('2020-09-22')..Date.today),
+    (Math::E..Math::PI),
+    :four_score_and_7_years,
+    nil
+    ]
+  examples.each do |ex|
+    result << [ex.class, ex.to_s, ex.tex_quote.inspect]
+  end
+  result
+#+end_src
 
-*** Numbers
+#+begin_example
+| Class    | Example                               | #tex_quote                                    |
+|----------+---------------------------------------+-----------------------------------------------|
+| String   | Save $100 or 14% on this Friday_Black | "Save \\$100 or 14\\% on this Friday\\_Black" |
+| Float    | 58743.44                              | "58743.44"                                    |
+| Float    | Infinity                              | "$\\infty$"                                   |
+| Float    | 3.141592653589793                     | "$\\pi$"                                      |
+| Complex  | 5+3i                                  | "$5+3i$"                                      |
+| Complex  | 5.0+3.0i                              | "$5+3i$"                                      |
+| Rational | 5/3                                   | "$\\frac{5}{3}$"                              |
+| Rational | 8/17                                  | "$\\frac{8}{17}$"                             |
+| Range    | 2020-09-22..2025-11-24                | "(2020-09-22..2025-11-24)"                    |
+| Range    | 2.718281828459045..3.141592653589793  | "($e$..$\\pi$)"                               |
+| Symbol   | four_score_and_7_years                | "four\\_score\\_and\\_7\\_years"              |
+| NilClass |                                       | ""                                            |
+#+end_example
 
-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
+* Contributing
 
 1. Fork it ([[http://github.com/ddoherty03/fat_core/fork]]  )
 2. Create your feature branch (~git checkout -b my-new-feature~)