casual_support 1.0.0 → 2.0.0

data/benchmarks/time/to_ymd.rb

@@ -0,0 +1,12 @@
+require 'benchmark/inputs'
+require_relative '../../lib/casual_support'
+
+
+FORMAT = '%Y-%m-%d'
+
+Benchmark.inputs([Time.new(1999, 12, 31, 23, 59, 59)]) do |job|
+  job.report('Time#to_ymd'){|t| t.to_ymd }
+  job.report('Time#strftime'){|t| t.strftime('%Y-%m-%d') }
+  job.report('Time#strftime(CONST)'){|t| t.strftime(FORMAT) }
+  job.compare!
+end

data/casual_support.gemspec

@@ -9,8 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jonathan Hefner"]
   spec.email         = ["jonathan.hefner@gmail.com"]
 
-  spec.summary       = %q{Utility methods as core extensions.}
-  spec.description   = %q{Utility methods as extensions to Ruby core objects.  Stuff I want in Active Support.}
+  spec.summary       = %q{Utility extensions to core objects, a la Active Support}
   spec.homepage      = "https://github.com/jonathanhefner/casual_support"
   spec.license       = "MIT"
 
@@ -22,6 +21,8 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'activesupport', '>= 3.1', '< 5.1'
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 11.1"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "benchmark-inputs", "~> 1.0"
 end

data/lib/casual_support.rb

@@ -1,8 +1,8 @@
-require 'casual_support/version'
-require 'casual_support/date'
-require 'casual_support/enumerable'
-require 'casual_support/hash'
-require 'casual_support/integer'
-require 'casual_support/numeric'
-require 'casual_support/string'
-require 'casual_support/time'
+require_relative 'casual_support/version'
+require_relative 'casual_support/comparable'
+require_relative 'casual_support/date'
+require_relative 'casual_support/enumerable'
+require_relative 'casual_support/hash'
+require_relative 'casual_support/integer'
+require_relative 'casual_support/string'
+require_relative 'casual_support/time'

data/lib/casual_support/comparable.rb

@@ -0,0 +1,3 @@
+require_relative 'comparable/at_least'
+require_relative 'comparable/at_most'
+require_relative 'comparable/clamp'

data/lib/casual_support/comparable/at_least.rb

@@ -0,0 +1,11 @@
+module Comparable
+
+  # Enforces a lower bound for the value.
+  #
+  # @param [Comparable] limit lower bound
+  # @return [Comparable] value constrained by the lower bound
+  def at_least(limit)
+    self < limit ? limit : self
+  end
+
+end

data/lib/casual_support/comparable/at_most.rb

@@ -0,0 +1,13 @@
+module Comparable
+
+  # Enforces an upper bound for the value.
+  #
+  # @param [Comparable] limit upper bound
+  # @return [Comparable] value constrained by the upper bound
+  def at_most(limit)
+    self > limit ? limit : self
+  end
+
+  alias_method :cap, :at_most
+
+end

data/lib/casual_support/comparable/clamp.rb

@@ -0,0 +1,16 @@
+module Comparable
+
+  # Clamps the value to a closed interval.
+  #
+  # Also see https://bugs.ruby-lang.org/issues/10594
+  #
+  # @param [Comparable] low lower bound
+  # @param [Comparable] high upper bound
+  # @return [Comparable] value constrained to the bounds
+  def clamp(low, high)
+    return low if self < low
+    return high if self > high
+    self
+  end
+
+end

data/lib/casual_support/date.rb

@@ -1 +1 @@
-require 'casual_support/date/to_ymd'
+require_relative 'date/to_ymd'

data/lib/casual_support/date/to_ymd.rb

@@ -3,7 +3,7 @@ require 'date'
 class Date
 
   # Formats date as "YYYY-MM-DD" (e.g. "1999-12-31").  Shortcut for
