Class: Hash

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

  require 'facet/hash/zipnew'

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

[]( *sliceKeys )

Adds slicing to Hash#[]. If more than one key arguments is given to Hash#[], the return value will be an array of the corresponding values.

  require "facet/hash/slice-op"

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

[]=( *args )

Add slicing to element assignment operator.

  require "facet/hash/slice-op"

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

  h[:a] = 9              #=> 9
  h                      #=> {:a=>9, :b=>2, :c=>3}

  h[:a, :c] = [10,11]    #=> [10,11]
  h                      #=> {:a=>10, :b=>2, :c=>11}

alias!( newkey, oldkey )

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.

  require 'facet/hash/alias!'

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

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

assert_has_keys(*check_keys)

require ‘facet/hash/assert_has_keys‘

h = { :a => 1, :b => 2 } h.assert_has_keys( :a ) #=> true h.assert_has_keys( :c ) #=> ArgumentError

assert_has_keys(*check_keys)

require ‘facet/hash/has_keys?‘

h = { :a => 1, :b => 2 } h.assert_has_keys( :a ) #=> true h.assert_has_keys( :c ) #=> ArgumentError

assert_has_only_keys(*check_keys)

require ‘facet/hash/has_keys?‘

h = { :a => 1, :b => 2 } h.assert_only_keys( :a, :b ) #=> true h.assert_only_keys( :a ) #=> ArgumentError

assert_has_only_keys(*check_keys)

Returns true is hash has only give keys, otherwise throws an ArgumentError.

  require 'facet/hash/assert_has_only_keys'

  h = { :a => 1, :b => 2 }
  h.assert_has_only_keys( :a, :b )   #=> true
  h.assert_has_only_keys( :a )       #=> ArgumentError

at_rand()

Alias for rand_value

