Hash which auto initializes it's children.

  ah = Hash.autonew
  ah['section one']['param one'] = 4
  ah['section one']['param two'] = 5
  ah['section one']['param three'] = 2
  ah['section one']['param four'] = 3

  p ah
  # {"section one"=>{"param one"=>4, "param four"=>3, "param three"=>2, "param two"=>5}}

  p ah['section one'].keys
  # ["param one", "param four", "param three", "param two"]

CREDIT: Trans, Jan Molic

Creates a new hash from two arrays —a keys array and a values array.

  Hash.zipnew(["a","b","c"], [1,2,3])
    #=> { "a"=>1, "b"=>2, "c"=>3 }

CREDIT: Trans, Ara T. Howard

Hash intersection. Two hashes intersect when their pairs are equal.

  {:a=>1,:b=>2} & {:a=>1,:c=>3}  #=> {:a=>1}

A hash can also be intersected with an array to intersect keys only.

  {:a=>1,:b=>2} & [:a,:c]  #=> {:a=>1}

The later form is similar to pairs_at. The differ only in that pairs_at will return a nil value for a key not in the hash, but #& will not.

CREDIT: Trans

Like merge operator ’+’ but merges in reverse order.

  h1 = { :a=>1 }
  h2 = { :a=>2, :b=>3 }

  h1 + h2  #=> { :a=>2, :b=>3 }
  h1 * h2  #=> { :a=>1, :b=>3 }

CREDIT: Trans

Operator for merge.

CREDIT: Trans

Operator for remove hash paris. If another hash is given the pairs are only removed if both key and value are equal. If an array is given then matching keys are removed.

CREDIT: Trans

Can be used like update, or passed as two-element [key,value] array.

CREDIT: Trans

Modifies the receiving Hash so that the value previously referred to by oldkey is also referenced by newkey; oldkey is retained in the Hash. If oldkey does not exist as a key in the Hash, no change is effected.

Returns a reference to the Hash.

  foo = { :name=>'Gavin', 'wife'=>:Lisa }
  foo.alias!('name',:name)     => { :name=>'Gavin', 'name'=>'Gavin', 'wife'=>:Lisa }

  foo = { :name=>'Gavin', 'wife'=>:Lisa }
  foo.alias!('spouse','wife')  => { :name=>'Gavin', 'wife'=>:Lisa, 'spouse'=>:Lisa }

  foo = { :name=>'Gavin', 'wife'=>:Lisa }
  foo.alias!('bar','foo')      => { :name=>'Gavin', 'wife'=>:Lisa }

Note that if the oldkey is reassigned, the reference will no longer exist, and the newkey will remain as it was.

CREDIT: Gavin Sinclair

TODO: Rename to aliaskey or something else.

Turn a hash into arguments.

  h = { :list => [1,2], :base => "HI" }
  h.argumentize #=> [ [], { :list => [1,2], :base => "HI" } ]
  h.argumentize(:list)   #=> [ [1,2], { :base => "HI" } ]
  h.argumentize(:base)   #=> [ ["HI"], { :list => [1,2] } ]

Merge the values of this hash with those from another, setting all values to be arrays representing the values from both hashes.

  { :a=>1, :b=>2 }.collate :a=>3, :b=>4, :c=>5
  #=> { :a=>[1,3], :b=>[2,4], :c=>[5] }

CREDIT: Gavin Kistner (Phrogz)

The same as collate, but modifies the receiver in place.

Inverse of delete_if.

CREDIT: Daniel Schierbeck

Minor modification to Ruby‘s Hash#delete method allowing it to take multiple keys.

  hsh = { :a => 1, :b => 2 }
  hsh.delete_values(1)
  hsh  #=> { :b => 2 }

CREDIT: Daniel Schierbeck

Minor modification to Ruby‘s Hash#delete method allowing it to take multiple keys.

This works niely with hash#[] and Hash#[]= facets.

   hsh[:a, :b, :c] = 1, 2, 3

   a, b, c = hsh.delete_values_at(:a, :b, :c)

   [a, b, c]  #=> [1, 2, 3]
   hsh        #=> {}

CREDIT: Daniel Schierbeck

Difference comparison of two hashes.

Each with key is like each_pair but reverses the order the parameters to [value,key] instead of [key,value].

CREDIT: Trans

Returns a new hash less the given keys.

Replaces hash with new hash less the given keys. This returns the hash of keys removed.

  h = {:a=>1, :b=>2, :c=>3}
  h.except!(:a)  #=> {:a=>1}
  h              #=> {:b=>2,:c=>3}

Alias for mash!