-  # +strftime("%Y-%m-%d")+.
+  # <code>strftime("%Y-%m-%d")</code>.
   #
   # @return [String] the date formatted as "YYYY-MM-DD"
   def to_ymd

data/lib/casual_support/enumerable.rb

@@ -1,2 +1,2 @@
-require 'casual_support/enumerable/duplicates'
-require 'casual_support/enumerable/index_to'
+require_relative 'enumerable/duplicates'
+require_relative 'enumerable/index_to'

data/lib/casual_support/enumerable/index_to.rb

@@ -1,4 +1,4 @@
-require 'casual_support/hash/setbang'
+require_relative '../hash/putbang'
 
 module Enumerable
 
@@ -10,7 +10,7 @@ module Enumerable
   # @yieldreturn value to associate with the +elem+ key
   # @return [Hash] hash with the +Enumerable+'s elements as keys
   def index_to()
-    self.reduce({}){|h, k| h.set!(k, (yield k)) }
+    self.reduce({}){|h, k| h.put!(k, (yield k)) }
   end
 
 end

data/lib/casual_support/hash.rb

@@ -1 +1 @@
-require 'casual_support/hash/setbang'
+require_relative 'hash/putbang'

data/lib/casual_support/hash/putbang.rb

@@ -0,0 +1,15 @@
+class Hash
+
+  # Associates a key-value a la +Hash#[]=+, but returns the modified
+  # Hash instead of the value.  Useful with +#reduce+, and faster than
+  # +Hash#merge!+.
+  #
+  # @param key
+  # @param value
+  # @return [Hash] the modified hash
+  def put!(key, value)
+    self[key] = value
+    self
+  end
+
+end

data/lib/casual_support/integer.rb

@@ -1 +1 @@
-require 'casual_support/integer/to_hex'
+require_relative 'integer/to_hex'

data/lib/casual_support/integer/to_hex.rb

@@ -5,16 +5,10 @@ class Integer
   # width, the string will be returned unaltered (without padding or
   # truncation).
   #
-  # Without the need for zero-padding, this method is ~7% slower than
-  # just +to_s(16)+.  However, when zero-padding is required, it is
-  # ~230% faster than +sprintf("%0#{width}x", self)+, and ~30% faster
-  # than +sprintf(FIXED_FORMAT_STRING, self)+.
-  #
   # @param [Integer] width desired width of the zero-padded string
   # @return [String] hexadecimal string
-  def to_hex(width = nil)
-    h = self.to_s(16)
-    width ? h.rjust(width, '0'.freeze) : h
+  def to_hex(width = 0)
+    width > 1 ? self.to_s(16).rjust(width, '0'.freeze) : self.to_s(16)
   end
 
 end

data/lib/casual_support/string.rb

@@ -1,4 +1,13 @@
-require 'casual_support/string/before_after'
-require 'casual_support/string/drop'
-require 'casual_support/string/first_last'
-require 'casual_support/string/from_to'
+require_relative 'string/after'
+require_relative 'string/after_last'
+require_relative 'string/before'
+require_relative 'string/before_last'
+require_relative 'string/between'
+require_relative 'string/drop'
+require_relative 'string/first'
+require_relative 'string/from'
+require_relative 'string/last'
+require_relative 'string/lchomp'
+require_relative 'string/prefix'
+require_relative 'string/suffix'
+require_relative 'string/to'

data/lib/casual_support/string/after.rb

@@ -0,0 +1,15 @@
+class String
+
+  # Searches for the first occurrence of a delimiter, and returns the
+  # portion of the string after that.  If the delimiter is not found,
+  # returns nil.  Equivalent to <code>split(delim, 2)[1]</code> for
+  # non-empty delimiters.
+  #
+  # @param [String] delim delimiter to search for
+  # @return [String] portion of the string after the first +delim+
+  def after(delim)
+    i = self.index(delim)
+    i && self[i + delim.length, self.length]
+  end
+
+end

data/lib/casual_support/string/after_last.rb

