fat_core 7.1.3 → 7.2.0

data/README.org

@@ -1,96 +1,27 @@
 #+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
+#+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
+#+PROPERTY: header-args:ruby+ :wrap example :eval yes
+#+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fat_core/all'; nil"
+#+PROPERTY: header-args:ruby+ :session fat_core_session :ruby "bundle exec irb"
+#+PROPERTY: header-args:sh :exports code :eval no
+#+PROPERTY: header-args:bash :exports code :eval no
 
-[[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]]
+#+BEGIN_EXPORT markdown
+[![CI](https://github.com/ddoherty03/fat_core/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ddoherty03/fat_core/actions/workflows/ruby.yml)
+#+END_EXPORT
 
 * Version
 #+begin_src ruby
-  require_relative './lib/fat_core/version'
   "Current version is: #{FatCore::VERSION}"
 #+end_src
 
+#+RESULTS:
 #+begin_example
-Current version is: 7.0.0
+Current version is: 7.1.3
 #+end_example
 
-* FatCore
-
+* Introduction
 ~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,
@@ -101,19 +32,19 @@ projects and provide a focused place to develop and test them.
 
 Add this line to your application's Gemfile:
 
-#+begin_src ruby
+#+begin_src ruby :eval no
   gem 'fat_core'
 #+end_SRC
 
 And then execute:
 
-#+begin_src shell
+#+begin_src sh
   $ bundle
 #+end_src
 
 Or install it yourself as:
 
-#+begin_src shell
+#+begin_src sh
   $ gem install fat_core
 #+end_src
 
@@ -121,7 +52,7 @@ Or install it yourself as:
 
 You can extend classes individually by requiring the corresponding file:
 
-#+begin_SRC ruby
+#+begin_SRC ruby :eval no
   require 'fat_core/array'
   require 'fat_core/bigdecimal'
   require 'fat_core/enumerable'
@@ -139,11 +70,16 @@ Or, you can require them all:
   require 'fat_core/all'
 #+end_SRC
 
+#+RESULTS:
+#+begin_example
+false
+#+end_example
+
 Many of these have little that is of general interest, but there are a few
 goodies.
 
-*** Array
-**** Method ~#comma_join(sep: nil, last_sep: nil, two_sep: nil)~
+** 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 ', '.
@@ -165,21 +101,19 @@ default.
 If the input array is empty, ~#comma_join~ returns an empty string.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/array'
-
   %w{hammers nails glue bolts}.comma_join
 #+end_src
 
+#+RESULTS:
 #+begin_example
 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
 hammers and nails
 #+end_example
@@ -187,74 +121,69 @@ hammers and nails
 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
 
+#+RESULTS:
 #+begin_example
 hammers, nails, glue and bolts
 #+end_example
 
-**** Method ~#last_i~
+*** 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
 
+#+RESULTS:
 #+begin_example
 3
 #+end_example
 
-**** Method ~#intersect_with_dups~
+*** 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}
+  b = %w{nails fingers bolts knuckles nails}
   a.intersect_with_dups(b)
 #+end_src
 
+#+RESULTS:
 #+begin_example
-| nails | nails |
+| nails | bolts | nails |
 #+end_example
 
-**** Method ~diff_with_dups~
+*** 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
 
+#+RESULTS:
 #+begin_example
 | hammers | glue | bolts | hammers |
 #+end_example
 
-*** BigDecimal ~#inspect~
+** 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
 
+#+RESULTS:
 #+begin_example
 2.1718281828
 #+end_example
@@ -262,8 +191,8 @@ class since the default inspect method is not very readable.
 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~
+** 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
@@ -271,8 +200,6 @@ 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|
@@ -288,6 +215,7 @@ these two cases specially without testing the index as in ~#each_with_index~.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Start    |  1, |
 | Continue |  1, |
@@ -299,17 +227,15 @@ these two cases specially without testing the index as in ~#each_with_index~.
 | Last     |  21 |
 #+end_example
 
-*** Hash
+** Hash
 FatCore::Hash extends the Hash class with some useful methods.
 
-**** Method ~#each_pair_with_flags~
+*** 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' }
@@ -330,6 +256,7 @@ for the first and last elements but ~false~ otherwise:
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Position | Author      | Novel                  |
 |----------+-------------+------------------------|
@@ -340,18 +267,17 @@ for the first and last elements but ~false~ otherwise:
 | End      | E. Brontë   | Wuthering Heights      |
 #+end_example
 
-**** Method ~#delete_with_value~ and ~#delete_with_value!~
+*** 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
 
+#+RESULTS:
 #+begin_example
 {:a=>1, :c=>3, :e=>1}
 #+end_example
@@ -359,13 +285,12 @@ equals the given value or values:
 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
 
+#+RESULTS:
 #+begin_example
 {:b=>2, :d=>2}
 #+end_example
@@ -373,91 +298,94 @@ You can supply multiple values for deletion:
 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
 
+#+RESULTS:
 #+begin_example
 {:a=>1, :b=>2, :c=>3, :d=>2, :e=>1}
 {:b=>2, :d=>2}
 #+end_example
 
-**** Method ~#keys_with_value~
+*** 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'
+#+begin_src ruby :results value code
+  h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+  h.keys_with_value(1).inspect
+#+end_src
 
+#+RESULTS:
+#+begin_example
+"[:a, :e]"
+#+end_example
+
+#+begin_src ruby :results value code
   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
+  h.keys_with_value(2, 3).inspect
 #+end_src
 
+#+RESULTS:
 #+begin_example
-[:a, :e]
-[:b, :d, :c]
+"[:b, :d, :c]"
 #+end_example
 
-**** Method ~#remap_keys~
+*** 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
+#+begin_src ruby :results value code
   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
+  h.remap_keys({:a => :A, :b => :B}).inspect
 #+end_src
 
+#+RESULTS:
 #+begin_example
-{:A=>1, :B=>2, :c=>3, :d=>2, :e=>1}
+"{:A=>1, :B=>2, :c=>3, :d=>2, :e=>1}"
 #+end_example
 
 These days, a more systematic job could be done with ~#transform_keys~:
-#+begin_src ruby :results output
+#+begin_src ruby :results value code
   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
-  puts h.transform_keys { |k| k.to_s.upcase.to_sym }.inspect
+  h.transform_keys { |k| k.to_s.upcase.to_sym }.inspect
 #+end_src
 
+#+RESULTS:
 #+begin_example
-{:A=>1, :B=>2, :C=>3, :D=>2, :E=>1}
+"{:A=>1, :B=>2, :C=>3, :D=>2, :E=>1}"
 #+end_example
 
-**** Method ~#replace_keys~
+*** Method ~#replace_keys~
 A wholesale replacement of the existing keys can be done with this method:
 
-#+begin_src ruby :results output
-  require_relative './lib/fat_core/hash'
-
+#+begin_src ruby :results value code
   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
-  puts h
-  puts h.replace_keys([:z, :y, :x, :w, :v]).inspect
+  h.replace_keys([:z, :y, :x, :w, :v]).inspect
 #+end_src
 
+#+RESULTS:
 #+begin_example
-{:a=>1, :b=>2, :c=>3, :d=>2, :e=>1}
-{:z=>1, :y=>2, :x=>3, :w=>2, :v=>1}
+"{:z=>1, :y=>2, :x=>3, :w=>2, :v=>1}"
 #+end_example
 
-**** Alias ~#merge~ to ~<<~
+*** 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
+#+begin_src ruby :results value code
+  {a: 'A', b: 'B', c: 'C'} << {c: 'CC', d: 'DD'} << {d: 'DDD', e: 'EEE'}
 #+end_src
 
+#+RESULTS:
 #+begin_example
 {:a=>"A", :b=>"B", :c=>"CC", :d=>"DDD", :e=>"EEE"}
 #+end_example
@@ -466,9 +394,8 @@ 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
+#+begin_src ruby :results value code
   require 'fileutils'
-  require_relative './lib/fat_core/hash'
 
   FileUtils.mkdir_p('./tmp')
   ff = File.open('./tmp/junk', 'w')
@@ -480,27 +407,40 @@ is an ~Array~ or ~Enumerable~:
       {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
+  h
 #+end_src
 
+#+RESULTS:
 #+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~
+** Numeric
+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~).
+
+*** Method ~#signum~
 Return ~-1~ for negative numbers, ~0~ for zero, and ~+1~ for positive numbers.
 This is sometimes handy.
 
-**** Method ~#commas(places = nil)~
+#+begin_src ruby :results value code
+[-55.signum, 0.signum, 55.signum]
+#+end_src
+
+#+RESULTS:
+#+begin_example
+[-1, 0, 1]
+#+end_example
+
+*** 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
@@ -514,6 +454,7 @@ To get s ~String~ representation of a ~Numeric~ with grouping commas inserted,
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                  N | Places |         N.commas(places) |
 |--------------------+--------+--------------------------|
@@ -534,17 +475,11 @@ To get s ~String~ representation of a ~Numeric~ with grouping commas inserted,
 | 16236565468798.668 | 5      | 16,236,565,468,798.66800 |
 #+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~).
-
-**** Methods ~#whole?~ and ~#int_if_whole~
+*** 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
-  require_relative 'lib/fat_core/numeric'
   result = []
   result << ['N', '#whole?', '#int_if_whole', 'Classes']
   result << nil
@@ -555,6 +490,7 @@ At times it is useful to know if a Float or BigDecimal can be converted to an
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                  N | #whole? |      #int_if_whole | Classes            |
 |--------------------+---------+--------------------+--------------------|
@@ -565,13 +501,12 @@ At times it is useful to know if a Float or BigDecimal can be converted to an
 | 16236565468798.668 | false   | 16236565468798.668 | Float -> Float     |
 #+end_example
 
-**** Method ~#secs_to_hms~
+*** 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.
+hours (or degrees), minutes, and seconds.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/numeric'
   result = []
   result << ['N', 'HH:MM:SS']
   result << nil
@@ -582,6 +517,7 @@ hours, minutes, and seconds.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                 N | HH:MM:SS    |
 |-------------------+-------------|
@@ -592,8 +528,7 @@ hours, minutes, and seconds.
 | 565.4861999999999 | 00:09:25.48 |
 #+end_example
 
-
-*** Range
+** 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?~,
@@ -604,7 +539,7 @@ 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~
+*** 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~
@@ -614,7 +549,6 @@ the max value of the left ~Range~ must equal the min value of the right
 ~Range~.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/range'
   require 'date'
 
   result = []
@@ -637,6 +571,7 @@ the max value of the left ~Range~ must equal the min value of the right
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                   Self |                  Other | Contiguous? | Right? | Left? |
 |------------------------+------------------------+-------------+--------+-------|
@@ -647,16 +582,15 @@ the max value of the left ~Range~ must equal the min value of the right
 |            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 |
+| 1963-11-22..1964-11-03 | 1964-11-04..2026-05-29 | true        | true   | false |
+| 1963-11-22..1964-11-03 | 1964-11-28..2026-05-29 | false       | false  | false |
 #+end_example
 
-**** Method ~#join(other)~
+*** Method ~#join(other)~
 If ~self~ is contiguous with ~other~, return a new ~Range~ that splices the
 two ~Range~s into one ~Range~.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/range'
   require 'date'
 
   result = []
@@ -679,6 +613,7 @@ two ~Range~s into one ~Range~.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                   Self |                  Other | Contiguous? |                 Joined |
 |------------------------+------------------------+-------------+------------------------|
@@ -689,12 +624,11 @@ two ~Range~s into one ~Range~.
 |            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       |                        |
+| 1963-11-22..1964-11-03 | 1964-11-04..2026-05-29 | true        | 1963-11-22..2026-05-29 |
+| 1963-11-22..1964-11-03 | 1964-11-28..2026-05-29 | false       |                        |
 #+end_example
 
-
-**** Method ~#spanned_by?(others)~
+*** 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
@@ -702,7 +636,6 @@ 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~.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/range'
   require 'date'
 
   result = []
@@ -723,6 +656,7 @@ can be joined and the given ~Range~ is within the joined ~Range~.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |        Self | Others                              | Spanned By? |
 |-------------+-------------------------------------+-------------|
@@ -735,14 +669,13 @@ can be joined and the given ~Range~ is within the joined ~Range~.
 |        a..z | ["a".."g", "j".."s", "t".."z"]      | false       |
 #+end_example
 
-**** Methods ~#gaps(others)~, ~#overlaps(others)~
+*** 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 = []
@@ -764,6 +697,7 @@ where the ~others~ overlap one another and thus are not contiguous.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |        Self | Others                              | Spanned By? | Gaps         | Overlaps |
 |-------------+-------------------------------------+-------------+--------------+----------|
@@ -777,7 +711,8 @@ where the ~others~ overlap one another and thus are not contiguous.
 |        a..z | ["a".."g", "j".."s", "t".."z"]      | false       | ["h".."i"]   | []       |
 #+end_example
 
-*** String
+** 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
@@ -786,7 +721,7 @@ 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~
+*** 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
@@ -823,8 +758,6 @@ matcher both the space and colon ':' have special meaning as shown below.
 9. 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
@@ -836,6 +769,7 @@ matcher both the space and colon ':' have special meaning as shown below.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Self                | Matcher        | Match          |
 |---------------------+----------------+----------------|
@@ -850,7 +784,7 @@ matcher both the space and colon ':' have special meaning as shown below.
 | St. Luke's Hospital | lukes:hospital | Lukes Hospital |
 #+end_example
 
-**** Method ~#matches_with~
+*** 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
@@ -859,8 +793,6 @@ 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
@@ -872,20 +804,21 @@ from the subject string before matching.
   result
 #+end_src
 
+#+RESULTS:
 #+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 |
+| Self                | Matcher            | Match       |
+|---------------------+--------------------+-------------|
+| St. Luke's Hospital | st lukes           | St Lukes    |
+| St. Luke's Hospital | /luk.*hosp/        | Luke's Hosp |
+| St. Luke's Hospital | st:spital          | nil         |
+| St. Luke's Hospital | /u.*s\b/           | uke's       |
+| 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/ | nil         |
 #+end_example
 
-**** Method ~#entitle~
+*** 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
@@ -894,8 +827,6 @@ 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
@@ -907,6 +838,7 @@ something like "In the Heat of the Night".
     result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Self                          | Entitled                      |
 |-------------------------------+-------------------------------|
@@ -917,15 +849,12 @@ something like "In the Heat of the Night".
 | lucy in the sky with diamonds | Lucy in the Sky With Diamonds |
 #+end_example
 
-
-**** Method ~#distance~
+*** 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
@@ -936,6 +865,7 @@ block size of 1 and a max distance of 10.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Word1   | Word2     | Distance |
 |---------+-----------+----------|
@@ -946,15 +876,13 @@ block size of 1 and a max distance of 10.
 | Smith   | Jones     | 5        |
 #+end_example
 
-**** Method ~#commas(places)~
+*** 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
@@ -966,6 +894,7 @@ back to a ~String~ with grouping commas inserted.
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 |                  N | Places |       With Commas |
 |--------------------+--------+-------------------|
@@ -978,13 +907,10 @@ back to a ~String~ with grouping commas inserted.
 |         +3.14159e3 | 2      |          3,141.59 |
 #+end_example
 
-
-**** Method =#wrap(width, hang)=
+*** 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
@@ -1014,6 +940,7 @@ for lines after the first.
   getty.wrap(110, 3)
 #+end_src
 
+#+RESULTS:
 #+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
@@ -1033,38 +960,153 @@ Four score and seven years ago our fathers brought forth on this continent, a ne
    the people, for the people, shall not perish from the earth.
 #+end_example
 
-**** Method =#as_sym=
+#+begin_src ruby
+getty.wrap(40, 2)
+#+end_src
+
+#+RESULTS:
+#+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
 
+#+RESULTS:
 #+begin_example
 :hello_to_the_world
 #+end_example
 
-*** Symbol
-**** Method =#as_str=
+*** Method ~gut~
+Very often one wants to truncate a string to a given size, but it is often the
+case that the most important parts of a string are at the beginning and the
+end.  The ~#gut(size)~ method returns a sting of length ~size~ by removing
+content from the middle of the string and leaving as much as possible at the
+two ends.
+
+#+begin_src ruby
+  result = []
+  result << ['Self', 'Gutted']
+  result << nil
+  strings = ["/usr/bin/fallacious", "Class A Common Stock", 'PROFILES IN courage', 'in the HEAT OF THE NIght', 'a day in the life', 'FROM HERE TO ETERNITY',
+             'lucy in the sky with diamonds']
+  strings.each do |t|
+    result << [t, t.gut(15)]
+  end
+  result
+#+end_src
+
+#+RESULTS:
+#+begin_example
+| Self                          | Gutted          |
+|-------------------------------+-----------------|
+| /usr/bin/fallacious           | /usr/bi~lacious |
+| Class A Common Stock          | Class A~n Stock |
+| PROFILES IN courage           | PROFILE~courage |
+| in the HEAT OF THE NIght      | in the ~E NIght |
+| a day in the life             | a day i~he life |
+| FROM HERE TO ETERNITY         | FROM HE~TERNITY |
+| lucy in the sky with diamonds | lucy in~iamonds |
+#+end_example
+
+By default, the deleted middle part is replace with the tilde character, but
+with the ellipsis parameter, you can make it whatever you want:
+
+#+begin_src ruby
+'Class A Common Stock'.gut(15, ellipsis: '...')
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Class ... Stock
+#+end_example
+
+Including, nothing at all:
+
+#+begin_src ruby
+'Class A Common Stock'.gut(15, ellipsis: '')
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Class A n Stock
+#+end_example
+
+And, you can optionally squeeze out spaces or other characters with the
+
+#+begin_src ruby
+'Class A Common Stock'.gut(16, ellipsis: '', squeeze: ' ')
+#+end_src
+
+#+RESULTS:
+#+begin_example
+ClassAComonStock
+#+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
 
+#+RESULTS:
 #+begin_example
 hello-to-the-world
 #+end_example
 
-*** TeX Quoting
+** 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
@@ -1073,7 +1115,6 @@ deploys TeX notation when special notation is available, for example, a
 ~Rational~ is rendered as a fraction.
 
 #+begin_src ruby
-  require_relative 'lib/fat_core/all'
   require 'date'
 
   result = []
@@ -1099,6 +1140,7 @@ deploys TeX notation when special notation is available, for example, a
   result
 #+end_src
 
+#+RESULTS:
 #+begin_example
 | Class    | Example                               | #tex_quote                                    |
 |----------+---------------------------------------+-----------------------------------------------|
@@ -1110,13 +1152,12 @@ deploys TeX notation when special notation is available, for example, a
 | 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    | 2020-09-22..2026-05-29                | "(2020-09-22..2026-05-29)"                    |
 | Range    | 2.718281828459045..3.141592653589793  | "($e$..$\\pi$)"                               |
 | Symbol   | four_score_and_7_years                | "four\\_score\\_and\\_7\\_years"              |
 | NilClass |                                       | ""                                            |
 #+end_example
 
-
 * Contributing
 
 1. Fork it ([[http://github.com/ddoherty03/fat_core/fork]]  )