quality_extensions 0.1.1

data/Readme

@@ -0,0 +1,54 @@
+= QualitySmith Extensions
+
+[<b>Home page</b>:]        http://qualitysmithext.rubyforge.org/
+[<b>Project site</b>:]     http://rubyforge.org/projects/qualitysmithext/
+[<b>Gem install</b>:]      <tt>gem install qualitysmith_extensions</tt>
+[<b>License</b>:]          {Ruby License}[link:files/License.html]
+
+== Introduction
+
+This is a library of miscellaneous general-purpose, reusable Ruby code, quite similar in purpose and layout to {Ruby Facets}[http://facets.rubyforge.org/]. It is certainly not meant to _compete_ with Facets though!
+
+Developers are encouraged to first check if the method or class they are looking for already exists in one of the fine existing open-source projects (like {Facets}[http://facets.rubyforge.org/] or {Extensions}[http://extensions.rubyforge.org/rdoc/index.html] or {stdlib}[http://www.ruby-doc.org/stdlib/]).
+
+If the code you are needing hasn't already been written by someone else, then you can throw it in this library. Also submit it to an existing extensions project if you think it's any good.
+
+Like Facets, this library contains:
+* methods that add functionality to existing Ruby classes (String, Array, etc.)
+* as well as new classes that aren't in core Ruby
+
+== Installation
+
+  gem install qualitysmith_extensions
+
+== Usage
+
+  require 'rubygems'
+  gem 'qualitysmith_extensions'
+
+And then <b>include as much or as little as you want</b>.
+
+Use the handy <tt>all.rb</tt> files to load everything in a particular directory (and all subdirectories).
+
+To load everything:
+
+  require 'qualitysmith_extensions/all'
+
+To load everything just for one class:
+
+  require 'qualitysmith_extensions/string/all'
+
+To load just an individual method:
+
+  require 'qualitysmith_extensions/array/average'
+
+
+== Running tests
+
+Tests are self-contained within the file for the code that is under test.
+
+To run the tests directly, you need to use the <tt>exrb</tt> command that is part of the {Ratchets}[http://ratchets.rubyforge.org/] project.
+
+At some point in time, we may extract them into separate files using the Exacto test extractor tool.
+
+<b>QualitySmith developers</b>: If you use <tt>vim</tt>, you can set up your editor to run the tests just by typing the <tt>:Test</tt> command. To set that up, just include <tt>~/svn/devscripts/vim/include.vim</tt> .

data/lib/qualitysmith_extensions/all.rb

@@ -0,0 +1,4 @@
+require File.dirname(__FILE__) + "/kernel/require_all"
+require_all File.dirname(__FILE__), 
+  :exclude => /(^|\/)test\//,         # Don't include anything in test/ because those files will include test/unit, which causes tests to automatically be run (an unfortunate side-effect)!
+  :exclude_files => 'all.rb'

data/lib/qualitysmith_extensions/array/all.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + "/../kernel/require_all"
+require_all File.dirname(__FILE__), :exclude_files => 'all.rb'

data/lib/qualitysmith_extensions/array/average.rb

@@ -0,0 +1,44 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+#   Wait, so Facets has mode (http://facets.rubyforge.org/src/doc/rdoc/core/classes/Enumerable.html#M001253) but it doesn't have mean/average?
+#   Whether or not this Array#average is included, Facets ought to have an Enumerable#mean/average similar to mode that uses each iterator rather than Array#size. (Still might want to keep this version if it's more efficient for Arrays?)
+#++
+
+class Array
+  # Calculates the arithmetic average (mean) of the elements in the array as a <tt>Float</tt>.
+  #   irb -> [1, 3, 3].average
+  #       => 2.33333333333333
+  def average
+    if self.size == 0
+      raise ZeroDivisionError
+    end
+    self.inject(0.0) do |sum, item|
+      sum + item.to_f
+    end / self.size
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_average
+    assert_equal 2, [0, 4].average
+    assert_equal Float, [0, 4].average.class
+
+    assert_equal 2.5, [0, 5].average
+
+    assert_raise ZeroDivisionError do
+      [].average
+    end
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/classify.rb

@@ -0,0 +1,97 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes!
+# Developer notes:
+# * This is the analog in Array to Set#classify (core).
+# * Compare to Array#group_by (qualitysmith_extensions), which assumes all elements are arrays (making a "table") and only
+#   allows you to do simple classification by the value of a "column". On the other hand, it adds the option to delete that
+#   column from the array, which can be nice, since the classification key in the hash makes it somewhat redundant.
+#++
+
+require 'rubygems'
+gem 'facets'
+require 'facet/array/to_hash'
+class Array
+
+=begin rdoc
+   Classifies the array by the return value of the given block and returns a hash of {value => array of elements} pairs.
+   The block is called once for each element of the array, passing the element as parameter.
+
+   Breaks an array into a hash of smaller arrays, making a new group for each unique value returned by the block. Each unique value becomes a key in the hash.
+
+   Example:
+      [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].classify {|o| o[0]}
+    =>  
+      {
+        "a" => [['a', 1], ['a', 2]], 
+        "b" => [['b', 3], ['b', 4]]
+      }
+=end
+  def classify(&block)
+    hash = {}
+    each do |element|
+      classification = yield(element)
+      (hash[classification] ||= []) << element
+    end
+    hash
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'set'
+
+class TheTest < Test::Unit::TestCase
+  def test_classify
+    input = [
+      ['a', 1],
+      ['a', 2],
+      ['b', 3],
+      ['b', 4],
+    ]
+    assert_equal({
+        "a" => [['a', 1], ['a', 2]], 
+        "b" => [['b', 3], ['b', 4]]
+      }, input.classify {|o| o[0]}
+    )
+    # For comparison:
+    assert_equal({
+        "a" => Set[['a', 1], ['a', 2]], 
+        "b" => Set[['b', 3], ['b', 4]]
+      }, input.to_set.classify {|o| o[0]}
+    )
+
+
+    input = [
+      ['Bob', "Bottle of water", 1.00],
+      ['Bob', "Expensive stapler", 50.00],
+      ['Alice', "Dinner for 2", 100.00],
+      ['Alice', "Bus ride to RubyConf", 50.00],
+    ]
+    assert_equal({
+        "Alice" => [['Alice',"Dinner for 2", 100.0], ['Alice', "Bus ride to RubyConf", 50.0]],
+        "Bob"   => [['Bob', "Bottle of water", 1.0], ['Bob', "Expensive stapler", 50.0]]
+      }, input.classify {|o| o[0]}
+    )
+    assert_equal({
+        50.0  => [["Bob", "Expensive stapler", 50.00], ["Alice", "Bus ride to RubyConf", 50.00]],
+        100.0 => [["Alice", "Dinner for 2", 100.00]],
+        1.0   => [["Bob", "Bottle of water", 1.00]]
+      }, input.classify {|o| o[2]}
+    )
+  end
+end
+=end
+

data/lib/qualitysmith_extensions/array/expand_ranges.rb

@@ -0,0 +1,52 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Yes.
+#++
+
+require 'rubygems'
+require 'facets/core/kernel/silence_warnings'
+
+class Array
+  # Expands (calls +to_a+ on) all Ranges contained in this array, replacing the range with the list of *elements* that the range represents.
+  #
+  # This is especially useful when you want to have "discontiguous ranges" like [1..3, 5..7]...
+  #
+  #   [1..3, 5..7].expand_ranges
+  #   => [1, 2, 3, 5, 6, 7]
+  #
+  def expand_ranges
+    new_array = []
+    each do |item|
+      silence_warnings do             # Object.to_a: warning: default `to_a' will be obsolete
+        if item.respond_to?(:to_a)
+          new_array.concat item.to_a
+        else
+          new_array.concat [item]
+        end
+      end
+    end
+    new_array
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'test/unit'
+class TheTest < Test::Unit::TestCase
+  def test_1
+    assert_equal [1, 2, 3], [1, 2, 3].expand_ranges
+  end
+  def test_2
+    assert_equal [1, 2, 3], [1..3].expand_ranges
+    assert_equal [1, 2, 3, 5, 6, 7], [1..3, 5..7].expand_ranges
+  end
+end
+=end
+

data/lib/qualitysmith_extensions/array/group_by.rb

@@ -0,0 +1,134 @@
+#--
+# Author::    Tyler Rick
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Maybe. 
+# Developer notes:
+# * Name is too general? Name it something to do with 'tables'?
+#   * group_table_by ?
+# * Compare to Array#classify (qualitysmith_extensions), which aims to be more general, letting you classify arrays that are
+#   *not* in "table" form (whose elements are *not* all arrays of equal size and might not even be *arrays*).
+#++
+
+require 'rubygems'
+gem 'facets'
+require 'facet/array/delete_values_at'
+class Array
+
+=begin rdoc
+   Breaks an array into a hash of smaller arrays, making a new group for each unique value in the specified column.
+   Each unique value becomes a key in the hash.
+
+   Example:
+        [
+           ['a', 1],
+           ['a', 2],
+           ['b', 3],
+           ['b', 4],
+        ].group_by(0)
+    =>  
+        "a"=>[[1], [2]], 
+        "b"=>[[3], [4]]
+
+   Options:
+   * <tt>delete_key</tt>: deletes the key from the corresponding array if true (default true)
+
+   Example:
+        [
+           ['a', 1],
+           ['a', 2],
+           ['b', 3],
+           ['b', 4],
+        ].group_by(0, :delete_key => false)
+    =>  
+        "a"=>[['a', 1], ['a', 2]], 
+        "b"=>[['b', 3], ['b', 4]]
+   
+   *Notes*:
+   * <tt>self</tt> must be in the shape of a "table" (that is, a rectangular-shaped, two-dimensional array = an array of arrays,
+     each member array being of the same size (the "width" of the table)).
+   * This is different from the GROUP BY in SQL in that it doesn't apply an aggregate (like sum or average) to each group -- it just returns each group unmodified.
+
+=end
+  def group_by(column_index, *args)
+    options = (if args.last.is_a?(Hash) then args.pop else {} end)
+    hash = {}
+    self.each do |row|
+      row_to_keep = row.dup
+      row_to_keep.delete_values_at(column_index) unless options[:delete_key] == false
+
+      hash[row[column_index]] ||= []
+      hash[row[column_index]] << row_to_keep
+    end
+    hash
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+require 'set'
+
+class TheTest < Test::Unit::TestCase
+  def test_group_by
+    assert_equal({ }, [ ].group_by(column_index = 0))
+
+    assert_equal({
+        "a"=>[[1], [2]], 
+        "b"=>[[3], [4]]
+      }, [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].group_by(column_index = 0)
+    )
+
+
+
+    assert_equal({
+        "a"=>[['a', 1], ['a', 2]], 
+        "b"=>[['b', 3], ['b', 4]]
+      }, [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].group_by(column_index = 0, :delete_key => false)
+    )
+    assert_equal({
+        "a" => Set[['a', 1], ['a', 2]], 
+        "b" => Set[['b', 3], ['b', 4]]
+      }, [
+        ['a', 1],
+        ['a', 2],
+        ['b', 3],
+        ['b', 4],
+      ].to_set.classify {|o| o[0]}
+    )
+
+
+    input = [
+      ['Bob', "Bottle of water", 1.00],
+      ['Bob', "Expensive stapler", 50.00],
+      ['Alice', "Dinner for 2", 100.00],
+      ['Alice', "Bus ride to RubyConf", 50.00],
+    ]
+    assert_equal({
+        "Alice"=>[["Dinner for 2", 100.0], ["Bus ride to RubyConf", 50.0]],
+        "Bob"=>[["Bottle of water", 1.0], ["Expensive stapler", 50.0]]
+      }, input.group_by(column_index = 0)
+    )
+    assert_equal({
+        50.0=>[["Bob", "Expensive stapler"], ["Alice", "Bus ride to RubyConf"]],
+        100.0=>[["Alice", "Dinner for 2"]],
+        1.0=>[["Bob", "Bottle of water"]]
+      }, input.group_by(column_index = 2)
+    )
+  end
+end
+=end

data/lib/qualitysmith_extensions/array/sequence.rb

@@ -0,0 +1,66 @@
+#--
+# Author::    Lance Ivy
+# Copyright:: Copyright (c) 2007 QualitySmith, Inc.
+# License::   Ruby License
+# Submit to Facets?:: Not sure.
+#++
+
+class Array
+=begin rdoc
+  Returns the value previous to the given value. The value previous to the first is the last. Returns nil if the given value is not in the array.
+
+  Example:
+       sequence = ['a', 'b', 'c']
+       sequence.before('a')           => 'c'
+       sequence.before('b')           => 'a'
+       sequence.before('c')           => 'b'
+       sequence.before('d')           => nil
+=end
+  def before(value)
+    return nil unless include? value
+    self[(index(value).to_i - 1) % length]
+  end
+
+=begin rdoc
+  Returns the value after the given value. The value before the last is the first. Returns nil if the given value is not in the array.
+
+  Example:
+       sequence = ['a', 'b', 'c']
+       sequence.after('a')           => 'b'
+       sequence.after('b')           => 'c'
+       sequence.after('c')           => 'a'
+       sequence.after('d')           => nil
+=end
+  def after(value)
+    return nil unless include? value
+    self[(index(value).to_i + 1) % length]
+  end
+end
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+=begin test
+class TheTest < Test::Unit::TestCase
+  def setup
+    @sequence = ['a', 'b', 'c']
+  end
+
+  def test_before
+    assert_equal 'c', @sequence.before('a')
+    assert_equal 'a', @sequence.before('b')
+    assert_equal 'b', @sequence.before('c')
+    assert_equal nil, @sequence.before('d')
+  end
+
+  def test_after
+    assert_equal 'b', @sequence.after('a')
+    assert_equal 'c', @sequence.after('b')
+    assert_equal 'a', @sequence.after('c')
+    assert_equal nil, @sequence.after('d')
+  end
+end
+=end