Returns true or false whether the hash contains the given keys.

  h = { :a => 1, :b => 2 }
  h.has_keys?( :a )   #=> true
  h.has_keys?( :c )   #=> false

CREDIT: Trans

Returns true if the hash contains only the given keys, otherwise false.

  h = { :a => 1, :b => 2 }
  h.has_only_keys?( :a, :b )   #=> true
  h.has_only_keys?( :a )       #=> false

CREDIT: Trans

As with store but only if the key isn‘t already in the hash.

TODO: Would store? be a better name?

CREDIT: Trans

Create a "true" inverse hash by storing mutliple values in Arrays.

  h = {"a"=>3, "b"=>3, "c"=>3, "d"=>2, "e"=>9, "f"=>3, "g"=>9}

  h.invert                #=> {2=>"d", 3=>"f", 9=>"g"}
  h.inverse               #=> {2=>"d", 3=>["f", "c", "b", "a"], 9=>["g", "e"]}
  h.inverse.inverse       #=> {"a"=>3, "b"=>3, "c"=>3, "d"=>2, "e"=>9, "f"=>3, "g"=>9}
  h.inverse.inverse == h  #=> true

CREDIT: Tilo Sloboda

Like Array#join but specialized to Hash.

CREDIT: Mauricio Fernandez

Alias for has_keys?

In place version of mash.

  NOTE: Hash#mash! is only useful for Hash. It is not generally
        applicable to Enumerable.

Alias for has_only_keys?

Same as Hash#merge but recursively merges sub-hashes.

Same as Hash#merge! but recursively merges sub-hashes.

Apply a block to hash, and recursively apply that block to each subhash.

  h = {:a=>1, :b=>{:b1=>1, :b2=>2}}
  h.recursively{|h| h.rekey(&:to_s) }
  => {"a"=>1, "b"=>{"b1"=>1, "b2"=>2}}

Rekey a hash.

  rekey()
  rekey(to_key, from_key)
  rekey{ |key| ... }

If no arguments or block are given, then all keys are converted to Symbols.

If two keys are given, then the second key is changed to the first. You can think of it as alias for hash keys.

  foo = { :a=>1, :b=>2 }
  foo.rekey('a',:a)       #=> { 'a'=>1, :b=>2 }
  foo.rekey('b',:b)       #=> { 'a'=>1, 'b'=>2 }
  foo.rekey('foo','bar')  #=> { 'a'=>1, 'b'=>2 }

