ruby-nuggets 0.6.9 → 0.7.0

data/lib/nuggets/hash/nest_mixin.rb

@@ -30,9 +30,9 @@ module Nuggets
     module NestMixin
 
   # call-seq:
-  #   Hash.nest(depth = 0) => aHash
-  #   Hash.nest(depth = 0, value) => aHash
-  #   Hash.nest(depth = 0) { |key| ... } => aHash
+  #   Hash.nest([depth]) => aHash
+  #   Hash.nest([depth[, value]]) => aHash
+  #   Hash.nest([depth]) { |key| ... } => aHash
   #
   # Creates a nested hash, +depth+ levels deep. The final hash will receive a
   # default value of +value+ or, if +value+ is not given but a block is given,

data/lib/nuggets/hash/only.rb

@@ -30,10 +30,11 @@ require 'nuggets/hash/at'
 class Hash
 
   # call-seq:
-  #   hash.only(relax = true or false) => aHash
+  #   hash.only => aHash
+  #   hash.only(+true+) => aHash
   #
   # Returns the only key/value pair of _hash_. Raises an IndexError if _hash_'s
-  # size is not 1, unless +relax+ is true.
+  # size is not 1, unless parameter +true+ is passed.
   def only(relax = size == 1, split = false)
     raise IndexError, 'not a single-element hash' unless relax
 
@@ -41,10 +42,11 @@ class Hash
   end
 
   # call-seq:
-  #   hash.only_pair(relax = true or false) => anArray
+  #   hash.only_pair => anArray
+  #   hash.only_pair(+true+) => anArray
   #
   # Returns the only key/value pair of _hash_ as an array. Raises an IndexError
-  # if _hash_'s size is not 1, unless +relax+ is true.
+  # if _hash_'s size is not 1, unless parameter +true+ is passed.
   def only_pair(relax = size == 1)
     only(relax, true)
   end

data/lib/nuggets/hash/unroll_mixin.rb

@@ -31,7 +31,7 @@ module Nuggets
 
   # call-seq:
   #   hash.unroll(*value_keys) => anArray
-  #   hash.unroll(*value_keys, :sort => ...) => anArray
+  #   hash.unroll(*value_keys, :sort_by => ...) => anArray
   #   hash.unroll(*value_keys) { |value_hash| ... } => anArray
   #
   # "Unrolls" a nested hash, so that each path through _hash_ results in a

data/lib/nuggets/io/modes.rb

@@ -34,8 +34,8 @@ class IO
     alias_method :_nuggets_original_read, :read
 
     # call-seq:
-    #   IO.read(name, [length [, offset]]) => aString
-    #   IO.read(name, binary = false) { |io| ... } => anObject
+    #   IO.read(name[, length[, offset]]]) => aString
+    #   IO.read(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode +r+. NOTE: With no associated block,
     # acts like the original IO::read, not like IO::new.
@@ -60,8 +60,8 @@ class IO
     end
 
     # call-seq:
-    #   IO.write(name, binary = false) => anIO
-    #   IO.write(name, binary = false) { |io| ... } => anObject
+    #   IO.write(name[, binary]) => anIO
+    #   IO.write(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode +w+.
     def write(name, binary = false)
@@ -69,8 +69,8 @@ class IO
     end
 
     # call-seq:
-    #   IO.append(name, binary = false) => anIO
-    #   IO.append(name, binary = false) { |io| ... } => anObject
+    #   IO.append(name[, binary]) => anIO
+    #   IO.append(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode +a+.
     def append(name, binary = false)
@@ -78,8 +78,8 @@ class IO
     end
 
     # call-seq:
-    #   IO.read_write(name, binary = false) => anIO
-    #   IO.read_write(name, binary = false) { |io| ... } => anObject
+    #   IO.read_write(name[, binary]) => anIO
+    #   IO.read_write(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode <tt>r+</tt>.
     def read_write(name, binary = false)
@@ -87,8 +87,8 @@ class IO
     end
 
     # call-seq:
-    #   IO.write_read(name, binary = false) => anIO
-    #   IO.write_read(name, binary = false) { |io| ... } => anObject
+    #   IO.write_read(name[, binary]) => anIO
+    #   IO.write_read(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode <tt>w+</tt>.
     def write_read(name, binary = false)
@@ -96,8 +96,8 @@ class IO
     end
 
     # call-seq:
-    #   IO.append_read(name, binary = false) => anIO
-    #   IO.append_read(name, binary = false) { |io| ... } => anObject
+    #   IO.append_read(name[, binary]) => anIO
+    #   IO.append_read(name[, binary]) { |io| ... } => anObject
     #
     # Opens +name+ with mode <tt>a+</tt>.
     def append_read(name, binary = false)

data/lib/nuggets/numeric/duration.rb

@@ -58,7 +58,7 @@ class Numeric
   end
 
   # call-seq:
-  #   num.to_hms(precision = 0, labels = %w[h m s]) => aString
+  #   num.to_hms([precision[, labels]]) => aString
   #
   # Produces a stringified version of _num_'s time portions (cf. #hms),
   # with the specified +precision+ for the seconds (treated as floating
@@ -82,11 +82,11 @@ class Numeric
   end
 
   # call-seq:
-  #   num.to_ymd(include_hms = false, labels = %w[y m d]) => aString
+  #   num.to_ymd([include_hms[, labels]]) => aString
   #
   # Produces a stringified version of _num_'s date portions (cf. #ymd),
   # analogous to #to_hms. Includes time portions (cf. #hms) if +include_hms+
-  # is true.
+  # is +true+.
   def to_ymd(include_hms = false, labels = %w[y m d])
     unless include_hms
       to_hms(0, labels, ymd)

data/lib/nuggets/object/blank_mixin.rb

@@ -30,7 +30,7 @@ module Nuggets
     module BlankMixin
 
   # call-seq:
-  #   object.blank? => true or false
+  #   object.blank? => +true+ or +false+
   #
   # Basically a short-cut to <tt>object.nil? || object.empty?</tt>.
   def blank?(*modifiers)
@@ -58,7 +58,7 @@ module Nuggets
   end
 
   # call-seq:
-  #   object.void? => true or false
+  #   object.void? => +true+ or +false+
   #
   # Adds white-space strings, 0 and arrays of +nil+ objects to the list of
   # blank objects.
@@ -74,9 +74,9 @@ module Nuggets
     module BlankMixin
 
   # call-seq:
-  #   array.vain? => true or false
+  #   array.vain? => +true+ or +false+
   #
-  # Returns true if all of _array_'s elements are themselves vain.
+  # Returns +true+ if all of _array_'s elements are themselves vain.
   def vain?
     blank? { |a| a.delete_if { |i| i.vain? } }
   end
@@ -88,9 +88,9 @@ module Nuggets
     module BlankMixin
 
   # call-seq:
-  #   hash.vain? => true or false
+  #   hash.vain? => +true+ or +false+
   #
-  # Returns true if all of _hash_'s values are themselves vain.
+  # Returns +true+ if all of _hash_'s values are themselves vain.
   def vain?
     blank? { |h| h.delete_if { |_, v| v.vain? } }
   end

data/lib/nuggets/object/boolean_mixin.rb

@@ -30,7 +30,7 @@ module Nuggets
     module BooleanMixin
 
   # call-seq:
-  #   object.boolean? => true or false
+  #   object.boolean? => +true+ or +false+
   #
   #
   def boolean?
@@ -38,7 +38,7 @@ module Nuggets
   end
 
   # call-seq:
-  #   object.negate => true or false
+  #   object.negate => +true+ or +false+
   #
   #
   def negate
@@ -48,7 +48,7 @@ module Nuggets
   alias_method :false?, :negate
 
   # call-seq:
-  #   object.to_bool => true or false
+  #   object.to_bool => +true+ or +false+
   #
   #
   def to_bool

data/lib/nuggets/object/singleton_class_mixin.rb

@@ -74,10 +74,10 @@ module Nuggets
   alias_method :singleton_instance, :singleton_object
 
   # call-seq:
-  #   object.singleton_class? => true or false
+  #   object.singleton_class? => +true+ or +false+
   #
-  # Returns true if _object_ is a singleton_class
-  # (i.e., has a singleton_object), false otherwise.
+  # Returns +true+ if _object_ is a singleton_class
+  # (i.e., has a singleton_object), +false+ otherwise.
   def singleton_class?
     singleton_object
     true

data/lib/nuggets/range/quantile_mixin.rb

@@ -30,7 +30,7 @@ module Nuggets
     module QuantileMixin
 
   # call-seq:
