casual_support 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a1a0d4b85acc5ebea33e00189e06584cdba7c1d
-  data.tar.gz: f7622e76c1255b6058499d9fa96c5cfa23ba101e
+  metadata.gz: 312ae68b392788d7e86e0ca1c60cac0342f51b29
+  data.tar.gz: 0b734117b2ff24d89fd7a26d53256798ab946dba
 SHA512:
-  metadata.gz: 4938a0152fa5a60b49be69f3e76ac26a96e988478a789933de3d1ca999e05d38220d0b71f46e8f5909c230c264837b5053e84f405ad7a7bb3c8d11e13c7a87cd
-  data.tar.gz: ef2a424c9e9ef9bfb2039d7c3e02f2c736fffc9dd5fa274d8c231d6173ee29765e351d5f3e7df36852c843855893fcf3e47ec3d56475f4d0698504744db00529
+  metadata.gz: 4e993b4d89958ae079329c3311ce4505e04ee58ef3986eb44c6f347193903efd9f04e060116c161da29871625d0b131c329dcd6c0bc0b6388728d0ff0f1709ba
+  data.tar.gz: e175c89da241db40ef6b88a376b23dcd2ceeb5a6847f40dc88a1de70b5abe39808a02155fb9b1266101e8c6815f9c7b1a228d5d268e277ab06beac3a7d55bb60

data/README.md

@@ -3,12 +3,12 @@
 Utility methods as extensions to Ruby core objects, a la Active Support.
 
 Also a nod to the epic [Facets] library, which has a vast quantity and
-wide variety of utility functions.  casual_support distinguishes itself
-in a few ways:
+wide variety of utility functions.  *casual_support* distinguishes
+itself in a few ways:
 
 - Focus on fast implementations.  See the benchmarks directory for
   performance comparisons with typical and alternative implementations.
-- Low memory footprint without requiring cherry-picking.  Cherry-picking
+- Low memory footprint without required cherry-picking.  Cherry-picking
   is still possible though!
 - Intended to be used alongside Active Support.  Does not clash with
   Active Support methods, and overrides only a few to provide more
@@ -19,44 +19,60 @@ in a few ways:
 
 ## Utility Methods
 
