123456789_123456789_123456789_123456789_123456789_

Class: Hash

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::Enumerable
Inherits: Object
Defined in: hash.c

Overview

A Hash is a dictionary-like collection of unique keys and their values. Also called associative arrays, they are similar to Arrays, but where an ::Array uses integers as its index, a Hash allows you to use any object type.

Hashes enumerate their values in the order that the corresponding keys were inserted.

A Hash can be easily created by using its implicit form:

grades = { "Jane Doe" => 10, "Jim Doe" => 6 }

Hashes allow an alternate syntax form when your keys are always symbols. Instead of

options = { :font_size => 10, :font_family => "Arial" }

You could write it as:

options = { font_size: 10, font_family: "Arial" }

Each named key is a symbol you can access in hash:

options[:font_size]  # => 10

A Hash can also be created through its .new method:

grades = Hash.new
grades["Dorothy Doe"] = 9

Hashes have a default value that is returned when accessing keys that do not exist in the hash. If no default is set nil is used. You can set the default value by sending it as an argument to .new:

grades = Hash.new(0)

Or by using the #default= method:

grades = {"Timmy Doe" => 8}
grades.default = 0

Accessing a value in a Hash requires using its key:

puts grades["Jane Doe"] # => 0

Common Uses

Hashes are an easy way to represent data structures, such as

books         = {}
books[:matz]  = "The Ruby Language"
books[:black] = "The Well-Grounded Rubyist"

Hashes are also commonly used as a way to have named parameters in functions. Note that no brackets are used below. If a hash is the last argument on a method call, no braces are needed, thus creating a really clean interface:

Person.create(name: "John Doe", age: 27)

def self.create(params)
  @name = params[:name]
  @age  = params[:age]
end

Hash Keys

Two objects refer to the same hash key when their #hash value is identical and the two objects are #eql? to each other.

A user-defined class may be used as a hash key if the #hash and #eql? methods are overridden to provide meaningful behavior. By default, separate instances refer to separate hash keys.

A typical implementation of #hash is based on the object's data while #eql? is usually aliased to the overridden #== method:

class Book
  attr_reader :author, :title

  def initialize(author, title)
    @author = author
    @title = title
  end

  def ==(other)
    self.class === other and
      other.author == @author and
      other.title == @title
  end

  alias eql? ==

  def hash
    @author.hash ^ @title.hash # XOR
  end
end

book1 = Book.new 'matz', 'Ruby in a Nutshell'
book2 = Book.new 'matz', 'Ruby in a Nutshell'

reviews = {}

reviews[book1] = 'Great reference!'
reviews[book2] = 'Nice and compact!'

reviews.length #=> 1

See also Object#hash and Object#eql?

Class Method Summary

Instance Attribute Summary

::Enumerable - Included

#all?

Passes each element of the collection to the given block.
#any?

Passes each element of the collection to the given block.
#none?

Passes each element of the collection to the given block.
#one?

Passes each element of the collection to the given block.

Instance Method Summary

::Enumerable - Included

#chunk

Enumerates over the items, chunking them together based on the return value of the block.
#collect

Alias for Enumerable#map.
#collect_concat

Alias for Enumerable#flat_map.
#count

Returns the number of items in enum through enumeration.
#cycle

Calls block for each element of enum repeatedly n times or forever if none or nil is given.
#detect

Alias for Enumerable#find.
#drop

Drops first n elements from enum, and returns rest elements in an array.
#drop_while

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.
#each_cons

Iterates the given block for each array of consecutive <n> elements.
#each_entry

Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.
#each_slice

Iterates the given block for each slice of <n> elements.
#each_with_index

Calls block with two arguments, the item and its index, for each item in enum.
#each_with_object

Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
#entries

Alias for Enumerable#to_a.
#find

Passes each entry in enum to block.
#find_all

Alias for Enumerable#select.
#find_index

Compares each entry in enum with value or passes to block.
#first

