class Hash

  # Returns a new hash built by iterating through each key,value
  # pair and updating the new hash.
  #
  #--
  # Note that this method may get some fine tuning as it
  # currently expects the block to return a "mini-hash"
  # pair -- parhaps a 2-element array woud be better?
  #++
  def collate  # :yield:
    newhash = {}
    each_pair{ |k,v| newhash.update( yield(k,v) ) }
    newhash
  end

  # In place version of #collate.
  def collate!(&yld)
    replace( collate(&yld) )
  end

end


#  _____         _
# |_   _|__  ___| |_
#   | |/ _ \/ __| __|
#   | |  __/\__ \ |_
#   |_|\___||___/\__|
#
=begin test

  require 'test/unit'

  class TCHash < Test::Unit::TestCase

    def test_collate
      a = { :a => 1, :b => 2, :c => 3 }
      e = { :a => 2, :b => 3, :c => 4 }
      assert_equal( e, a.collate{ |k,v| { k => v+1 } } )
    end

    def test_collate!
      a = { :a => 1, :b => 2, :c => 3 }
      e = { :a => 2, :b => 3, :c => 4 }
      a.collate!{ |k,v| { k => v+1 } }
      assert_equal( e, a )
    end

  end

=end