-  #   range.quantile(value, order = 100) => anInteger
+  #   range.quantile(value[, order]) => anInteger
   #
   # Determines the <tt>order</tt>-quantile of +value+ in _range_.
   def quantile(value, order = 100)

data/lib/nuggets/statistics.rb

@@ -0,0 +1,11 @@
+# load statistics related nuggets
+
+require 'nuggets/array/correlation'
+require 'nuggets/array/histogram'
+require 'nuggets/array/mean'
+require 'nuggets/array/median'
+require 'nuggets/array/mode'
+require 'nuggets/array/regression'
+require 'nuggets/array/standard_deviation'
+require 'nuggets/array/variance'
+require 'nuggets/range/quantile'

data/lib/nuggets/statistics_mixins.rb

@@ -0,0 +1,11 @@
+# load statistics related nuggets (mixins)
+
+require 'nuggets/array/correlation_mixin'
+require 'nuggets/array/histogram_mixin'
+require 'nuggets/array/mean_mixin'
+require 'nuggets/array/median_mixin'
+require 'nuggets/array/mode_mixin'
+require 'nuggets/array/regression_mixin'
+require 'nuggets/array/standard_deviation_mixin'
+require 'nuggets/array/variance_mixin'
+require 'nuggets/range/quantile_mixin'

data/lib/nuggets/string/case.rb

@@ -46,7 +46,7 @@ class String
   end
 
   # call-seq:
-  #   str.lower_case? => true or false
+  #   str.lower_case? => +true+ or +false+
   #
   # Tell whether _str_ is all lower case.
   def lower_case?
@@ -55,7 +55,7 @@ class String
   alias_method :downcase?, :lower_case?
 
   # call-seq:
-  #   str.upper_case? => true or false
+  #   str.upper_case? => +true+ or +false+
   #
   # Tell whether _str_ is all upper case.
   def upper_case?
@@ -64,7 +64,7 @@ class String
   alias_method :upcase?, :upper_case?
 
   # call-seq:
-  #   str.mixed_case? => true or false
+  #   str.mixed_case? => +true+ or +false+
   #
   # Tell whether _str_ is mixed case.
   def mixed_case?
@@ -72,7 +72,7 @@ class String
   end
 
   # call-seq:
-  #   str.capitalized? => true or false
+  #   str.capitalized? => +true+ or +false+
   #
   # Tell whether _str_ is capitalized.
   def capitalized?

data/lib/nuggets/string/msub.rb

@@ -48,7 +48,7 @@ class String
   end
 
   # call-seq:
-  #   str.msub!(*substitutions) => str or nil
+  #   str.msub!(*substitutions) => str or +nil+
   #
   # Destructive version of #msub.
   def msub!(*substitutions)

data/lib/nuggets/string/nsub.rb

@@ -41,8 +41,8 @@ class String
   end
 
   # call-seq:
-  #   str.nsub!(pattern, replacement, count) => str or nil
-  #   str.nsub!(pattern, count) { |match| ... } => str or nil
+  #   str.nsub!(pattern, replacement, count) => str or +nil+
+  #   str.nsub!(pattern, count) { |match| ... } => str or +nil+
   #
   # Performs the substitutions of #nsub in place, returning _str_, or +nil+ if
   # no substitutions were performed.

data/lib/nuggets/string/sub_with_md.rb

@@ -44,7 +44,7 @@ class String
   end
 
   # call-seq:
-  #   str.sub_with_md!(pattern) { |match_data| ... } => str or nil
+  #   str.sub_with_md!(pattern) { |match_data| ... } => str or +nil+
   #
   # Destructive version of #sub_with_md.
   def sub_with_md!(pattern, replacement = nil)
@@ -65,7 +65,7 @@ class String
   end
 
   # call-seq:
-  #   str.gsub_with_md!(pattern) { |match_data| ... } => str or nil
+  #   str.gsub_with_md!(pattern) { |match_data| ... } => str or +nil+
   #
   # Destructive version of #gsub_with_md.
   def gsub_with_md!(pattern, replacement = nil)

data/lib/nuggets/tempfile/open.rb

@@ -38,7 +38,7 @@ class Tempfile
     # If a block is given, it will be passed tempfile as an argument,
     # and the tempfile will automatically be closed when the block
     # terminates.  In this case, open() returns tempfile -- in contrast
