sleeping_king_studios-tools 0.2.0 → 0.3.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2cbcab2d2d7823d4c8236c192e43624496156d31
-  data.tar.gz: df39fa76136cc679066555eed5a9d047054a0162
+  metadata.gz: d2abf0235b1796184caa2b29cc3c2886d0b94f1b
+  data.tar.gz: 784bd7ea599838663906cde584cbcca474879ed6
 SHA512:
-  metadata.gz: 37b3aab0adbf9e9c6715543fac51f3ff378e9502c1e31846a63b288ab89cf20a43c4506172cf0f2a80d35ff00e827c968854623f6eb95541051ac4e7da70ad1f
-  data.tar.gz: e72a4bc32d601530b21de8323b361b9b2c297181ee2283271e8e201ba3ff1ed5fa54230c21731188ac05ac00f21d0e159bbde072062245985ec71048df289c9d
+  metadata.gz: 9554e42f6ac9fc4e584849d808872828b2091efdc645a3c22d65403c474e786eedbcb6eb61440ae7991508ff571bd358f940f4fe67fe87d9842d4c54d77dedba
+  data.tar.gz: 57137dcbd88ef5ca51d071b69315a819c9a3e3d00c92d2d620a602eb032ea546c59bebba62b2c7139615c0ab4b4956053bf4a86121b1a7c3f5341ea428425936

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Pre-release Versions
 
+### 0.3.0
+
+Implement ArrayTools#bisect and ArrayTools#splice.
+
+#### StringTools
+
+Implement #underscore.
+
 ### 0.2.0
 
 Split EnumerableTools into ArrayTools and HashTools.

data/README.md

@@ -18,6 +18,17 @@ Hi, I'm Rob Smith, a Ruby Engineer and the developer of this library. I use thes
 
 Tools for working with array-like enumerable objects.
 
+#### `#bisect`
+
+Separates the array into two arrays, the first containing all items in the original array that matches the provided block, and the second containing all items in the original array that do not match the provided block.
+
+    original = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    selected, rejected = ArrayTools.bisect(original) { |item| item.even? }
+    selected
+    #=> [0, 2, 4, 6, 8]
+    rejected
+    #=> [1, 3, 5, 7, 9]
+
 #### `#count_values`
 
 Counts the number of times each value appears in the array, or if a block is given, calls the block with each item and counts the number of times each result appears.
@@ -64,6 +75,31 @@ Accepts a list of values and returns a human-readable string of the values, with
     ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'])
     #=> 'spam, eggs, bacon, and spam'
 
+#### `#splice`
+
+Accepts an array, a start value, a number of items to delete, and zero or more items to insert at that index. Deletes the specified number of items, then inserts the given items at the index and returns the array of deleted items.
+
+    # Deleting items from an Array
+    values = %w(katana wakizashi tachi daito shoto)
+    ArrayTools.splice values, 1, 2
+    #=> ['wakizashi', 'tachi']
+    values
+    #=> ['katana', 'daito', 'shoto']
+
+    # Inserting items into an Array
+    values = %w(longsword broadsword claymore)
+    ArrayTools.splice values, 1, 0, 'zweihänder'
+    #=> []
+    values
+    #=> ['longsword', 'zweihänder', 'broadsword', 'claymore']
+
+    # Inserting and deleting items
+    values = %w(shortbow longbow crossbow)
+    ArrayTools.splice values, 2, 1, 'arbalest', 'chu-ko-nu'
+    #=> ['crossbow']
+    values
+    #=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']
+
 ### Hash Tools
 
 Tools for working with array-like enumerable objects.
@@ -202,6 +238,10 @@ Returns the singular or the plural value, depending on the provided item count.
     StringTools.pluralize 4, 'light', 'lights'
     #=> 'lights'
 
+#### '#underscore'
+
+Converts a mixed-case string expression to a lowercase, underscore separated string, as per ActiveSupport::Inflector#underscore.
+
 ## Additional Features
 
 ### Semantic Version

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -8,19 +8,57 @@ module SleepingKingStudios::Tools
   module ArrayTools
     extend self
 
