class Hash(K, V)

Creates a new empty Hash with a block for handling missing keys.

proc = ->(hash : Hash(String, Int32), key : String) { hash[key] = key.size }
hash = Hash(String, Int32).new(proc)

hash.size   # => 0
hash["foo"] # => 3
hash.size   # => 1
hash["bar"] = 10
hash["bar"] # => 10

The initial_capacity is useful to avoid unnecessary reallocations of the internal buffer in case of growth. If the number of elements a hash will hold is known, the hash should be initialized with that capacity for improved performance. Otherwise, the default is 11 and inputs less than 11 are ignored.

Creates a new empty Hash with a block that handles missing keys.

hash = Hash(String, Int32).new do |hash, key|
  hash[key] = key.size
end

hash.size   # => 0
hash["foo"] # => 3
hash.size   # => 1
hash["bar"] = 10
hash["bar"] # => 10

The initial_capacity is useful to avoid unnecessary reallocations of the internal buffer in case of growth. If the number of elements a hash will hold is known, the hash should be initialized with that capacity for improved performance. Otherwise, the default is 11 and inputs less than 11 are ignored.

Creates a new empty Hash where the default_value is returned if a key is missing.

inventory = Hash(String, Int32).new(0)
inventory["socks"] = 3
inventory["pickles"] # => 0

NOTE The default value is passed by reference:

arr = [1, 2, 3]
hash = Hash(String, Array(Int32)).new(arr)
hash["3"][1] = 4
arr # => [1, 4, 3]

The initial_capacity is useful to avoid unnecessary reallocations of the internal buffer in case of growth. If the number of elements a hash will hold is known, the hash should be initialized with that capacity for improved performance. Otherwise, the default is 11 and inputs less than 11 are ignored.

Zips two arrays into a Hash, taking keys from ary1 and values from ary2.

Hash.zip(["key1", "key2", "key3"], ["value1", "value2", "value3"])
# => {"key1" => "value1", "key2" => "value2", "key3" => "value3"}

Compares with other. Returns true if all key-value pairs are the same.

Returns the value for the key given by key. If not found, returns the default value given by Hash.new, otherwise raises KeyError.

h = {"foo" => "bar"}
h["foo"] # => "bar"

h = Hash(String, String).new("bar")
h["foo"] # => "bar"

h = Hash(String, String).new { "bar" }
h["foo"] # => "bar"

h = Hash(String, String).new
h["foo"] # raises KeyError

Sets the value of key to the given value.

h = {} of String => String
h["foo"] = "bar"
h["foo"] # => "bar"

Returns the value for the key given by key. If not found, returns nil. This ignores the default value set by Hash.new.

h = {"foo" => "bar"}
h["foo"]? # => "bar"
h["bar"]? # => nil

h = Hash(String, String).new("bar")
h["foo"]? # => nil

Empties a Hash and returns it.

hash = {"foo" => "bar"}
hash.clear # => {}

Similar to #dup, but duplicates the values as well.

hash_a = {"foobar" => {"foo" => "bar"}}
hash_b = hash_a.clone
hash_b["foobar"]["foo"] = "baz"
hash_a # => {"foobar" => {"foo" => "bar"}}

Returns new Hash without nil values.

hash = {"hello" => "world", "foo" => nil}
hash.compact # => {"hello" => "world"}

Removes all nil value from self. Returns nil if no changes were made.

hash = {"hello" => "world", "foo" => nil}
hash.compact! # => {"hello" => "world"}
hash.compact! # => nil

Deletes the key-value pair and returns the value, otherwise returns nil.

h = {"foo" => "bar"}
h.delete("foo")     # => "bar"
h.fetch("foo", nil) # => nil

Deletes the key-value pair and returns the value, else yields key with given block.

h = {"foo" => "bar"}
h.delete("foo") { |key| "#{key} not found" } # => "bar"
h.fetch("foo", nil)                          # => nil
h.delete("baz") { |key| "#{key} not found" } # => "baz not found"

Deletes each key-value pair for which the given block returns true.

h = {"foo" => "bar", "fob" => "baz", "bar" => "qux"}
h.delete_if { |key, value| key.starts_with?("fo") }
h # => { "bar" => "qux" }

Traverses the depth of a structure and returns the value, otherwise raises KeyError.