Returns the first element, or the first n elements, of the enumerable.
#flat_map

Returns a new array with the concatenated results of running block once for every element in enum.
#grep

Returns an array of every element in enum for which Pattern === element.
#group_by

Groups the collection by result of the block.
#include?

Alias for Enumerable#member?.
#inject

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
#lazy

Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis.
#map

Returns a new array with the results of running block once for every element in enum.
#max

Returns the object in enum with the maximum value.
#max_by

Returns the object in enum that gives the maximum value from the given block.
#member?

Returns true if any member of enum equals obj.
#min

Returns the object in enum with the minimum value.
#min_by

Returns the object in enum that gives the minimum value from the given block.
#minmax

Returns two elements array which contains the minimum and the maximum value in the enumerable.
#minmax_by

Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
#partition

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
#reduce

Alias for Enumerable#inject.
#reject

Returns an array for all elements of enum for which the given block returns false.
#reverse_each

Builds a temporary array and traverses that array in reverse order.
#select

Returns an array containing all elements of enum for which the given block returns a true value.
#slice_after

Creates an enumerator for each chunked elements.
#slice_before

Creates an enumerator for each chunked elements.
#slice_when

Creates an enumerator for each chunked elements.
#sort

Returns an array containing the items in enum sorted, either according to their own <=> method, or by using the results of the supplied block.
#sort_by

Sorts enum using a set of keys generated by mapping the values in enum through the given block.
#take

Returns first n elements from enum.
#take_while

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.
#to_a

Returns an array containing the items in enum.
#to_h

Returns the result of interpreting enum as a list of [key, value] pairs.
#zip

Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new ⇒ Hash .new(obj) ⇒ Hash .new {|hash, key| ... } ⇒ Hash

Returns a new, empty hash. If this hash is subsequently accessed by a key that doesn't correspond to a hash entry, the value returned depends on the style of new used to create the hash. In the first form, the access returns nil. If obj is specified, this single object will be used for all default values. If a block is specified, it will be called with the hash object and the key, and should return the default value. It is the block's responsibility to store the value in the hash if required.

h = Hash.new("Go Fish")
h["a"] = 100
h["b"] = 200
h["a"]           #=> 100
h["c"]           #=> "Go Fish"
# The following alters the single default object
h["c"].upcase!   #=> "GO FISH"
h["d"]           #=> "GO FISH"
h.keys           #=> ["a", "b"]

# While this creates a new default object each time
h = Hash.new { |hash, key| hash[key] = "Go Fish: #{key}" }
h["c"]           #=> "Go Fish: c"
h["c"].upcase!   #=> "GO FISH: C"
h["d"]           #=> "Go Fish: d"
h.keys           #=> ["c", "d"]

Class Method Details

.[](key, value, ... ) ⇒ Hash .[]([ [key, value], ... ] ) ⇒ Hash .[](object ) ⇒ Hash

Creates a new hash populated with the given objects.

Similar to the literal { key => value, ... }. In the first form, keys and values occur in pairs, so there must be an even number of arguments.

The second and third form take a single argument which is either an array of key-value pairs or an object convertible to a hash.

Hash["a", 100, "b", 200]             #=> {"a"=>100, "b"=>200}
Hash[ [ ["a", 100], ["b", 200] ] ]   #=> {"a"=>100, "b"=>200}
Hash["a" => 100, "b" => 200]         #=> {"a"=>100, "b"=>200}

.try_convert(obj) ⇒ Hash?

Try to convert obj into a hash, using to_hash method. Returns converted hash or nil if obj cannot be converted for any reason.

Hash.try_convert({1=>2})   # => {1=>2}
Hash.try_convert("1=>2")   # => nil

Instance Attribute Details

#any? {|(key, value)| ... } ⇒ Boolean (readonly) #any? ⇒ Boolean

See also Enumerable#any?

#compare_by_identity ⇒ Hash (readonly)

Makes hsh compare its keys by their identity, i.e. it will consider exact same objects as same keys.