-    # @overload count_values(values)
+    # Separates the array into two arrays, the first containing all items in the
+    # original array that matches the provided block, and the second containing
+    # all items in the original array that do not match the provided block.
+    #
+    # @example
+    #   selected, rejected = ArrayTools.bisect([*0...10]) { |item| item.even? }
+    #   selected
+    #   #=> [0, 2, 4, 6, 8]
+    #   rejected
+    #   #=> [1, 3, 5, 7, 9]
+    #
+    # @param [Array<Object>] ary The array to bisect.
+    #
+    # @yieldparam item [Object] An item in the array to matched.
+    #
+    # @yieldreturn [Boolean] True if the item matches the criteria, otherwise
+    #   false.
+    #
+    # @raise ArgumentError If the first argument is not an Array-like object or
+    #   if no block is given.
+    #
+    # @return [Array<Array<Object>>] An array containing two arrays.
+    def bisect ary, &block
+      require_array! ary
+
+      raise ArgumentError.new('no block given') unless block_given?
+
+      selected, rejected = [], []
+
+      ary.each do |item|
+        (yield(item) ? selected : rejected) << item
+      end # each
+
+      [selected, rejected]
+    end # method bisect
+
+    # @overload count_values(ary)
     #   Counts the number of times each value appears in the enumerable object.
     #
     #   @example
     #     ArrayTools.count_values([1, 1, 1, 2, 2, 3])
     #     #=> { 1 => 3, 2 => 2, 3 => 1 }
     #
-    #   @param [Array<Object>] values The values to count.
+    #   @param [Array<Object>] ary The values to count.
+    #
+    #   @raise ArgumentError If the first argument is not an Array-like object.
     #
     #   @return [Hash{Object, Integer}] The number of times each value appears
     #     in the enumerable object.
     #
-    # @overload count_values(values, &block)
+    # @overload count_values(ary, &block)
     #   Calls the block with each item and counts the number of times each
     #   result appears.
     #
@@ -28,15 +66,20 @@ module SleepingKingStudios::Tools
     #     ArrayTools.count_values([1, 1, 1, 2, 2, 3]) { |i| i ** 2 }
     #     #=> { 1 => 3, 4 => 2, 9 => 1 }
     #
-    #   @param [Array<Object>] values The values to count.
+    #   @param [Array<Object>] ary The values to count.
+    #
+    #   @yieldparam item [Object] An item in the array to matched.
+    #
+    #   @raise ArgumentError If the first argument is not an Array-like object.
     #
     #   @return [Hash{Object, Integer}] The number of times each result
     #     appears.
-    #
-    #   @yield item An item in the array to be converted to a countable result.
-    def count_values values, &block
-      values.each.with_object({}) do |item, hsh|
+    def count_values ary, &block
+      require_array! ary
+
+      ary.each.with_object({}) do |item, hsh|
         value = block_given? ? block.call(item) : item
+
         hsh[value] = hsh.fetch(value, 0) + 1
       end # each
     end # method count_values
@@ -48,6 +91,8 @@ module SleepingKingStudios::Tools
     #
     # @return [Array] The copy of the array.
     def deep_dup ary
+      require_array! ary
+
       ary.map { |obj| ObjectTools.deep_dup obj }
     end # method deep_dup
 
@@ -74,7 +119,7 @@ module SleepingKingStudios::Tools
     #   ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'], :last_separator => ' or ')
     #   #=> 'spam, eggs, bacon, or spam'
     #
-    # @param [Array<String>] values The list of values to format. Will be
+    # @param [Array<String>] ary The list of values to format. Will be
     #   coerced to strings using #to_s.
     # @param [Hash] options Optional configuration hash.
     # @option options [String] :last_separator The value to use to separate
@@ -85,18 +130,22 @@ module SleepingKingStudios::Tools
     #   of values before the last in lists of length 3 or greater. Defaults to
     #   ", " (note the trailing space).
     #
+    # @raise ArgumentError If the first argument is not an Array-like object.
+    #
     # @return [String] The formatted string.
-    def humanize_list values, options = {}
+    def humanize_list ary, options = {}
+      require_array! ary
+
       separator = options.fetch(:separator, ', ')
       last_separator = options.fetch(:last_separator, ' and ')
 