If a block is given, converts all keys in the Hash accroding to the given block. If the block returns nil for given key, then that key will be left intact.

  foo = { :name=>'Gavin', :wife=>:Lisa }
  foo.rekey{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
  foo.inspect              #=>  { :name =>"Gavin", :wife=>:Lisa }

CREDIT: Trans, Gavin Kistner

Synonym for Hash#rekey, but modifies the receiver in place (and returns it).

  foo = { :name=>'Gavin', :wife=>:Lisa }
  foo.rekey!{ |k| k.to_s }  #=>  { "name"=>"Gavin", "wife"=>:Lisa }
  foo.inspect               #=>  { "name"=>"Gavin", "wife"=>:Lisa }

CREDIT: Trans, Gavin Kistner

Same as update_each, but deletes the key element first.

CREDIT: Trans

Allows for reverse merging where its the keys in the calling hash that wins over those in the other_hash. This is particularly useful for initializing an incoming option hash with default values:

  def setup(options = {})
    options.reverse_merge! :size => 25, :velocity => 10
  end

The default :size and :velocity is only set if the options passed in doesn‘t already have those keys set.

Inplace form of reverse_merge.

Alias for reverse_merge!

In-place version of Hash#select. The opposite of the built-in Hash#reject!.

CREDIT: Gavin Sinclair, Noah Gibbs

Returns a new hash with only the given keys.

Replaces hash with a new hash having only the given keys. This return the hash of keys removed.

  h = {:a=>1, :b=>2}
  h.slice!(:a)  #=> {:a=>1}
  h             #=> {:b=>2}

Converts all keys in the Hash to Strings, returning a new Hash. With a filter parameter, limits conversion to only a certain selection of keys.

  foo = { :name=>'Gavin', :wife=>:Lisa }
  foo.stringify_keys    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
  foo.inspect           #=>  { :name =>"Gavin", :wife=>:Lisa }

This method is considered archaic. Use rekey instead.

Synonym for Hash#stringify_keys, but modifies the receiver in place and returns it. With a filter parameter, limits conversion to only a certain selection of keys.

  foo = { :name=>'Gavin', :wife=>:Lisa }
  foo.stringify_keys!    #=>  { "name"=>"Gavin", "wife"=>:Lisa }
  foo.inspect            #=>  { "name"=>"Gavin", "wife"=>:Lisa }

This method is considered archaic. Use rekey instead.

Swap the values of a pair of keys in place.

  {:a=>1,:b=>2}.swap!(:a,:b)  #=> {:a=>2,:b=>1}

CREDIT: Gavin Sinclair

Converts all keys in the Hash to Symbols, returning a new Hash. With a filter, limits conversion to only a certain selection of keys.

  foo = { :name=>'Gavin', 'wife'=>:Lisa }
  foo.symbolize_keys    #=>  { :name=>"Gavin", :wife=>:Lisa }
  foo.inspect           #=>  { "name" =>"Gavin", "wife"=>:Lisa }

This method is considered archaic. Use rekey instead.

Synonym for Hash#symbolize_keys, but modifies the receiver in place and returns it. With a filter parameter, limits conversion to only a certain selection of keys.

  foo = { 'name'=>'Gavin', 'wife'=>:Lisa }
  foo.symbolize_keys!    #=>  { :name=>"Gavin", :wife=>:Lisa }
  foo.inspect            #=>  { :name=>"Gavin", :wife=>:Lisa }

This method is considered archaic. Use rekey instead.

Return a rehashing of self.

  {"a"=>1,"b"=>2}.to_h  #=> {"b"=>2,"a"=>1}

CREDIT: Forian Gross

Constructs a Proc object from a hash such that the parameter of the Proc is assigned the hash keys as attributes.

  h = { :a => 1 }
  p = h.to_proc
  o = OpenStruct.new
  p.call(o)
  o.a  #=> 1

CREDIT: Trans

A fault-tolerent version of to_proc.

It works just like to_proc, but the block will make sure# the object responds to the assignment.

CREDIT: Trans

A method to convert a Hash into a Struct.

  h = {:name=>"Dan","age"=>33,"rank"=>"SrA","grade"=>"E4"}
  s = h.to_struct("Foo")

TODO: Is this robust enough considerd hashes aren‘t ordered?

CREDIT: Daniel Berger

Returns a new hash created by traversing the hash and its subhashes, executing the given block on the key and value. The block should return a 2-element array of the form +[key, value]+.

  h = { "A"=>"A", "B"=>"B" }
  g = h.traverse { |k,v| [k.downcase, v] }
  g  #=> { "a"=>"A", "b"=>"B" }

TODO: Contrast these to recursibely —we may not need both.

TODO: Testing value to see if it is a Hash also catches subclasses of Hash.

      This is probably not the right thing to do and should catch Hashes only (?)

CREDIT: Trans

In place version of traverse, which traverses the hash and its subhashes, executing the given block on the key and value.

  h = { "A"=>"A", "B"=>"B" }
  h.traverse! { |k,v| [k.downcase, v] }
  h  #=> { "a"=>"A", "b"=>"B" }

CREDIT: Trans

Iterates through each pair and updates a the hash in place. This is formally equivalent to mash! But does not use mash to accomplish the task. Hence update_each is probably a touch faster.

CREDIT: Trans

Iterate over hash updating just the keys.

  h = {:a=>1, :b=>2}
  h.update_keys{ |k| "#{k}!" }
  h  #=> { "a!"=>1, "b!"=>2 }

CREDIT: Trans

Iterate over hash updating just the values.

  h = {:a=>1, :b=>2}
  h.update_values{ |v| v+1 }
  h  #=> { a:=>2, :b=>3 }

CREDIT: Trans

Weave is a very uniqe hash operator. I is designed to merge to complex hashes in according to sensible, regular pattern. The effect is akin to inheritance.

Two hashes are weaved together to produce a new hash. The two hashes need to be compatible according to the following rules for each node:

  <tt>
  hash,   hash    => hash (recursive +)
  hash,   array   => error
  hash,   value   => error
  array,  hash    => error
  array,  array   => array + array
  array,  value   => array << value
  value,  hash    => error
  value,  array   => array.unshift(valueB)
  value1, value2  => value2
  </tt>

Here is a basic example:

  h1 = { :a => 1, :b => [ 1 ], :c => { :x => 1 } }
  => {:b=>[1], :c=>{:x=>1}, :a=>1}

  h2 = { :a => 2, :b => [ 2 ], :c => { :x => 2 } }
  => {:b=>[2], :c=>{:x=>2}, :a=>2}

  h1.weave(h2)
  => {:b=>[1, 2], :c=>{:x=>2}, :a=>2}

Weave follows the most expected pattern of unifying two complex hashes. It is especially useful for implementing overridable configuration schemes.

CREDIT: Thomas Sawyer

Operator for reverse_merge.

CREDIT: Trans