h1 = { "a" => 100, "b" => 200, :c => "c" }
h1["a"]        #=> 100
h1.compare_by_identity
h1.compare_by_identity? #=> true
h1["a".dup]    #=> nil  # different objects.
h1[:c]         #=> "c"  # same symbols are all same.

#compare_by_identity? ⇒ Boolean (readonly)

Returns true if hsh will compare its keys by their identity. Also see #compare_by_identity.

#default_proc ⇒ Object (rw)

If .new was invoked with a block, return that block, otherwise return nil.

h = Hash.new {|h,k| h[k] = k*k }   #=> {}
p = h.default_proc                 #=> #<Proc:0x401b3d08@-:1>
a = []                             #=> []
p.call(a, 2)
a                                  #=> [nil, nil, 4]

#default_proc=(proc_obj or nil) (rw)

Sets the default proc to be executed on each failed key lookup.

h.default_proc = proc do |hash, key|
  hash[key] = key + key
end
h[2]       #=> 4
h["cat"]   #=> "catcat"

#empty? ⇒ Boolean (readonly)

Returns true if hsh contains no key-value pairs.

{}.empty?   #=> true

Instance Method Details

#==(other_hash) ⇒ Boolean

Equality—Two hashes are equal if they each contain the same number of keys and if each key-value pair is equal to (according to Object#==) the corresponding elements in the other hash.

h1 = { "a" => 1, "c" => 2 }
h2 = { 7 => 35, "c" => 2, "a" => 1 }
h3 = { "a" => 1, "c" => 2, 7 => 35 }
h4 = { "a" => 1, "d" => 2, "f" => 35 }
h1 == h2   #=> false
h2 == h3   #=> true
h3 == h4   #=> false

#[](key) ⇒ value

Element Reference—Retrieves the value object corresponding to the key object. If not found, returns the default value (see .new for details).

h = { "a" => 100, "b" => 200 }
h["a"]   #=> 100
h["c"]   #=> nil

#[]=(key, value) ⇒ value #store(key, value) ⇒ value
Also known as: #store

Element Assignment

Associates the value given by value with the key given by #key.

h = { "a" => 100, "b" => 200 }
h["a"] = 9
h["c"] = 4
h   #=> {"a"=>9, "b"=>200, "c"=>4}
h.store("d", 42) #=> 42
h   #=> {"a"=>9, "b"=>200, "c"=>4, "d"=>42}

#key should not have its value changed while it is in use as a key (an unfrozen String passed as a key will be duplicated and frozen).

a = "a"
b = "b".freeze
h = { a => 100, b => 200 }
h.key(100).equal? a #=> false
h.key(200).equal? b #=> true

#assoc(obj) ⇒ Array?

Searches through the hash comparing obj with the key using #==. Returns the key-value pair (two elements array) or nil if no match is found. See Array#assoc.

h = {"colors"  => ["red", "blue", "green"],
     "letters" => ["a", "b", "c" ]}
h.assoc("letters")  #=> ["letters", ["a", "b", "c"]]
h.assoc("foo")      #=> nil

#clear ⇒ Hash

Removes all key-value pairs from hsh.

h = { "a" => 100, "b" => 200 }   #=> {"a"=>100, "b"=>200}
h.clear                          #=> {}

#default(key = nil) ⇒ Object

Returns the default value, the value that would be returned by hsh if key did not exist in hsh. See also .new and #default=.

h = Hash.new                            #=> {}
h.default                               #=> nil
h.default(2)                            #=> nil

h = Hash.new("cat")                     #=> {}
h.default                               #=> "cat"
h.default(2)                            #=> "cat"

h = Hash.new {|h,k| h[k] = k.to_i*10}   #=> {}
h.default                               #=> nil
h.default(2)                            #=> 20

#default=(obj) ⇒ Object

Sets the default value, the value returned for a key that does not exist in the hash. It is not possible to set the default to a ::Proc that will be executed on each key lookup.

h = { "a" => 100, "b" => 200 }
h.default = "Go fish"
h["a"]     #=> 100
h["z"]     #=> "Go fish"
# This doesn't do what you might hope...
h.default = proc do |hash, key|
  hash[key] = key + key
end
h[2]       #=> #<Proc:0x401b3948@-:6>
h["cat"]   #=> #<Proc:0x401b3948@-:6>

#delete(key) ⇒ value #delete(key) {|key| ... } ⇒ value

Deletes the key-value pair and returns the value from hsh whose key is equal to key. If the key is not found, returns the default value. If the optional code block is given and the key is not found, pass in the key and return the result of block.

h = { "a" => 100, "b" => 200 }
h.delete("a")                              #=> 100
h.delete("z")                              #=> nil
h.delete("z") { |el| "#{el} not found" }   #=> "z not found"

#delete_if {|key, value| ... } ⇒ Hash #delete_if ⇒ Enumerator

Deletes every key-value pair from hsh for which block evaluates to true.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200, "c" => 300 }
h.delete_if {|key, value| key >= "b" }   #=> {"a"=>100}