-      case values.count
+      case ary.count
       when 0
         ''
       when 1
-        values.first.to_s
+        ary.first.to_s
       when 2
-        "#{values[0]}#{last_separator}#{values[1]}"
+        "#{ary[0]}#{last_separator}#{ary[1]}"
       else
         if last_separator =~ /\A,?\s*/
           last_separator = last_separator.sub /\A,?\s*/, separator
@@ -104,8 +153,64 @@ module SleepingKingStudios::Tools
           last_separator = "#{separator}#{last_separator}"
         end # if-else
 
-        "#{values[0...-1].join(separator)}#{last_separator}#{values.last}"
+        "#{ary[0...-1].join(separator)}#{last_separator}#{ary.last}"
       end # case
     end # method humanize_list
+
+    # Accepts an array, a start value, a number of items to delete, and zero or
+    # more items to insert at that index. Deletes the specified number of items,
+    # then inserts the given items at the index and returns the array of deleted
+    # items.
+    #
+    # @example Deleting items from an Array
+    #   values = %w(katana wakizashi tachi daito shoto)
+    #   ArrayTools.splice values, 1, 2
+    #   #=> ['wakizashi', 'tachi']
+    #   values
+    #   #=> ['katana', 'daito', 'shoto']
+    #
+    # @example Inserting items into an Array
+    #   values = %w(longsword broadsword claymore)
+    #   ArrayTools.splice values, 1, 0, 'zweihänder'
+    #   #=> []
+    #   values
+    #   #=> ['longsword', 'zweihänder', 'broadsword', 'claymore']
+    #
+    # @example Inserting and deleting items
+    #   values = %w(shortbow longbow crossbow)
+    #   ArrayTools.splice values, 2, 1, 'arbalest', 'chu-ko-nu'
+    #   #=> ['crossbow']
+    #   values
+    #   #=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']
+    #
+    # @param [Array<Object>] ary The array to splice.
+    # @param [Integer] start The starting index to delete or insert values from
+    #   or into. If negative, counts backward from the end of the array.
+    # @param [Integer] delete_count The number of items to delete.
+    # @param [Array<Object>] insert The items to insert, if any.
+    #
+    # @raise ArgumentError If the first argument is not an Array-like object.
+    #
+    # @return [Array<Object>] The deleted items, or an empty array if no items
+    #   were deleted.
+    def splice ary, start, delete_count, *insert
+      require_array! ary
+
+      start   = start < 0 ? start + ary.count : start
+      range   = start...(start + delete_count)
+      deleted = ary[range]
+
+      ary[range] = insert
+
+      deleted
+    end # method splice
+
+    private
+
+    def require_array! value
+      methods = %i([] count each)
+
+      raise ArgumentError.new('argument must be an array') unless methods.reduce(true) { |memo, method_name| memo && value.respond_to?(method_name) }
+    end # method require_array
   end # module
 end # module

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -23,5 +23,30 @@ module SleepingKingStudios::Tools
     def pluralize count, single, plural
       1 == count ? single : plural
     end # method pluralize
+
+    # Converts a mixed-case string expression to a lowercase, underscore
+    # separated string.
+    #
+    # @param str [String] The string to convert.
+    #
+    # @return [String] The converted string.
+    #
+    # @see ActiveSupport::Inflector#underscore.
+    def underscore str
+      require_string! str
+
+      str = str.dup
+      str.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+      str.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      str.tr!("-", "_")
+      str.downcase!
+      str
+    end # method underscore
+
+    private
+
+    def require_string! value
+      raise ArgumentError.new('argument must be a string') unless value.is_a?(String)
+    end # method require_array
   end # module
 end # module

data/lib/sleeping_king_studios/tools/version.rb

@@ -13,8 +13,9 @@ module SleepingKingStudios
       private
 
       MAJOR = 0
-      MINOR = 2
+      MINOR = 3
       PATCH = 0
+      PRERELEASE = 'alpha'
     end # module
 
     VERSION = Version.to_gem_version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sleeping_king_studios-tools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0.alpha
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-07 00:00:00.000000000 Z
+date: 2016-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -114,9 +114,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.1