collate( {|| ...}

Returns a new hash built by iterating through each key,value pair and updating the new hash.

  require 'facet/hash/collate'

collate!(&yld)

In place version of collate.

each() {|v| ...}

A "smarter" hasheach which iterates through each value if only one block parameter is given.

  require 'facet/hash/each'

  {:a=>"a", 2=>"b", "x"=>"c"}.each{ |v| puts v }

produces

  a
  b
  c

WARNING! Use with caution. Methods from other libraries may depend on the old behavior, expecting a two element array to be passed into a single block argument.

graph(&yld)

Like map/collect, but it generates a Hash. The block is expected to return two values: the key and the value for the new hash.

  require 'facet/enumberable/graph'

  numbers  = (1..3)
  squares  = numbers.graph { |n| [n, n*n] }   # { 1=>1, 2=>4, 3=>9 }
  sq_roots = numbers.graph { |n| [n*n, n] }   # { 1=>1, 4=>2, 9=>3 }

graph!( &blk )

As with graph but acts in place.

has_keys?(*check_keys)

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

  require 'facet/hash/has_keys?'

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

has_keys?(*check_keys)

require ‘facet/hash/has_keys?‘

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

has_only_keys?(*check_keys)

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

  require 'facet/hash/has_only_keys?'

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

has_only_keys?(*check_keys)

require ‘facet/hash/has_keys?‘

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

inverse()

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

  require 'facet/hash/inverse'

  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

keys_to_s( from_class=nil )

Converts all keys in the Hash to be String values, returning a new Hash. With a from_class parameter, limits conversion to only a certain class of keys. It defaults to nil which convert any key class.

  require 'facet/hash/keys_to_s'

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

keys_to_s!( from_class=nil )

Synonym for Hash#keys_to_string, but modifies the receiver in place (and returns it). With a from_class parameter, limits conversion to only a certain class of keys. It defaults to nil which convert any key class.

  require 'facet/hash/keys_to_s'

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

keys_to_sym( from_class=String )

Converts all keys in the Hash to be Symbol values, returning a new Hash. With a from_class parameter, limits conversion to only a certain class of keys. It defaults to String —use nil to convert any key class.

  require 'facet/hash/keys_to_sym'

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

keys_to_sym!( from_class=String )

Synonym for Hash#keys_to_symbol, but modifies the receiver in place (and returns it). With a from_class parameter, limits conversion to only a certain class of keys. It defaults to String —use nil to convert any key class.

  require 'facet/hash/keys_to_symbol'

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

pick_key()

Alias for rand_key!

pick_pair()

Alias for rand_pair!

rand_key()

Returns a random key.

  require 'facet/hash/at_rand'

  {:one => 1, :two => 2, :three => 3}.pick_key  #=> :three

rand_key!()

Delete a random key-value pair, returning the key.

  require 'facet/hash/at_rand'

  a = {:one => 1, :two => 2, :three => 3}
  a.pick_key!  #=> :two
  a            #=> {:one => 1, :three => 3}

rand_pair()

Returns a random key-value pair.

  require 'facet/hash/at_rand'

  {:one => 1, :two => 2, :three => 3}.pick  #=> [:one, 1]

rand_pair!()

Deletes a random key-value pair and returns that pair.

  require 'facet/hash/at_rand'

  a = {:one => 1, :two => 2, :three => 3}
  a.rand_pair!  #=> [:two, 2]
  a             #=> {:one => 1, :three => 3}

rand_value()

Returns a random hash value.

  require 'facet/hash/rand_value'

  {:one => 1, :two => 2, :three => 3}.rand_value  #=> 2
  {:one => 1, :two => 2, :three => 3}.rand_value  #=> 1

rand_value!()

Deletes a random key-value pair and returns the value.

  require 'facet/hash/at_rand'

  a = {:one => 1, :two => 2, :three => 3}
  a.at_rand!  #=> 2
  a           #=> {:one => 1, :three => 3}

replace_each( {|| ...}

Same as update_each, but deletes the key element first.

shuffle_hash()

Returns a copy of the hash with values arranged in new random order.

  require 'facet/hash/shuffle'

  h = {:a=>1, :b=>2, :c=>3}
  h.shuffle_hash  #=> {:b=>2, :c=>1, :a>3}

shuffle_hash!()

Destructive shuffle_hash. Arrange the values in a new random order.

  require 'facet/hash/shuffle'

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

shuffle_hash_pairs()

Return the key-value pairs with keys and values shuffled independedly.

  require 'facet/hash/shuffle'

  {:a=>1, :b=>2, :c=>3}.shuffle_hash_pairs

produces

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

swap!( key1, key2 )

Swap the values of a pair of keys.

  require 'facet/hash/swap!'

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

swapkey!( newkey, oldkey )

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

Returns a reference to the Hash.

  require 'facet/hash/swapkey!'

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

symbolize_keys( from_class=String )

Alias for keys_to_sym

symbolize_keys!( from_class=String )

Alias for keys_to_sym!

to_h()

Return a rehashing of self.

  require 'facet/hash/to_h'

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

to_ostruct()

Turns a hash into a generic object using an OpenStruct.

  require 'facet/hash/to_ostruct'

  o = { 'a' => 1 }.to_ostruct
  o.a  #=> 1

to_ostruct_recurse()

Like to_ostruct but recusively objectifies all hash elements as well.

  require 'facet/hash/to_ostruct'

  o = { 'a' => { 'b' => 1 } }.to_ostruct_recurse
  o.a.b  #=> 1

traverse(&b)

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]+.

  require 'facet/hash/traverse'

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

traverse!( &yld )

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

  require 'facet/hash/traverse'

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

update_each( {|| ...}

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

  require 'facet/hash/update_each'

  # example to do

weave(h)

Weaves two hashes producing 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)
  valueA, valueB => valueB
  </tt>

Example:

  require 'facet/hash/weave'

  # to do

Methods

External Aliases

Public Class methods

Public Instance methods

[]	->	at
rand_value!	->	at_rand!
update	->	<<
	Alias shorthand for update.
values_at	->	slice
	Alias slice to values_at. require "facet/hash/slice" h = { :a => 1, :b => 2, :c => 3 } h.slice(:a) #=> [1] h.slice(:a, :b) #=> [1,2]
at_rand!	->	pick