-    # to the original implementation, which returns nil.
+    # to the original implementation, which returns +nil+.
     def open(*args)
       tempfile = new(*args)
 

data/lib/nuggets/uri/content_type_mixin.rb

@@ -33,7 +33,7 @@ module Nuggets
     module ContentTypeMixin
 
   # call-seq:
-  #   URI.content_type(uri) => aString or nil
+  #   URI.content_type(uri) => aString or +nil+
   #
   # Return the content type of +uri+, or +nil+ if not found.
   def content_type(uri)

data/lib/nuggets/uri/exist_mixin.rb

@@ -32,9 +32,9 @@ module Nuggets
     module ExistMixin
 
   # call-seq:
-  #   URI.exist?(uri) => true or false
+  #   URI.exist?(uri) => +true+ or +false+
   #
-  # Return +true+ if the named URI exists.
+  # Return +true+ if the URI +uri+ exists.
   def exist?(uri)
     open(uri.to_s)
     true

data/lib/nuggets/util/content_type.rb

@@ -67,7 +67,7 @@ module Util
     extend self
 
     # call-seq:
-    #   ContentType.of(path) => aString or nil
+    #   ContentType.of(path) => aString or +nil+
     #
     # Get the MIME-Type of the file living at +path+. Either by looking
     # directly into the file (requires FileMagic), or, assuming +path+

data/lib/nuggets/util/i18n.rb