@@ -0,0 +1,14 @@
+class String
+
+  # Searches for the last occurrence of a delimiter, and returns the
+  # portion of the string after that.  If the delimiter is not found,
+  # returns nil.  Equivalent to <code>split(delim, -1).drop(1)[-1]</code>.
+  #
+  # @param [String] delim delimiter to search for
+  # @return [String] portion of the string after the last +delim+
+  def after_last(delim)
+    i = self.rindex(delim)
+    i && self[i + delim.length, self.length]
+  end
+
+end

data/lib/casual_support/string/before.rb

@@ -0,0 +1,14 @@
+class String
+
+  # Searches for the first occurrence of a delimiter, and returns the
+  # portion of the string before that.  If the delimiter is not found,
+  # returns a copy of the original string.  Equivalent to
+  # <code>split(delim, 2)[0]</code> for non-empty delimiters.
+  #
+  # @param [String] delim delimiter to search for
+  # @return [String] portion of the string before the first +delim+
+  def before(delim)
+    self[0, self.index(delim) || self.length]
+  end
+
+end

data/lib/casual_support/string/before_last.rb

@@ -0,0 +1,15 @@
+class String
+
+  # Searches for the last occurrence of a delimiter, and returns the
+  # portion of the string before that.  If the delimiter is not found,
+  # returns a copy of the original string.  Equivalent to
+  # <code>split(delim, -1)[0..-2].join(delim)</code> for existent
+  # delimiters.
+  #
+  # @param [String] delim delimiter to search for
+  # @return [String] portion of the string before the last +delim+
+  def before_last(delim)
+    self[0, self.rindex(delim) || self.length]
+  end
+
+end

data/lib/casual_support/string/between.rb

@@ -0,0 +1,16 @@
+class String
+  
+  # Returns the portion of the string between the first occurrences of
+  # an opening and a closing delimiter.  If either delimiter is not
+  # found, returns nil.
+  #
+  # @param [String] open opening delimiter
+  # @param [String] close closing delimiter
+  # @return [String] portion of the string between the delimiters
+  def between(open, close)
+    i = self.index(open)
+    j = self.index(close, i + 1) if i
+    j && self[i + 1, j - i - 1]
+  end
+
+end

data/lib/casual_support/string/drop.rb

@@ -7,7 +7,8 @@ class String
   # @param [Integer] n number of characters to drop
   # @return [String] string of remaining characters
   def drop(n)
-    self[n.constrain(0, self.length), self.length]
+    return self.dup if n <= 0
+    self[n, self.length] || ''
   end
 
 end

data/lib/casual_support/string/first.rb

@@ -0,0 +1,17 @@
+class String
+
+  # This replaces Active Support's +String#first+, but it returns an
+  # empty string when given a negative +limit+ argument, whereas Active
+  # Support's +String#first+ removes +limit.abs+ characters from the
+  # end of the string.  Returning an empty string makes more sense if
+  # you interpret +first+ as "keep upto +limit+ characters."  At most, a
+  # negative +limit+ should *keep* that many characters from the end of
+  # the string, rather than *remove* that many characters (but returning
+  # an empty string is a good conservative choice).
+  #
+  # This method is also faster.
+  def first(limit = 1)
+    self[0, limit] || ''
+  end
+
+end

data/lib/casual_support/string/from.rb

@@ -0,0 +1,8 @@
+class String
+
+  # This replaces Active Support's +String#from+.  It is faster.
+  def from(position)
+    self[position, length]
+  end
+
+end

data/lib/casual_support/string/last.rb

