nuggets 0.9.9 → 1.0.0

data/lib/nuggets/array/boost.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/boost_mixin'
+
+class Array
+  include Nuggets::Array::BoostMixin
+end

data/lib/nuggets/array/boost_mixin.rb

@@ -0,0 +1,77 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2012 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/mean_mixin'
+
+module Nuggets
+  class Array
+    module BoostMixin
+
+  def self.included(base)
+    base.send :include, Nuggets::Array::MeanMixin
+  end
+
+  # call-seq:
+  #   array.boost_factor(other_array) => aFloat
+  #   array.boost_factor(other_array) { |array| ... } => aFloat
+  #
+  # Calculates the "boost factor" *from* the series of values in _array_ *to*
+  # the series of values in +other_array+ by means of their arithmetic mean
+  # or the value returned from the block given.
+  #
+  # Example:
+  #
+  #   # series of runtime measurements for old version
+  #   a = [1.5, 1.6, 1.4]
+  #
+  #   # series of runtime measurements for new version
+  #   b = [0.7, 0.8, 0.8]
+  #
+  #   # what speedup did we get? => almost 50%
+  #   a.boost_factor(b)  #=> -0.48888888888888893
+  def boost_factor(other, &block)
+    block ||= :mean.to_proc
+    block[other] / block[self] - 1
+  end
+
+  alias_method :boof, :boost_factor
+
+  # call-seq:
+  #   array.boost(factor) => anArray
+  #
+  # Maps each value in _array_ to its "boosted" value according to +factor+.
+  # (Cf. #boost_factor)
+  #
+  # Example:
+  #
+  #   a.boost(a.boost_factor(b)).mean == b.mean
+  def boost(factor)
+    map { |x| x * (1 + factor) }
+  end
+
+    end
+  end
+end

data/lib/nuggets/array/combination.rb

@@ -0,0 +1,62 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.comb(n, ...) => new_array
+  #   array.comb(n, ...) { |combination| ... } => new_array
+  #
+  # Returns an array of arrays of each possible +n+-combination of _array_ for each
+  # given +n+. If a block is given, each +combination+ is yielded to it. Based on
+  # <http://blade.nagaokaut.ac.jp/~sinara/ruby/math/combinatorics/array-comb.rb>.
+  def comb(*sizes)
+    # If no sizes are given, produce all!
+    sizes = (0..size).to_a.reverse if sizes.empty?
+
+    combinations, collect_and_yield = [], lambda { |combination|
+      yield combination if block_given?
+      combinations << combination
+    }
+
+    sizes.each { |n|
+      case n
+        when 0        # Short-cut (breaks recursion)
+          collect_and_yield[[]]
+        when 1..size  # Ignore out-of-range values
+          self[1..-1].comb(n - 1) { |combination|
+            collect_and_yield[combination.unshift(first)]
+          }
+          self[1..-1].comb(n) { |combination|
+            collect_and_yield[combination]
+          }
+      end
+    }
+
+    combinations
+  end
+
+end

data/lib/nuggets/array/correlation.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/correlation_mixin'
+
+class Array
+  include Nuggets::Array::CorrelationMixin
+end

data/lib/nuggets/array/correlation_mixin.rb

@@ -0,0 +1,63 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/standard_deviation_mixin'
+
+module Nuggets
+  class Array
+    module CorrelationMixin
+
+  def self.included(base)
+    base.send :include, Nuggets::Array::StandardDeviationMixin
+  end
+
+  # call-seq:
+  #   array.correlation_coefficient => anArray
+  #
+  # Calculates the {Pearson product-moment correlation
+  # coefficient}[http://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient]
+  # for the <tt>{x,y}</tt> pairs in _array_. If _array_ only contains
+  # values instead of pairs, +y+ will be the value and +x+ will be each
+  # value's position (rank) in _array_.
+  def correlation_coefficient
+    return 0.0 if empty?
+
+    target = first.respond_to?(:to_ary) ? self :
+      self.class.new(size) { |i| [i + 1, at(i)] }
+
+    c = target.cov
+
+    (sx = target.std { |x, _| x }).zero? ||
+    (sy = target.std { |_, y| y }).zero? ?
+      c < 0 ? -1.0 : 1.0 : c / (sx * sy)
+  end
+
+  alias_method :corr, :correlation_coefficient
+  alias_method :pmcc, :correlation_coefficient
+
+    end
+  end
+end