-- Comparable
-  - [at_least](http://www.rubydoc.info/gems/casual_support/Comparable%3Aat_least)
-  - [at_most](http://www.rubydoc.info/gems/casual_support/Comparable%3Aat_most)
-  - [clamp](http://www.rubydoc.info/gems/casual_support/Comparable%3Aclamp)
-- Date
-  - [to_ymd](http://www.rubydoc.info/gems/casual_support/Date%3Ato_ymd)
-- Enumerable
-  - [duplicates](http://www.rubydoc.info/gems/casual_support/Enumerable%3Aduplicates)
-  - [index_to](http://www.rubydoc.info/gems/casual_support/Enumerable%3Aindex_to)
-- Hash
-  - [put!](http://www.rubydoc.info/gems/casual_support/Hash%3Aput%21)
-- Integer
-  - [to_hex](http://www.rubydoc.info/gems/casual_support/Integer%3Ato_hex)
-- String
-  - [after](http://www.rubydoc.info/gems/casual_support/String%3Aafter)
-  - [after_last](http://www.rubydoc.info/gems/casual_support/String%3Aafter_last)
-  - [before](http://www.rubydoc.info/gems/casual_support/String%3Abefore)
-  - [before_last](http://www.rubydoc.info/gems/casual_support/String%3Abefore_last)
-  - [between](http://www.rubydoc.info/gems/casual_support/String%3Abetween)
-  - [drop](http://www.rubydoc.info/gems/casual_support/String%3Adrop)
-  - [first](http://www.rubydoc.info/gems/casual_support/String%3Afirst)
-  - [from](http://www.rubydoc.info/gems/casual_support/String%3Afrom)
-  - [last](http://www.rubydoc.info/gems/casual_support/String%3Alast)
-  - [lchomp](http://www.rubydoc.info/gems/casual_support/String%3Alchomp)
-  - [prefix](http://www.rubydoc.info/gems/casual_support/String%3Aprefix)
-  - [suffix](http://www.rubydoc.info/gems/casual_support/String%3Asuffix)
-  - [to](http://www.rubydoc.info/gems/casual_support/String%3Ato)
-- Time
-  - [to_hms](http://www.rubydoc.info/gems/casual_support/Time%3Ato_hms)
-  - [to_ymd](http://www.rubydoc.info/gems/casual_support/Time%3Ato_ymd)
+- Boolean
+  - [#to_z](http://www.rubydoc.info/gems/casual_support/TrueClass:to_z)
+- [Comparable](http://www.rubydoc.info/gems/casual_support/Comparable)
+  - [#at_least](http://www.rubydoc.info/gems/casual_support/Comparable:at_least)
+  - [#at_most](http://www.rubydoc.info/gems/casual_support/Comparable:at_most)
+- [Date](http://www.rubydoc.info/gems/casual_support/Date)
+  - [#to_ymd](http://www.rubydoc.info/gems/casual_support/Date:to_ymd)
+- [Enumerable](http://www.rubydoc.info/gems/casual_support/Enumerable)
+  - [#duplicates](http://www.rubydoc.info/gems/casual_support/Enumerable:duplicates)
+  - [#index_to](http://www.rubydoc.info/gems/casual_support/Enumerable:index_to)
+- [Hash](http://www.rubydoc.info/gems/casual_support/Hash)
+  - [#displace](http://www.rubydoc.info/gems/casual_support/Hash:displace)
+  - [#put!](http://www.rubydoc.info/gems/casual_support/Hash:put%21)
+- [Integer](http://www.rubydoc.info/gems/casual_support/Integer)
+  - [#to_hex](http://www.rubydoc.info/gems/casual_support/Integer:to_hex)
+- [Numeric](http://www.rubydoc.info/gems/casual_support/Numeric)
+  - [#sign](http://www.rubydoc.info/gems/casual_support/Numeric:sign)
+- [String](http://www.rubydoc.info/gems/casual_support/String)
+  - [#after](http://www.rubydoc.info/gems/casual_support/String:after)
+  - [#after_last](http://www.rubydoc.info/gems/casual_support/String:after_last)
+  - [#before](http://www.rubydoc.info/gems/casual_support/String:before)
+  - [#before_last](http://www.rubydoc.info/gems/casual_support/String:before_last)
+  - [#between](http://www.rubydoc.info/gems/casual_support/String:between)
+  - [#drop](http://www.rubydoc.info/gems/casual_support/String:drop)
+  - [#first](http://www.rubydoc.info/gems/casual_support/String:first)
+  - [#from](http://www.rubydoc.info/gems/casual_support/String:from)
+  - [#last](http://www.rubydoc.info/gems/casual_support/String:last)
+  - [#prefix](http://www.rubydoc.info/gems/casual_support/String:prefix)
+  - [#suffix](http://www.rubydoc.info/gems/casual_support/String:suffix)
+  - [#to](http://www.rubydoc.info/gems/casual_support/String:to)
+- [Struct](http://www.rubydoc.info/gems/casual_support/Struct)
+  - [#assign_attributes](http://www.rubydoc.info/gems/casual_support/Struct:assign_attributes)
+  - [.from_h](http://www.rubydoc.info/gems/casual_support/Struct.from_h)
+- [Time](http://www.rubydoc.info/gems/casual_support/Time)
+  - [#to_hms](http://www.rubydoc.info/gems/casual_support/Time:to_hms)
+  - [#to_ymd](http://www.rubydoc.info/gems/casual_support/Time:to_ymd)
 
 
 ## Installation
 
-    $ gem install casual_support
+Install from [Ruby Gems](https://rubygems.org/gems/casual_support):
 
+```bash
+$ gem install casual_support
+```
 
-## Development
+Then require in your Ruby script:
+
+```ruby
+require "casual_support"
+```
+
+
+## Contributing
 
 Run `rake test` to run the tests.  You can also run `rake irb` for an
 interactive prompt that pre-loads the project code.
@@ -64,4 +80,4 @@ interactive prompt that pre-loads the project code.
 
 ## License
 
-[MIT License](http://opensource.org/licenses/MIT)
+[MIT License](https://opensource.org/licenses/MIT)

data/benchmarks/struct/assign_attributes.rb

@@ -0,0 +1,69 @@
+require 'benchmark/inputs'
+require_relative '../../lib/casual_support'
+
+
+class Struct
+
+  def assign_attributes_alt1(new_attributes)
+    self.members.each do |m|
+      if new_attributes.key?(m)
+        self[m] = new_attributes[m]
+      elsif new_attributes.key?(m.to_s)
+        self[m] = new_attributes[m.to_s]
+      end
+    end
+    self
+  end
+
+  def assign_attributes_alt2(new_attributes)
+    self.members.each do |m|
+      if new_attributes.key?(m)
+        self[m] = new_attributes[m]
+      elsif new_attributes.key?(m_s = m.to_s)
+        self[m] = new_attributes[m_s]
+      end
+    end
+    self
+  end
+
+  def assign_attributes_alt3(new_attributes)
+    new_attributes.each do |k, v|
+      self[k.to_sym] = v if self.members.include?(k.to_sym)
+    end
+    self
+  end
+
+  def assign_attributes_alt4(new_attributes)
+    new_attributes.each do |k, v|
+      m = k.to_sym
+      self[m] = v if self.members.include?(m)
+    end
+    self
+  end
+
+end
+
+
+Subject = Struct.new(:attr1, :attr2, :attr3)
+subject = Subject.new(1, 2, 3)
+
+input_attributes = [
+  { attr1: 11 },
+  { attr1: 111, attr2: 222 },
+  { attr1: 1111, attr2: 2222, attr3: 3333 },
+  { attr1: 11111, attr2: 22222, attr3: 33333, attr9: 99999 },
+  { "attr1" => 11 },
+  { "attr1" => 111, "attr2" => 222 },
+  { "attr1" => 1111, "attr2" => 2222, "attr3" => 3333 },
+  { "attr1" => 11111, "attr2" => 22222, "attr3" => 33333, "attr9" => 99999 },
+]
+
+
+Benchmark.inputs(input_attributes) do |job|
+  job.report('Struct#assign_attributes'){|attrs| subject.assign_attributes(attrs) }
+  job.report('Struct#assign_attributes_alt1'){|attrs| subject.assign_attributes_alt1(attrs) }
+  job.report('Struct#assign_attributes_alt2'){|attrs| subject.assign_attributes_alt2(attrs) }
+  job.report('Struct#assign_attributes_alt3'){|attrs| subject.assign_attributes_alt3(attrs) }
+  job.report('Struct#assign_attributes_alt4'){|attrs| subject.assign_attributes_alt4(attrs) }
+  job.compare!
+end

data/lib/casual_support.rb

@@ -1,8 +1,11 @@
 require_relative 'casual_support/version'
+require_relative 'casual_support/boolean'
 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/numeric'
 require_relative 'casual_support/string'
+require_relative 'casual_support/struct'
 require_relative 'casual_support/time'

data/lib/casual_support/boolean.rb

@@ -0,0 +1 @@
+require_relative 'boolean/to_z'

data/lib/casual_support/boolean/to_z.rb

@@ -0,0 +1,22 @@
+class FalseClass
+
+  # Returns 0 if +false+, 1 if +true+.
+  #
+  # @return [Integer]
+  def to_z
+    0
+  end
+
+end
+
+
+class TrueClass
+
+  # Returns 0 if +false+, 1 if +true+.
+  #
+  # @return [Integer]
+  def to_z
+    1
+  end
+
+end

data/lib/casual_support/comparable.rb

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

data/lib/casual_support/comparable/at_least.rb

@@ -2,8 +2,12 @@ module Comparable
 
   # Enforces a lower bound for the value.
   #
-  # @param [Comparable] limit lower bound
-  # @return [Comparable] value constrained by the lower bound
+  # @example
+  #   -10.at_least(0)  # == 0
+  #   99.at_least(0)   # == 99
+  #
+  # @param limit [Comparable]
+  # @return [Comparable]
   def at_least(limit)
     self < limit ? limit : self
   end

data/lib/casual_support/comparable/at_most.rb

@@ -2,8 +2,12 @@ module Comparable
 
   # Enforces an upper bound for the value.
   #
-  # @param [Comparable] limit upper bound
-  # @return [Comparable] value constrained by the upper bound
+  # @example
+  #   120.at_most(100)  # == 100
+  #   90.at_most(100)   # == 90
+  #
+  # @param limit [Comparable]
+  # @return [Comparable]
   def at_most(limit)
     self > limit ? limit : self
   end

data/lib/casual_support/date/to_ymd.rb

@@ -2,14 +2,17 @@ require 'date'
 
 class Date
 
-  # Formats date as "YYYY-MM-DD" (e.g. "1999-12-31").  Shortcut for
-  # <code>strftime("%Y-%m-%d")</code>.
+  # Formats the Date as "YYYY-MM-DD".  Equivalent to
+  # +strftime("%Y-%m-%d")+.
   #
-  # @return [String] the date formatted as "YYYY-MM-DD"
+  # @example
+  #   Date.new(1999, 12, 31).to_ymd  # == "1999-12-31"
+  #
+  # @return [String]
   def to_ymd
     # Date#strftime appears to be **much** faster than Time#strftime
-    # (nearly 3x faster!).  Thus it used here, unlike Time#to_ymd which
-    # uses sprintf.
+    # (nearly 3x faster!).  Thus it is used here, unlike Time#to_ymd
+    # which uses sprintf.
     self.strftime('%Y-%m-%d'.freeze)
   end
 

data/lib/casual_support/enumerable/duplicates.rb

@@ -1,24 +1,15 @@
 module Enumerable
 
   # Returns the first duplicate of each element, preserving order of
-  # appearance.  If a block is given, it will use the return
-  # value of the block for element comparison.
+  # appearance.
   #
-  # Examples:
-  #   %w[a a b c d c b a].duplicates == %w[a c b]
-  #   %w[A a B b].duplicates(&:upcase) == %w[a b]
+  # @example
+  #   %w[a a b c c b a d].duplicates  # == ["a", "c", "b"]
   #
-  # @yield [elem] computes an indentifying value
-  # @yieldparam elem element from the +Enumerable+
-  # @yieldreturn value used for duplicate comparison
-  # @return [Enumerable] duplicate elements of the +Enumerable+
+  # @return [Enumerable]
   def duplicates
     seen = Hash.new(0)
-    if block_given?
-      self.select{|elem| (seen[yield(elem)] += 1) == 2 }
-    else
-      self.select{|elem| (seen[elem] += 1) == 2 }
-    end
+    self.select{|element| (seen[element] += 1) == 2 }
   end
 
 end

data/lib/casual_support/enumerable/index_to.rb

@@ -2,13 +2,15 @@ require_relative '../hash/putbang'
 
 module Enumerable
 
-  # Converts an +Enumerable+ into a +Hash+ by using its elements as keys
-  # and extracting values from each.
+  # Converts the Enumerable into a Hash, using its elements as keys and
+  # using the given block to compute an associated value for each key.
   #
-  # @yield [elem] extracts a value
-  # @yieldparam elem element from the +Enumerable+
-  # @yieldreturn value to associate with the +elem+ key
-  # @return [Hash] hash with the +Enumerable+'s elements as keys
+  # @example
+  #   cache = id_list.index_to{|id| find_by_id(id) }
+  #
+  # @yieldparam element ['E] element from the Enumerable
+  # @yieldreturn ['V] value to associate with the +element+ key
+  # @return [Hash{'E => 'V}]
   def index_to()
     self.reduce({}){|h, k| h.put!(k, (yield k)) }
   end

data/lib/casual_support/hash.rb

@@ -1 +1,2 @@
+require_relative 'hash/displace'
 require_relative 'hash/putbang'

data/lib/casual_support/hash/displace.rb

@@ -0,0 +1,26 @@
+class Hash
+
+  # Associates a key with a value, and returns the key's previously
+  # associated value.  If the key had no previously associated value,
+  # returns +Hash#default+.
+  #
+  # @example
+  #   visited = { "id1" => true, "id2" => false }
+  #
+  #   visited.displace("id1", true)  # == true
+  #   visited                        # == { "id1" => true, "id2" => false }
+  #   visited.displace("id2", true)  # == false
+  #   visited                        # == { "id1" => true, "id2" => true }
+  #   visited.displace("id3", true)  # == nil
+  #   visited                        # == { "id1" => true, "id2" => true, "id3" => true }
+  #
+  # @param key
+  # @param value
+  # @return [Hash]
+  def displace(key, value)
+    old_value = self[key]
+    self[key] = value
+    old_value
+  end
+
+end

data/lib/casual_support/hash/putbang.rb

@@ -1,12 +1,17 @@
 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!+.
+  # Associates a key with a value.  Similar to +Hash#[]=+, but returns
+  # the Hash instead of the value.  Faster than +Hash#merge!+ for
+  # singular values in a loop.
+  #
+  # @example
+  #   cache = id_list.reduce({}) do |hash, id|
+  #     hash.put!(id, find_by_id(id))
+  #   end
   #
   # @param key
   # @param value
-  # @return [Hash] the modified hash
+  # @return [Hash]
   def put!(key, value)
     self[key] = value
     self

data/lib/casual_support/integer/to_hex.rb

@@ -1,12 +1,17 @@
 class Integer
 
-  # Converts integer to a zero-padded lower-case hexadecimal string.
+  # Formats the Integer as a zero-padded lower-case hexadecimal string.
   # If the length of the raw hexadecimal string exceeds the desired
-  # width, the string will be returned unaltered (without padding or
+  # width, the string will be returned as-is (without padding or
   # truncation).
   #
-  # @param [Integer] width desired width of the zero-padded string
-  # @return [String] hexadecimal string
+  # @example
+  #   250.to_hex     # == "fa"
+  #   250.to_hex(4)  # == "00fa"
+  #   250.to_hex(1)  # == "fa"
+  #
+  # @param width [Integer]
+  # @return [String]
   def to_hex(width = 0)
     width > 1 ? self.to_s(16).rjust(width, '0'.freeze) : self.to_s(16)
   end

data/lib/casual_support/numeric.rb

@@ -0,0 +1 @@
+require_relative 'numeric/sign'

data/lib/casual_support/numeric/sign.rb

@@ -0,0 +1,15 @@
+class Numeric
+
+  # Returns the sign of the number expressed as +-1+, +0+, or +1+.
+  #
+  # @example
+  #   -4.sign  # == -1
+  #   0.sign   # == 0
+  #   16.sign  # == 1
+  #
+  # @return [Integer]
+  def sign
+    self <=> 0
+  end
+
+end

data/lib/casual_support/string.rb

@@ -7,7 +7,6 @@ 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

@@ -1,15 +1,20 @@
 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.
+  # portion of the String after that.  If the delimiter is not found,
+  # returns nil.  Equivalent to +split(delimiter, 2)[1]+ 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]
+  # @example
+  #  "http://www.example.com".after("://")  # == "www.example.com"
+  #  "http://www.example.com".after("?")    # == nil
+  #  "http://www.example.com".after("")     # == "http://www.example.com"
+  #
+  # @param delimiter [String]
+  # @return [String, nil]
+  def after(delimiter)
+    i = self.index(delimiter)
+    i && self[i + delimiter.length, self.length]
   end
 
 end

data/lib/casual_support/string/after_last.rb

@@ -1,14 +1,20 @@
 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>.
+  # portion of the String after that.  If the delimiter is not found,
+  # returns nil.  Equivalent to +split(delimiter, -1).drop(1)[-1]+ for
+  # non-empty delimiters.
   #
-  # @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]
+  # @example
+  #   "/path/to/file".after_last("/")  # == "file"
+  #   "/path/to/file".after_last(".")  # == nil
+  #   "/path/to/file".after_last("")   # == ""
+  #
+  # @param delimiter [String]
+  # @return [String, nil]
+  def after_last(delimiter)
+    i = self.rindex(delimiter)
+    i && self[i + delimiter.length, self.length]
   end
 
 end

data/lib/casual_support/string/before.rb

@@ -1,14 +1,19 @@
 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.
+  # portion of the String before that.  If the delimiter is not found,
+  # returns a copy of the original String.  Equivalent to
+  # +split(delimiter, 2)[0]+ 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]
+  # @example
+  #  "http://www.example.com".before("://")  # == "http"
+  #  "http://www.example.com".before("?")    # == "http://www.example.com"
+  #  "http://www.example.com".before("")     # == ""
+  #
+  # @param delimiter [String]
+  # @return [String]
+  def before(delimiter)
+    self[0, self.index(delimiter) || self.length]
   end
 
 end

data/lib/casual_support/string/before_last.rb

@@ -1,15 +1,20 @@
 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
+  # portion of the String before that.  If the delimiter is not found,
+  # returns a copy of the original String.  Equivalent to
+  # +split(delimiter, -1)[0..-2].join(delimiter)+ 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]
+  # @example
+  #   "/path/to/file".before_last("/")  # == "/path/to"
+  #   "/path/to/file".before_last(".")  # == "/path/to/file"
+  #   "/path/to/file".before_last("")   # == "/path/to/file"
+  #
+  # @param delimiter [String]
+  # @return [String]
+  def before_last(delimiter)
+    self[0, self.rindex(delimiter) || self.length]
   end
 
 end

data/lib/casual_support/string/between.rb

@@ -1,16 +1,23 @@
 class String
-  
-  # Returns the portion of the string between the first occurrences of
+
+  # 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
+  # @example
+  #   "i <b><3</b> ruby".between("<b>", "</b>")  # == "<3"
+  #   "i <b><3<b> ruby".between("<b>", "</b>")   # == nil
+  #
+  # @param open [String]
+  # @param close [String]
+  # @return [String, nil]
   def between(open, close)
     i = self.index(open)
-    j = self.index(close, i + 1) if i
-    j && self[i + 1, j - i - 1]
+    if i
+      i += open.length
+      j = self.index(close, i)
+      self[i, j - i] if j
+    end
   end
 
 end

data/lib/casual_support/string/drop.rb

@@ -1,11 +1,17 @@
 class String
 
-  # Drops characters from the beginning of a string, and returns the
+  # Drops characters from the beginning of the String, and returns the
   # remainder.  If the number of characters to drop is greater than the
-  # length of the string, an empty string is returned.
+  # length of the String, an empty string is returned.
   #
-  # @param [Integer] n number of characters to drop
-  # @return [String] string of remaining characters
+  # @example
+  #   "abcdef".drop(0)  # == "abcdef"
+  #   "abcdef".drop(3)  # == "def"
+  #   "abcdef".drop(6)  # == ""
+  #   "abcdef".drop(7)  # == ""
+  #
+  # @param n [Integer]
+  # @return [String]
   def drop(n)
     return self.dup if n <= 0
     self[n, self.length] || ''

data/lib/casual_support/string/first.rb

@@ -1,15 +1,31 @@
+require 'active_support/core_ext/string/access'
+
 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).
+  remove_method :first
+
+  # Returns the first +limit+ characters from the beginning of the
+  # String.
+  #
+  # This method replaces Active Support's +String#first+, except that 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.
+  #
+  # @example
+  #   "abcdef".first(0)   # == ""
+  #   "abcdef".first(3)   # == "abc"
+  #   "abcdef".first(6)   # == "abcdef"
+  #   "abcdef".first(7)   # == "abcdef"
+  #   "abcdef".first(-1)  # == ""
   #
-  # This method is also faster.
+  # @param limit [Integer]
+  # @return [String]
   def first(limit = 1)
     self[0, limit] || ''
   end

data/lib/casual_support/string/from.rb

@@ -1,8 +1,24 @@
+require 'active_support/core_ext/string/access'
+
 class String
 
-  # This replaces Active Support's +String#from+.  It is faster.
+  remove_method :from
+
+  # Returns the substring starting at a given position, spanning through
+  # the end of the String.
+  #
+  # This method replaces Active Support's +String#from+.  It is faster.
+  #
+  # @example
+  #   "abcdef".from(0)  # == "abcdef"
+  #   "abcdef".from(3)  # == "def"
+  #   "abcdef".from(6)  # == ""
+  #   "abcdef".from(7)  # == ""
+  #
+  # @param position [Integer]
+  # @return [String]
   def from(position)
-    self[position, length]
+    self[position, self.length]
   end
 
 end

data/lib/casual_support/string/last.rb

@@ -1,16 +1,30 @@
+require 'active_support/core_ext/string/access'
+
 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+.
+  remove_method :last
+
+  # Returns the last +limit+ characters from the end of the String.
+  #
+  # This method replaces Active Support's +String#last+, except that 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.)  This method is also faster.
+  #
+  # @example
+  #   "abcdef".last(0)   # == ""
+  #   "abcdef".last(3)   # == "def"
+  #   "abcdef".last(6)   # == "abcdef"
+  #   "abcdef".last(7)   # == "abcdef"
+  #   "abcdef".last(-1)  # == ""
   #
-  # This method is also faster.
+  # @param limit [Integer]
+  # @return [String]
   def last(limit = 1)
     limit < 0 ? '' : (self[-limit, limit] || self.dup)
   end

data/lib/casual_support/string/prefix.rb

@@ -1,13 +1,17 @@
 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>.
+  # Prepends a prefix to the String only if the String does not already
+  # start with that prefix.  Otherwise returns a duplicate of the
+  # String.  Equivalent to +gsub(/^(?!prefix)/, "prefix")+.
   #
-  # @param [String] fix prefix to prepend
-  # @return [String] prefixed string
-  def prefix(fix)
-    self.start_with?(fix) ? self.dup : "#{fix}#{self}"
+  # @example
+  #   "example.com".prefix("www.")      # == "www.example.com"
+  #   "www.example.com".prefix("www.")  # == "www.example.com"
+  #
+  # @param affix [String]
+  # @return [String]
+  def prefix(affix)
+    self.start_with?(affix) ? self.dup : "#{affix}#{self}"
   end
 
 end

data/lib/casual_support/string/suffix.rb

@@ -1,13 +1,17 @@
 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>.
+  # Appends a suffix to the String only if the String does not already
+  # end with that suffix.  Otherwise returns a duplicate of the String.
+  # Equivalent to +gsub(/(?<!affix)$/, "affix")+.
   #
-  # @param [String] fix suffix to append
-  # @return [String] suffixed string
-  def suffix(fix)
-    self.end_with?(fix) ? self.dup : "#{self}#{fix}"
+  # @example
+  #   "example".suffix(".com")      # == "example.com"
+  #   "example.com".suffix(".com")  # == "example.com"
+  #
+  # @param affix [String]
+  # @return [String]
+  def suffix(affix)
+    self.end_with?(affix) ? self.dup : "#{self}#{affix}"
   end
 
 end

data/lib/casual_support/string/to.rb

@@ -1,6 +1,22 @@
+require 'active_support/core_ext/string/access'
+
 class String
 
-  # This replaces Active Support's +String#to+.  It is faster.
+  remove_method :to
+
+  # Returns the substring from the start of the String, spanning through
+  # a given position.
+  #
+  # This method replaces Active Support's +String#to+.  It is faster.
+  #
+  # @example
+  #   "abcdef".to(0)  # == "a"
+  #   "abcdef".to(2)  # == "abc"
+  #   "abcdef".to(5)  # == "abcdef"
+  #   "abcdef".to(6)  # == "abcdef"
+  #
+  # @param position [Integer]
+  # @return [String]
   def to(position)
     position += self.length if position < 0
     self[0, position + 1] || ''

data/lib/casual_support/struct.rb

@@ -0,0 +1,2 @@
+require_relative 'struct/assign_attributes'
+require_relative 'struct/from_h'

data/lib/casual_support/struct/assign_attributes.rb

@@ -0,0 +1,26 @@
+class Struct
+
+  # Assigns values in the given Hash to corresponding attributes of the
+  # Struct.  Both Symbol keys and String keys are accepted.  Keys which
+  # don't correspond to an attribute of the Struct are ignored.  Mutates
+  # the Struct and returns it.
+  #
+  # @example
+  #   Point = Struct.new(:x, :y, :z)
+  #   point = Point.new(10, 20, 30)
+  #
+  #   point.assign_attributes(y: 30, z: 50)  # == point
+  #   point.to_h                             # == { x: 10, y: 30, z: 50 }
+  #
+  # @param new_attributes [Hash<Symbol, Object>, Hash<String, Object>]
+  # @return [self]
+  def assign_attributes(new_attributes)
+    ms = self.members
+    new_attributes.each do |k, v|
+      m = k.to_sym
+      self[m] = v if ms.include?(m)
+    end
+    self
+  end
+
+end

data/lib/casual_support/struct/from_h.rb

@@ -0,0 +1,22 @@
+require_relative 'assign_attributes'
+
+class Struct
+
+  # Constructs an instance of a subclass of Struct, and assigns the
+  # values of the given attribute Hash to the instance.  This method is
+  # intended for use only with subclasses of Struct which do not alter
+  # the default signature of the +initialize+ method.  See also
+  # {Struct#assign_attributes}.
+  #
+  # @example
+  #   Point = Struct.new(:x, :y, :z)
+  #   p = Point.from_h(x: 10, y: 20, z: 30)  # == Point.new(10, 20, 30)
+  #
+  # @param attributes [Hash<Symbol, Object>, Hash<String, Object>]
+  # @return [self.new]
+  def self.from_h(attributes)
+    raise "Struct.from_h is for use only with subclasses of Struct" if self == Struct
+    self.new.assign_attributes(attributes)
+  end
+
+end

data/lib/casual_support/time/to_hms.rb

@@ -1,9 +1,12 @@
 class Time
 
-  # Formats time as "HH:MM:SS" (e.g. "23:59:59").  Equivalent to
-  # <code>strftime("%H:%M:%S")</code>, but faster.
+  # Formats the Time as "HH:MM:SS".  Equivalent to
+  # +strftime("%H:%M:%S")+, but faster.
   #
-  # @return [String] the time formatted as "HH:MM:SS"
+  # @example
+  #   Time.new(1999, 12, 31, 23, 59, 59).to_hms  # == "23:59:59"
+  #
+  # @return [String]
   def to_hms
     # Date#strftime appears to be **much** faster than Time#strftime
     # (nearly 3x faster!).  If Time#strftime becomes optimized to that

data/lib/casual_support/time/to_ymd.rb

@@ -1,9 +1,12 @@
 class Time
 
-  # Formats time as "YYYY-MM-DD" (e.g. "1999-12-31").  Equivalent to
-  # <code>strftime("%Y-%m-%d")</code>, but faster.
+  # Formats the Time as "YYYY-MM-DD".  Equivalent to
+  # +strftime("%Y-%m-%d")+, but faster.
   #
-  # @return [String] the time formatted as "YYYY-MM-DD"
+  # @example
+  #   Time.new(1999, 12, 31, 23, 59, 59).to_ymd  # == "1999-12-31"
+  #
+  # @return [String]
   def to_ymd
     # Date#strftime appears to be **much** faster than Time#strftime
     # (nearly 3x faster!).  If Time#strftime becomes optimized to that

data/lib/casual_support/version.rb

@@ -1,3 +1,3 @@
 module CasualSupport
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: casual_support
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-06 00:00:00.000000000 Z
+date: 2017-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -129,23 +129,28 @@ files:
 - benchmarks/string/prefix.rb
 - benchmarks/string/suffix.rb
 - benchmarks/string/to.rb
+- benchmarks/struct/assign_attributes.rb
 - benchmarks/time/to_hms.rb
 - benchmarks/time/to_ymd.rb
 - casual_support.gemspec
 - lib/casual_support.rb
+- lib/casual_support/boolean.rb
+- lib/casual_support/boolean/to_z.rb
 - lib/casual_support/comparable.rb
 - lib/casual_support/comparable/at_least.rb
 - lib/casual_support/comparable/at_most.rb
-- lib/casual_support/comparable/clamp.rb
 - lib/casual_support/date.rb
 - lib/casual_support/date/to_ymd.rb
 - lib/casual_support/enumerable.rb
 - lib/casual_support/enumerable/duplicates.rb
 - lib/casual_support/enumerable/index_to.rb
 - lib/casual_support/hash.rb
+- lib/casual_support/hash/displace.rb
 - lib/casual_support/hash/putbang.rb
 - lib/casual_support/integer.rb
 - lib/casual_support/integer/to_hex.rb
+- lib/casual_support/numeric.rb
+- lib/casual_support/numeric/sign.rb
 - lib/casual_support/string.rb
 - lib/casual_support/string/after.rb
 - lib/casual_support/string/after_last.rb
@@ -156,10 +161,12 @@ files:
 - lib/casual_support/string/first.rb
 - lib/casual_support/string/from.rb
 - lib/casual_support/string/last.rb
-- lib/casual_support/string/lchomp.rb
 - lib/casual_support/string/prefix.rb
 - lib/casual_support/string/suffix.rb
 - lib/casual_support/string/to.rb
+- lib/casual_support/struct.rb
+- lib/casual_support/struct/assign_attributes.rb
+- lib/casual_support/struct/from_h.rb
 - lib/casual_support/time.rb
 - lib/casual_support/time/to_hms.rb
 - lib/casual_support/time/to_ymd.rb
@@ -184,7 +191,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Utility extensions to core objects, a la Active Support

data/lib/casual_support/comparable/clamp.rb

@@ -1,16 +0,0 @@
-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/string/lchomp.rb

@@ -1,16 +0,0 @@
-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