@@ -0,0 +1,18 @@
+class String
+
+  # This replaces Active Support's +String#last+, but it returns an
+  # empty string when given a negative +limit+ argument, whereas Active
+  # Support's +String#last+ removes +limit.abs+ characters from the
+  # beginning of the string.  Returning an empty string makes more sense
+  # if you interpret +last+ as "keep upto +limit+ characters."  At most,
+  # a negative +limit+ should *keep* that many characters from the
+  # beginning of the string, rather than *remove* that many characters
+  # (but returning an empty string is a good conservative choice).  Also
+  # see +String#first+.
+  #
+  # This method is also faster.
+  def last(limit = 1)
+    limit < 0 ? '' : (self[-limit, limit] || self.dup)
+  end
+
+end

data/lib/casual_support/string/lchomp.rb

@@ -0,0 +1,16 @@
+class String
+
+  # Removes the beginning of the string if that portion matches the
+  # argument.  Otherwise returns a duplicate of the string.  Like
+  # String#chomp, but operates on the left side (beginning) of the
+  # string.
+  #
+  # Also see https://bugs.ruby-lang.org/issues/10574
+  #
+  # @param [String] head substring to match and remove
+  # @return [String] chomped string
+  def lchomp(head)
+    self.start_with?(head) ? self[head.length, self.length] : self.dup
+  end
+
+end

data/lib/casual_support/string/prefix.rb

@@ -0,0 +1,13 @@
+class String
+
+  # Prepends a prefix to the string if the string does not already start
+  # with that prefix.  Otherwise returns a duplicate of the string.
+  # Equivalent to <code>gsub(/^(?!fix)/, "fix")</code>.
+  #
+  # @param [String] fix prefix to prepend
+  # @return [String] prefixed string
+  def prefix(fix)
+    self.start_with?(fix) ? self.dup : "#{fix}#{self}"
+  end
+
+end

data/lib/casual_support/string/suffix.rb

@@ -0,0 +1,13 @@
+class String
+
+  # Appends a suffix to the string if the string does not already end
+  # with that suffix.  Otherwise returns a duplicate of the string.
+  # Equivalent to <code>gsub(/(?<!fix)$/, "fix")</code>.
+  #
+  # @param [String] fix suffix to append
+  # @return [String] suffixed string
+  def suffix(fix)
+    self.end_with?(fix) ? self.dup : "#{self}#{fix}"
+  end
+
+end

data/lib/casual_support/string/to.rb

@@ -0,0 +1,9 @@
+class String
+
+  # This replaces Active Support's +String#to+.  It is faster.
+  def to(position)
+    position += self.length if position < 0
+    self[0, position + 1] || ''
+  end
+
+end

data/lib/casual_support/time.rb

@@ -1 +1,2 @@
-require 'casual_support/time/ymd_hms'
+require_relative 'time/to_hms'
+require_relative 'time/to_ymd'

data/lib/casual_support/time/to_hms.rb

@@ -0,0 +1,14 @@
+class Time
+
+  # Formats time as "HH:MM:SS" (e.g. "23:59:59").  Equivalent to
+  # <code>strftime("%H:%M:%S")</code>, but faster.
+  #
+  # @return [String] the time formatted as "HH:MM:SS"
+  def to_hms
+    # Date#strftime appears to be **much** faster than Time#strftime
+    # (nearly 3x faster!).  If Time#strftime becomes optimized to that
+    # level in the future, it should be used instead of sprintf.
+    sprintf('%02d:%02d:%02d'.freeze, hour, min, sec)
+  end
+
+end

data/lib/casual_support/time/to_ymd.rb

@@ -0,0 +1,14 @@
+class Time
+
+  # Formats time as "YYYY-MM-DD" (e.g. "1999-12-31").  Equivalent to
+  # <code>strftime("%Y-%m-%d")</code>, but faster.
+  #
+  # @return [String] the time formatted as "YYYY-MM-DD"
+  def to_ymd
+    # Date#strftime appears to be **much** faster than Time#strftime
+    # (nearly 3x faster!).  If Time#strftime becomes optimized to that
+    # level in the future, it should be used instead of sprintf.
+    sprintf('%04d-%02d-%02d'.freeze, year, month, day)
+  end
+
+end