h = {"a" => {"b" => [10, 20, 30]}}
h.dig "a", "b"                # => [10, 20, 30]
h.dig "a", "b", "c", "d", "e" # raises KeyError

Traverses the depth of a structure and returns the value. Returns nil if not found.

h = {"a" => {"b" => [10, 20, 30]}}
h.dig? "a", "b"                # => [10, 20, 30]
h.dig? "a", "b", "c", "d", "e" # => nil

Duplicates a Hash.

hash_a = {"foo" => "bar"}
hash_b = hash_a.dup
hash_b.merge!({"baz" => "qux"})
hash_a # => {"foo" => "bar"}

Calls the given block for each key-value pair and passes in the key and the value.

h = {"foo" => "bar"}

h.each do |key, value|
  key   # => "foo"
  value # => "bar"
end

h.each do |key_and_value|
  key_and_value # => {"foo", "bar"}
end

Returns an iterator over the hash entries. Which behaves like an Iterator returning a Tuple consisting of the key and value types.

hsh = {"foo" => "bar", "baz" => "qux"}
iterator = hsh.each

iterator.next # => {"foo", "bar"}
iterator.next # => {"baz", "qux"}

Returns an iterator over the hash keys. Which behaves like an Iterator consisting of the key's types.

hsh = {"foo" => "bar", "baz" => "qux"}
iterator = hsh.each_key

key = iterator.next
key # => "foo"

key = iterator.next
key # => "baz"

Calls the given block for each key-value pair and passes in the key.

h = {"foo" => "bar"}
h.each_key do |key|
  key # => "foo"
end

Calls the given block for each key-value pair and passes in the value.

h = {"foo" => "bar"}
h.each_value do |value|
  value # => "bar"
end

Returns an iterator over the hash values. Which behaves like an Iterator consisting of the value's types.

hsh = {"foo" => "bar", "baz" => "qux"}
iterator = hsh.each_value

value = iterator.next
value # => "bar"

value = iterator.next
value # => "qux"

Returns true when hash contains no key-value pairs.

h = Hash(String, String).new
h.empty? # => true

h = {"foo" => "bar"}
h.empty? # => false

Returns the value for the key given by key, or when not found the value given by default. This ignores the default value set by Hash.new.

h = {"foo" => "bar"}
h.fetch("foo", "foo") # => "bar"
h.fetch("bar", "foo") # => "foo"

Returns the value for the key given by key, or when not found calls the given block with the key.

h = {"foo" => "bar"}
h.fetch("foo") { "default value" }  # => "bar"
h.fetch("bar") { "default value" }  # => "default value"
h.fetch("bar") { |key| key.upcase } # => "BAR"

Returns the first key in the hash.

Returns the first key if it exists, or returns nil.

hash = {"foo1" => "bar1", "foz2" => "baz2"}
hash.first_key? # => "foo1"
hash.clear
hash.first_key? # => nil

Returns the first value in the hash.

Returns the first value if it exists, or returns nil.

hash = {"foo1" => "bar1", "foz2" => "baz2"}
hash.first_value? # => "bar1"
hash.clear
hash.first_value? # => nil

Returns true when key given by key exists, otherwise false.

h = {"foo" => "bar"}
h.has_key?("foo") # => true
h.has_key?("bar") # => false

Returns true when value given by value exists, otherwise false.

h = {"foo" => "bar"}
h.has_value?("foo") # => false
h.has_value?("bar") # => true

See Object#hash(hasher)

Inverts keys and values. If there are duplicated values, the last key becomes the new value.

{"foo" => "bar"}.invert                 # => {"bar" => "foo"}
{"foo" => "bar", "baz" => "bar"}.invert # => {"bar" => "baz"}

Returns a key with the given value, else yields value with the given block.

hash = {"foo" => "bar"}
hash.key_for("bar") { |value| value.upcase } # => "foo"
hash.key_for("qux") { |value| value.upcase } # => "QUX"

Returns a key with the given value, else raises KeyError.

hash = {"foo" => "bar", "baz" => "qux"}
hash.key_for("bar")    # => "foo"
hash.key_for("qux")    # => "baz"
hash.key_for("foobar") # raises KeyError (Missing hash key for value: foobar)

Returns a key with the given value, else nil.