@@ -32,68 +32,68 @@ module Util
   module I18n
 
     DIACRITICS = {
-      "À" => "A",  # LATIN CAPITAL LETTER A WITH GRAVE
-      "Á" => "A",  # LATIN CAPITAL LETTER A WITH ACUTE
-      "Â" => "A",  # LATIN CAPITAL LETTER A WITH CIRCUMFLEX
-      "Ã" => "A",  # LATIN CAPITAL LETTER A WITH TILDE
-      "Ä" => "AE", # LATIN CAPITAL LETTER A WITH DIAERESIS
-      "Å" => "A",  # LATIN CAPITAL LETTER A WITH RING ABOVE
-      "Æ" => "AE", # LATIN CAPITAL LETTER AE
-      "Ç" => "C",  # LATIN CAPITAL LETTER C WITH CEDILLA
-      "È" => "E",  # LATIN CAPITAL LETTER E WITH GRAVE
-      "É" => "E",  # LATIN CAPITAL LETTER E WITH ACUTE
-      "Ê" => "E",  # LATIN CAPITAL LETTER E WITH CIRCUMFLEX
-      "Ë" => "E",  # LATIN CAPITAL LETTER E WITH DIAERESIS
-      "Ì" => "I",  # LATIN CAPITAL LETTER I WITH GRAVE
-      "Í" => "I",  # LATIN CAPITAL LETTER I WITH ACUTE
-      "Î" => "I",  # LATIN CAPITAL LETTER I WITH CIRCUMFLEX
-      "Ï" => "I",  # LATIN CAPITAL LETTER I WITH DIAERESIS
-      "Ð" => "DH", # LATIN CAPITAL LETTER ETH
-      "Ñ" => "N",  # LATIN CAPITAL LETTER N WITH TILDE
-      "Ò" => "O",  # LATIN CAPITAL LETTER O WITH GRAVE
-      "Ó" => "O",  # LATIN CAPITAL LETTER O WITH ACUTE
-      "Ô" => "O",  # LATIN CAPITAL LETTER O WITH CIRCUMFLEX
-      "Õ" => "O",  # LATIN CAPITAL LETTER O WITH TILDE
-      "Ö" => "OE", # LATIN CAPITAL LETTER O WITH DIAERESIS
-      "Ø" => "O",  # LATIN CAPITAL LETTER O WITH STROKE
-      "Ù" => "U",  # LATIN CAPITAL LETTER U WITH GRAVE
-      "Ú" => "U",  # LATIN CAPITAL LETTER U WITH ACUTE
-      "Û" => "U",  # LATIN CAPITAL LETTER U WITH CIRCUMFLEX
-      "Ü" => "UE", # LATIN CAPITAL LETTER U WITH DIAERESIS
-      "Ý" => "Y",  # LATIN CAPITAL LETTER Y WITH ACUTE
-      "Þ" => "TH", # LATIN CAPITAL LETTER THORN
-      "ß" => "ss", # LATIN SMALL LETTER SHARP S
-      "à" => "a",  # LATIN SMALL LETTER A WITH GRAVE
-      "á" => "a",  # LATIN SMALL LETTER A WITH ACUTE
-      "â" => "a",  # LATIN SMALL LETTER A WITH CIRCUMFLEX
-      "ã" => "a",  # LATIN SMALL LETTER A WITH TILDE
-      "ä" => "ae", # LATIN SMALL LETTER A WITH DIAERESIS
-      "å" => "a",  # LATIN SMALL LETTER A WITH RING ABOVE
-      "æ" => "ae", # LATIN SMALL LETTER AE
-      "ç" => "c",  # LATIN SMALL LETTER C WITH CEDILLA
-      "è" => "e",  # LATIN SMALL LETTER E WITH GRAVE
-      "é" => "e",  # LATIN SMALL LETTER E WITH ACUTE
-      "ê" => "e",  # LATIN SMALL LETTER E WITH CIRCUMFLEX
-      "ë" => "e",  # LATIN SMALL LETTER E WITH DIAERESIS
-      "ì" => "i",  # LATIN SMALL LETTER I WITH GRAVE
-      "í" => "i",  # LATIN SMALL LETTER I WITH ACUTE
-      "î" => "i",  # LATIN SMALL LETTER I WITH CIRCUMFLEX
-      "ï" => "i",  # LATIN SMALL LETTER I WITH DIAERESIS
-      "ð" => "dh", # LATIN SMALL LETTER ETH
-      "ñ" => "n",  # LATIN SMALL LETTER N WITH TILDE
-      "ò" => "o",  # LATIN SMALL LETTER O WITH GRAVE
-      "ó" => "o",  # LATIN SMALL LETTER O WITH ACUTE
-      "ô" => "o",  # LATIN SMALL LETTER O WITH CIRCUMFLEX
-      "õ" => "o",  # LATIN SMALL LETTER O WITH TILDE
-      "ö" => "oe", # LATIN SMALL LETTER O WITH DIAERESIS
-      "ø" => "o",  # LATIN SMALL LETTER O WITH STROKE
-      "ù" => "u",  # LATIN SMALL LETTER U WITH GRAVE
-      "ú" => "u",  # LATIN SMALL LETTER U WITH ACUTE
-      "û" => "u",  # LATIN SMALL LETTER U WITH CIRCUMFLEX
-      "ü" => "ue", # LATIN SMALL LETTER U WITH DIAERESIS
-      "ý" => "y",  # LATIN SMALL LETTER Y WITH ACUTE
-      "þ" => "th", # LATIN SMALL LETTER THORN
-      "ÿ" => "y"   # LATIN SMALL LETTER Y WITH DIAERESIS
+      'À' => 'A',  # LATIN CAPITAL LETTER A WITH GRAVE
+      'Á' => 'A',  # LATIN CAPITAL LETTER A WITH ACUTE
+      'Â' => 'A',  # LATIN CAPITAL LETTER A WITH CIRCUMFLEX
+      'Ã' => 'A',  # LATIN CAPITAL LETTER A WITH TILDE
+      'Ä' => 'AE', # LATIN CAPITAL LETTER A WITH DIAERESIS
+      'Å' => 'A',  # LATIN CAPITAL LETTER A WITH RING ABOVE
+      'Æ' => 'AE', # LATIN CAPITAL LETTER AE
+      'Ç' => 'C',  # LATIN CAPITAL LETTER C WITH CEDILLA
+      'È' => 'E',  # LATIN CAPITAL LETTER E WITH GRAVE
+      'É' => 'E',  # LATIN CAPITAL LETTER E WITH ACUTE
+      'Ê' => 'E',  # LATIN CAPITAL LETTER E WITH CIRCUMFLEX
+      'Ë' => 'E',  # LATIN CAPITAL LETTER E WITH DIAERESIS
+      'Ì' => 'I',  # LATIN CAPITAL LETTER I WITH GRAVE
+      'Í' => 'I',  # LATIN CAPITAL LETTER I WITH ACUTE
+      'Î' => 'I',  # LATIN CAPITAL LETTER I WITH CIRCUMFLEX
+      'Ï' => 'I',  # LATIN CAPITAL LETTER I WITH DIAERESIS
+      'Ð' => 'DH', # LATIN CAPITAL LETTER ETH
+      'Ñ' => 'N',  # LATIN CAPITAL LETTER N WITH TILDE
+      'Ò' => 'O',  # LATIN CAPITAL LETTER O WITH GRAVE
+      'Ó' => 'O',  # LATIN CAPITAL LETTER O WITH ACUTE
+      'Ô' => 'O',  # LATIN CAPITAL LETTER O WITH CIRCUMFLEX
+      'Õ' => 'O',  # LATIN CAPITAL LETTER O WITH TILDE
+      'Ö' => 'OE', # LATIN CAPITAL LETTER O WITH DIAERESIS
+      'Ø' => 'O',  # LATIN CAPITAL LETTER O WITH STROKE
+      'Ù' => 'U',  # LATIN CAPITAL LETTER U WITH GRAVE
+      'Ú' => 'U',  # LATIN CAPITAL LETTER U WITH ACUTE
+      'Û' => 'U',  # LATIN CAPITAL LETTER U WITH CIRCUMFLEX
+      'Ü' => 'UE', # LATIN CAPITAL LETTER U WITH DIAERESIS
+      'Ý' => 'Y',  # LATIN CAPITAL LETTER Y WITH ACUTE
+      'Þ' => 'TH', # LATIN CAPITAL LETTER THORN
+      'ß' => 'ss', # LATIN SMALL LETTER SHARP S
+      'à' => 'a',  # LATIN SMALL LETTER A WITH GRAVE
+      'á' => 'a',  # LATIN SMALL LETTER A WITH ACUTE
+      'â' => 'a',  # LATIN SMALL LETTER A WITH CIRCUMFLEX
+      'ã' => 'a',  # LATIN SMALL LETTER A WITH TILDE
+      'ä' => 'ae', # LATIN SMALL LETTER A WITH DIAERESIS
+      'å' => 'a',  # LATIN SMALL LETTER A WITH RING ABOVE
+      'æ' => 'ae', # LATIN SMALL LETTER AE
+      'ç' => 'c',  # LATIN SMALL LETTER C WITH CEDILLA
+      'è' => 'e',  # LATIN SMALL LETTER E WITH GRAVE
+      'é' => 'e',  # LATIN SMALL LETTER E WITH ACUTE
+      'ê' => 'e',  # LATIN SMALL LETTER E WITH CIRCUMFLEX
+      'ë' => 'e',  # LATIN SMALL LETTER E WITH DIAERESIS
+      'ì' => 'i',  # LATIN SMALL LETTER I WITH GRAVE
+      'í' => 'i',  # LATIN SMALL LETTER I WITH ACUTE
+      'î' => 'i',  # LATIN SMALL LETTER I WITH CIRCUMFLEX
+      'ï' => 'i',  # LATIN SMALL LETTER I WITH DIAERESIS
+      'ð' => 'dh', # LATIN SMALL LETTER ETH
+      'ñ' => 'n',  # LATIN SMALL LETTER N WITH TILDE
+      'ò' => 'o',  # LATIN SMALL LETTER O WITH GRAVE
+      'ó' => 'o',  # LATIN SMALL LETTER O WITH ACUTE
+      'ô' => 'o',  # LATIN SMALL LETTER O WITH CIRCUMFLEX
+      'õ' => 'o',  # LATIN SMALL LETTER O WITH TILDE
+      'ö' => 'oe', # LATIN SMALL LETTER O WITH DIAERESIS
+      'ø' => 'o',  # LATIN SMALL LETTER O WITH STROKE
+      'ù' => 'u',  # LATIN SMALL LETTER U WITH GRAVE
+      'ú' => 'u',  # LATIN SMALL LETTER U WITH ACUTE
+      'û' => 'u',  # LATIN SMALL LETTER U WITH CIRCUMFLEX
+      'ü' => 'ue', # LATIN SMALL LETTER U WITH DIAERESIS
+      'ý' => 'y',  # LATIN SMALL LETTER Y WITH ACUTE
+      'þ' => 'th', # LATIN SMALL LETTER THORN
+      'ÿ' => 'y'   # LATIN SMALL LETTER Y WITH DIAERESIS
     }
 
   end
@@ -112,7 +112,7 @@ class String
   end
 
   # call-seq:
-  #   str.replace_diacritics! => str or nil
+  #   str.replace_diacritics! => str or +nil+
   #
   # Destructive version of #replace_diacritics.
   def replace_diacritics!