#each {|key, value| ... } ⇒ Hash #each_pair {|key, value| ... } ⇒ Hash #each ⇒ Enumerator #each_pair ⇒ Enumerator
Also known as: #each_pair

Calls block once for each key in hsh, passing the key-value pair as parameters.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200 }
h.each {|key, value| puts "#{key} is #{value}" }

produces:

a is 100
b is 200

#each_key {|key| ... } ⇒ Hash #each_key ⇒ Enumerator

Calls block once for each key in hsh, passing the key as a parameter.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200 }
h.each_key {|key| puts key }

produces:

a
b

#each {|key, value| ... } ⇒ Hash #each_pair {|key, value| ... } ⇒ Hash #each ⇒ Enumerator #each_pair ⇒ Enumerator

Alias for #each.

#each_value {|value| ... } ⇒ Hash #each_value ⇒ Enumerator

Calls block once for each key in hsh, passing the value as a parameter.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200 }
h.each_value {|value| puts value }

produces:

100
200

#eql?(other) ⇒ Boolean

Returns true if hash and other are both hashes with the same content.

#fetch(key [, default] ) ⇒ Object #fetch(key) {|key| ... } ⇒ Object

Returns a value from the hash for the given key. If the key can't be found, there are several options: With no other arguments, it will raise an ::KeyError exception; if default is given, then that will be returned; if the optional code block is specified, then that will be run and its result returned.

h = { "a" => 100, "b" => 200 }
h.fetch("a")                            #=> 100
h.fetch("z", "go fish")                 #=> "go fish"
h.fetch("z") { |el| "go fish, #{el}"}   #=> "go fish, z"

The following example shows that an exception is raised if the key is not found and a default value is not supplied.

h = { "a" => 100, "b" => 200 }
h.fetch("z")

produces:

prog.rb:2:in `fetch': key not found (KeyError)
 from prog.rb:2

#flatten ⇒ Array #flatten(level) ⇒ Array

Returns a new array that is a one-dimensional flattening of this hash. That is, for every key or value that is an array, extract its elements into the new array. Unlike Array#flatten, this method does not flatten recursively by default. The optional level argument determines the level of recursion to flatten.

a =  {1=> "one", 2 => [2,"two"], 3 => "three"}
a.flatten    # => [1, "one", 2, [2, "two"], 3, "three"]
a.flatten(2) # => [1, "one", 2, 2, "two", 3, "three"]

#has_key?(key) ⇒ Boolean #include?(key) ⇒ Boolean #key?(key) ⇒ Boolean #member?(key) ⇒ Boolean

Alias for #key?.

#has_value?(value) ⇒ Boolean #value?(value) ⇒ Boolean

Alias for #value?.

#hash ⇒ Fixnum

Compute a hash-code for this hash. Two hashes with the same content will have the same hash code (and will compare using #eql?).

See also Object#hash.

#has_key?(key) ⇒ Boolean #include?(key) ⇒ Boolean #key?(key) ⇒ Boolean #member?(key) ⇒ Boolean

Alias for #key?.

#to_s ⇒ String #inspect ⇒ String

Alias for #to_s.

#invert ⇒ Hash

Returns a new hash created by using hsh's values as keys, and the keys as values.

h = { "n" => 100, "m" => 100, "y" => 300, "d" => 200, "a" => 0 }
h.invert   #=> {0=>"a", 100=>"m", 200=>"d", 300=>"y"}

#keep_if {|key, value| ... } ⇒ Hash #keep_if ⇒ Enumerator

Deletes every key-value pair from hsh for which block evaluates to false.

If no block is given, an enumerator is returned instead.

#key(value) ⇒ key

Returns the key of an occurrence of a given value. If the value is not found, returns nil.

h = { "a" => 100, "b" => 200, "c" => 300, "d" => 300 }
h.key(200)   #=> "b"
h.key(300)   #=> "c"
h.key(999)   #=> nil

#has_key?(key) ⇒ Boolean #include?(key) ⇒ Boolean #key?(key) ⇒ Boolean #member?(key) ⇒ Boolean
Also known as: #include?, #member?, #has_key?

Returns true if the given key is present in hsh.

h = { "a" => 100, "b" => 200 }
h.has_key?("a")   #=> true
h.has_key?("z")   #=> false

#keys ⇒ Array

Returns a new array populated with the keys from this hash. See also #values.

h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 }
h.keys   #=> ["a", "b", "c", "d"]

#length ⇒ Fixnum #size ⇒ Fixnum
Also known as: #size

Returns the number of key-value pairs in the hash.

h = { "d" => 100, "a" => 200, "v" => 300, "e" => 400 }
h.length        #=> 4
h.delete("a")   #=> 200
h.length        #=> 3

#has_key?(key) ⇒ Boolean #include?(key) ⇒ Boolean #key?(key) ⇒ Boolean #member?(key) ⇒ Boolean

Alias for #key?.

#merge(other_hash) ⇒ Hash #merge(other_hash) {|key, oldval, newval| ... } ⇒ Hash

Returns a new hash containing the contents of other_hash and the contents of hsh. If no block is specified, the value for entries with duplicate keys will be that of other_hash. Otherwise the value for each duplicate key is determined by calling the block with the key, its value in hsh and its value in other_hash.

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 254, "c" => 300 }
h1.merge(h2)   #=> {"a"=>100, "b"=>254, "c"=>300}
h1.merge(h2){|key, oldval, newval| newval - oldval}
               #=> {"a"=>100, "b"=>54,  "c"=>300}
h1             #=> {"a"=>100, "b"=>200}

#merge!(other_hash) ⇒ Hash #update(other_hash) ⇒ Hash #merge!(other_hash) {|key, oldval, newval| ... } ⇒ Hash #update(other_hash) {|key, oldval, newval| ... } ⇒ Hash
Also known as: #update

Adds the contents of other_hash to hsh. If no block is specified, entries with duplicate keys are overwritten with the values from other_hash, otherwise the value of each duplicate key is determined by calling the block with the key, its value in hsh and its value in other_hash.

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 254, "c" => 300 }
h1.merge!(h2)   #=> {"a"=>100, "b"=>254, "c"=>300}

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 254, "c" => 300 }
h1.merge!(h2) { |key, v1, v2| v1 }
                #=> {"a"=>100, "b"=>200, "c"=>300}

#rassoc(obj) ⇒ Array?

Searches through the hash comparing obj with the value using #==. Returns the first key-value pair (two-element array) that matches. See also Array#rassoc.

a = {1=> "one", 2 => "two", 3 => "three", "ii" => "two"}
a.rassoc("two")    #=> [2, "two"]
a.rassoc("four")   #=> nil

#rehash ⇒ Hash

Rebuilds the hash based on the current hash values for each key. If values of key objects have changed since they were inserted, this method will reindex hsh. If rehash is called while an iterator is traversing the hash, an ::RuntimeError will be raised in the iterator.

a = [ "a", "b" ]
c = [ "c", "d" ]
h = { a => 100, c => 300 }
h[a]       #=> 100
a[0] = "z"
h[a]       #=> nil
h.rehash   #=> {["z", "b"]=>100, ["c", "d"]=>300}
h[a]       #=> 100

#reject {|key, value| ... } ⇒ Hash #reject ⇒ Enumerator

Returns a new hash consisting of entries for which the block returns false.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200, "c" => 300 }
h.reject {|k,v| k < "b"}  #=> {"b" => 200, "c" => 300}
h.reject {|k,v| v > 100}  #=> {"a" => 100}

#reject! {|key, value| ... } ⇒ Hash? #reject! ⇒ Enumerator

Equivalent to #delete_if, but returns nil if no changes were made.

#replace(other_hash) ⇒ Hash

Replaces the contents of hsh with the contents of other_hash.

h = { "a" => 100, "b" => 200 }
h.replace({ "c" => 300, "d" => 400 })   #=> {"c"=>300, "d"=>400}

#select {|key, value| ... } ⇒ Hash #select ⇒ Enumerator

Returns a new hash consisting of entries for which the block returns true.

If no block is given, an enumerator is returned instead.

h = { "a" => 100, "b" => 200, "c" => 300 }
h.select {|k,v| k > "a"}  #=> {"b" => 200, "c" => 300}
h.select {|k,v| v < 200}  #=> {"a" => 100}

#select! {|key, value| ... } ⇒ Hash? #select! ⇒ Enumerator

Equivalent to #keep_if, but returns nil if no changes were made.

#shift ⇒ Array, Object

Removes a key-value pair from hsh and returns it as the two-item array [ key, value ], or the hash's default value if the hash is empty.

h = { 1 => "a", 2 => "b", 3 => "c" }
h.shift   #=> [1, "a"]
h         #=> {2=>"b", 3=>"c"}

#length ⇒ Fixnum #size ⇒ Fixnum

Alias for #length.

#[]=(key, value) ⇒ value #store(key, value) ⇒ value

Alias for #[]=.

#to_a ⇒ Array

Converts hsh to a nested array of [ key, value ] arrays.

h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
h.to_a   #=> [["c", 300], ["a", 100], ["d", 400]]

#to_h ⇒ Hash

Returns self. If called on a subclass of Hash, converts the receiver to a Hash object.

#to_hash ⇒ Hash

Returns self.

#to_s ⇒ String #inspect ⇒ String
Also known as: #inspect

Return the contents of this hash as a string.

h = { "c" => 300, "a" => 100, "d" => 400, "c" => 300  }
h.to_s   #=> "{\"c\"=>300, \"a\"=>100, \"d\"=>400}"

#merge!(other_hash) ⇒ Hash #update(other_hash) ⇒ Hash #merge!(other_hash) {|key, oldval, newval| ... } ⇒ Hash #update(other_hash) {|key, oldval, newval| ... } ⇒ Hash

Alias for #merge!.

#has_value?(value) ⇒ Boolean #value?(value) ⇒ Boolean
Also known as: #has_value?

Returns true if the given value is present for some key in hsh.

h = { "a" => 100, "b" => 200 }
h.has_value?(100)   #=> true
h.has_value?(999)   #=> false

#values ⇒ Array

Returns a new array populated with the values from hsh. See also #keys.

h = { "a" => 100, "b" => 200, "c" => 300 }
h.values   #=> [100, 200, 300]

#values_at(key, ...) ⇒ Array

Return an array containing the values associated with the given keys. Also see #select.

h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" }
h.values_at("cow", "cat")  #=> ["bovine", "feline"]