data/lib/nuggets/array/flatten_once.rb

@@ -0,0 +1,56 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+class Array
+
+  # call-seq:
+  #   array.flatten_once => new_array
+  #
+  # Flatten _array_ by _one_ level only. Pretty straight-forward port of David
+  # Alan Black's flattenx C implementation (though much slower, of course ;-).
+  def flatten_once
+    flat = []
+
+    each { |element|
+      if element.is_a?(::Array)
+        flat += element
+      else
+        flat << element
+      end
+    }
+
+    flat
+  end
+
+  # call-seq:
+  #   array.flatten_once! => array
+  #
+  # Destructive version of #flatten_once.
+  def flatten_once!
+    replace(flatten_once)
+  end
+
+end

data/lib/nuggets/array/flush.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/flush_mixin'
+
+class Array
+  include Nuggets::Array::FlushMixin
+end

data/lib/nuggets/array/flush_mixin.rb

@@ -0,0 +1,46 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2013 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module FlushMixin
+
+  # call-seq:
+  #   array.flush => anArray
+  #   array.flush { |array| ... } => anObject
+  #
+  # If a block is given, yields _array_ to the block and
+  # clears it afterwards; returns the return value of the
+  # block. Otherwise clears _array_ and returns its contents.
+  def flush
+    ret = block_given? ? yield(self) : dup
+    clear
+    ret
+  end
+
+    end
+  end
+end

data/lib/nuggets/array/format.rb

@@ -0,0 +1,65 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2011 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+require 'nuggets/array/combination'
+
+class Array
+
+  # call-seq:
+  #   array % other_array => aString
+  #   array % str         => aString
+  #
+  # Format--Uses the first string in _array_ for which the corresponding
+  # combination of _other_array_ does not contain blank elements as a format
+  # specification, and returns the result of applying it to that combination
+  # (cf. String#%). Returns an empty string if _other_array_ is empty.
+  #
+  # Applies to string argument accordingly: First string in _array_ applied to
+  # _str_; empty string if _str_ is empty.
+  def %(args)
+    opts = { :sep => ', ' }
+    opts.update(pop) if last.is_a?(::Hash)
+
+    default = lambda { |n| ['%s'] * n * opts[:sep] }
+
+    case args
+      when ::String
+        return (first || default[1]) % args unless
+          args.nil? || args.empty?
+      when ::Array
+        i = 0
+        [*args].comb { |x|
+          return (self[i] || default[x.size]) % x unless
+            x.empty? || x.any? { |y| y.nil? || y.empty? }
+
+          i += 1
+        }
+    end
+
+    ''
+  end
+
+end

data/lib/nuggets/array/hashify.rb

@@ -0,0 +1,5 @@
+require 'nuggets/array/hashify_mixin'
+
+class Array
+  include Nuggets::Array::HashifyMixin
+end

data/lib/nuggets/array/hashify_mixin.rb

@@ -0,0 +1,47 @@
+#--
+###############################################################################
+#                                                                             #
+# nuggets -- Extending Ruby                                                   #
+#                                                                             #
+# Copyright (C) 2007-2014 Jens Wille                                          #
+#                                                                             #
+# Authors:                                                                    #
+#     Jens Wille <jens.wille@gmail.com>                                       #
+#                                                                             #
+# nuggets is free software; you can redistribute it and/or modify it under    #
+# the terms of the GNU Affero General Public License as published by the Free #
+# Software Foundation; either version 3 of the License, or (at your option)   #
+# any later version.                                                          #
+#                                                                             #
+# nuggets is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS   #
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for     #
+# more details.                                                               #
+#                                                                             #
+# You should have received a copy of the GNU Affero General Public License    #
+# along with nuggets. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                             #
+###############################################################################
+#++
+
+module Nuggets
+  class Array
+    module HashifyMixin
+
+      def hashify(value = nil, &block)
+        block ||= lambda { |key| [key, key] }
+
+        hash = case value
+          when ::Hash then value
+          when ::Proc then ::Hash.new(&value)
+          else             ::Hash.new(value)
+        end
+
+        each { |key| hash.store(*block[key]) }
+
+        hash
+      end
+
+    end
+  end
+end