hash = {"foo" => "bar", "baz" => "qux"}
hash.key_for?("bar")    # => "foo"
hash.key_for?("qux")    # => "baz"
hash.key_for?("foobar") # => nil

Returns the index of the given key, or nil when not found. The keys are ordered based on when they were inserted.

h = {"foo" => "bar", "baz" => "qux"}
h.key_index("foo") # => 0
h.key_index("qux") # => nil

Returns a new Array with all the keys.

h = {"foo" => "bar", "baz" => "bar"}
h.keys # => ["foo", "baz"]

Returns the last key in the hash.

Returns the last key if it exists, or returns nil.

hash = {"foo1" => "bar1", "foz2" => "baz2"}
hash.last_key? # => "foz2"
hash.clear
hash.last_key? # => nil

Returns the last value in the hash.

Returns the last value if it exists, or returns nil.

hash = {"foo1" => "bar1", "foz2" => "baz2"}
hash.last_value? # => "baz2"
hash.clear
hash.last_value? # => nil

Returns a new Hash with the keys and values of this hash and other combined. A value in other takes precedence over the one in this hash.

hash = {"foo" => "bar"}
hash.merge({"baz" => "qux"})
# => {"foo" => "bar", "baz" => "qux"}
hash
# => {"foo" => "bar"}

Similar to #merge, but the receiver is modified.

hash = {"foo" => "bar"}
hash.merge!({"baz" => "qux"})
hash # => {"foo" => "bar", "baz" => "qux"}

Returns a new Hash without the given keys.

{"a" => 1, "b" => 2, "c" => 3, "d" => 4}.reject("a", "c") # => {"b" => 2, "d" => 4}

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

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

Removes a list of keys out of hash.

h = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.reject!("a", "c")
h # => {"b" => 2, "d" => 4}

Equivalent to Hash#reject, but makes modification on the current object rather that returning a new one. Returns nil if no changes were made.

Returns a new Hash with the given keys.

{"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select("a", "c") # => {"a" => 1, "c" => 3}

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

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}

Removes every element except the given ones.

h = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!("a", "c")
h # => {"a" => 1, "c" => 3}

Equivalent to Hash#select but makes modification on the current object rather that returning a new one. Returns nil if no changes were made

Deletes and returns the first key-value pair in the hash, or raises IndexError if the hash is empty.

hash = {"foo" => "bar", "baz" => "qux"}
hash.shift # => {"foo", "bar"}
hash       # => {"baz" => "qux"}

hash = {} of String => String
hash.shift # raises IndexError

Deletes and returns the first key-value pair in the hash. Yields to the given block if the hash is empty.

hash = {"foo" => "bar", "baz" => "qux"}
hash.shift { true } # => {"foo", "bar"}
hash                # => {"baz" => "qux"}

hash = {} of String => String
hash.shift { true } # => true
hash                # => {}

Same as #shift, but returns nil if the hash is empty.

hash = {"foo" => "bar", "baz" => "qux"}
hash.shift? # => {"foo", "bar"}
hash        # => {"baz" => "qux"}

hash = {} of String => String
hash.shift? # => nil

Returns self.

Converts to a String.

h = {"foo" => "bar"}
h.to_s       # => "{\"foo\" => \"bar\"}"
h.to_s.class # => String

Returns a new hash with all keys converted using the block operation. The block can change a type of keys.

hash = {:a => 1, :b => 2, :c => 3}
hash.transform_keys { |key| key.to_s } # => {"A" => 1, "B" => 2, "C" => 3}

Returns a new hash with the results of running block once for every value. The block can change a type of values.

hash = {:a => 1, :b => 2, :c => 3}
hash.transform_values { |value| value + 1 } # => {:a => 2, :b => 3, :c => 4}

Destructively transforms all values using a block. Same as transform_values but modifies in place. The block cannot change a type of values.

hash = {:a => 1, :b => 2, :c => 3}
hash.transform_values! { |value| value + 1 }
hash # => {:a => 2, :b => 3, :c => 4}

Returns only the values as an Array.

h = {"foo" => "bar", "baz" => "qux"}
h.values # => ["bar", "qux"]

Returns a tuple populated with the elements at the given indexes. Raises if any index is invalid.

{"a" => 1, "b" => 2, "c" => 3, "d" => 4}.values_at("a", "c") # => {1, 3}