Creates a new emptyHash where thedefault_value is returned if a key is missing.

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

WARNING When the default value gets returned on a missing key, it isnot stored into the hash under that key. If you want that behaviour, please use the overload with a block.

WARNING The default value is returned as-is. It gets neither duplicated nor cloned. For types with reference semantics this means it will be exactly the same object every time.

hash = Hash(String, Array(Int32)).new([1])
hash["a"][0] = 2
hash["b"] # => [2]

• .new(&block : (Hash(K, V), K -> V)) is an alternative with a block that can return a different default value for each invocation.

Theinitial_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 8. Inputs lower than 8 are ignored.

Reads a Hash from the given pull parser.

Keys are read by invokingfrom_json_object_key? on this hash's key type (K), which must return a value of typeK ornil. Ifnil is returned aJSON::ParseException is raised.

Values are parsed using the regular.new(pull : JSON::PullParser) method.

Creates a new emptyHash.

Creates a new emptyHash with ablock 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

Theinitial_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 8. Inputs lower than 8 are ignored.

Creates a new emptyHash with ablock that handles missing keys.

hash = Hash(String, String).new do |hash, key|
  "some default value"
end

hash.size           # => 0
hash["foo"] = "bar" # => "bar"
hash.size           # => 1
hash["baz"]         # => "some default value"
hash.size           # => 1
hash                # => {"foo" => "bar"}

WARNING When the default block is invoked on a missing key, its return value isnot implicitly stored into the hash under that key. If you want that behaviour, you need to store it explicitly:

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

Theinitial_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 8. Inputs lower than 8 are ignored.

Zips two arrays into aHash, taking keys fromary1 and values fromary2.

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

Compares withother. Returnstrue if all key-value pairs are the same.

Returns the value for the key given bykey. If not found, returns the default value given byHash.new, otherwise raisesKeyError.

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 ofkey to the givenvalue.

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

Returns the value for the key given bykey. If not found, returnsnil. This ignores the default value set byHash.new.

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

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

Empties aHash 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 newHash withoutnil values.

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

Removes allnil value fromself. Returnsself.

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

Makes this hash compare keys using their object identity (object_id) for types that define such method (Reference types, but also structs that might wrap otherReference types and delegate theobject_id method to them).

h1 = {"foo" => 1, "bar" => 2}
h1["fo" + "o"]? # => 1

h1.compare_by_identity
h1.compare_by_identity? # => true
h1["fo" + "o"]?         # => nil # not the same String instance

Returnstrue if this Hash is comparing keys byobject_id.

See#compare_by_identity.

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

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

Deletes the key-value pair and returns the value, else yieldskey 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"

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

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

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

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

Duplicates aHash.

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

The enumeration follows the order the keys were inserted.

Returns an iterator over the hash entries. Which behaves like anIterator returning aTuple consisting of the key and value types.

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

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

The enumeration follows the order the keys were inserted.

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

The enumeration follows the order the keys were inserted.

Returns an iterator over the hash keys. Which behaves like anIterator 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"

The enumeration follows the order the keys were inserted.

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

The enumeration follows the order the keys were inserted.

Returns an iterator over the hash values. Which behaves like anIterator 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"

The enumeration follows the order the keys were inserted.

Returnstrue 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 bykey, or when not found the value given bydefault. This ignores the default value set byHash.new.

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

Returns the value for the key given bykey, 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 returnsnil.

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 returnsnil.

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

Returnstrue when key given bykey exists, otherwisefalse.

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

Returnstrue when value given byvalue exists, otherwisefalse.

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

SeeObject#hash(hasher)

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

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 givenvalue, else raisesKeyError.

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 givenvalue, else yieldsvalue 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 givenvalue, elsenil.

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

Returns a newArray 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 returnsnil.

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 returnsnil.

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

Returns a newHash with the keys and values of this hash andother combined. A value inother 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"}

Adds the contents ofother to this hash. If a key exists in both hashes, the given block is called to determine the value to be used. The block arguments are the key, the value inself and the value inother.

hash = {"a" => 100, "b" => 200}
other = {"b" => 254, "c" => 300}
hash.merge!(other) { |key, v1, v2| v1 + v2 }
hash # => {"a" => 100, "b" => 454, "c" => 300}

Returnstrue ifself is a subset ofother.

Returnstrue ifother is a subset ofself or equals toself.

Sets the value ofkey to the givenvalue.

If a value already exists forkey, that (old) value is returned. Otherwise the given block is invoked withkey and its value is returned.

h = {} of Int32 => String
h.put(1, "one") { "didn't exist" } # => "didn't exist"
h.put(1, "uno") { "didn't exist" } # => "one"
h.put(2, "two") { |key| key.to_s } # => "2"
h                                  # => {1 => "one", 2 => "two"}

Sets the value ofkey to the givenvalue, unless a value forkey already exists.

If a value already exists forkey, that (old) value is returned. Otherwisevalue is returned.

h = {} of Int32 => String
h.put_if_absent(1, "one") # => "one"
h.put_if_absent(1, "uno") # => "one"
h.put_if_absent(2, "two") # => "two"
h                         # => {1 => "one", 2 => "two"}

Sets the value ofkey to the value returned by the given block, unless a value forkey already exists.

If a value already exists forkey, that (old) value is returned. Otherwise the given block is invoked withkey and its value is returned.

h = {} of Int32 => Array(String)
h.put_if_absent(1) { |key| [key.to_s] } # => ["1"]
h.put_if_absent(1) { [] of String }     # => ["1"]
h.put_if_absent(2) { |key| [key.to_s] } # => ["2"]
h                                       # => {1 => ["1"], 2 => ["2"]}

hash.put_if_absent(key) { value } is a more performant alternative to hash[key] ||= value that also works correctly when the hash may contain falsey values.

Rebuilds the hash table based on the current keys.

When using mutable data types as keys, modifying a key after it was inserted into theHash may lead to undefined behaviour. This method re-indexes the hash using the current keys.

Returns a new hash consisting of entries for which the block is falsey.

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}

Returns a newHash without the given keys.

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

Returns a newHash without the given keys.

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

Equivalent toHash#reject, but makes modification on the current object rather than returning a new one. Returnsself.

Removes a list of keys out of hash.

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

Removes a list of keys out of hash.

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

Returns a new hash consisting of entries for which the block is truthy.

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}

Returns a newHash with the given keys.

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

Returns a newHash with the given keys.

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

Equivalent toHash#select but makes modification on the current object rather than returning a new one. Returnsself.

Removes every element except the given ones.

h1 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!({"a", "c"})
h2 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!("a", "c")
h3 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(["a", "c"])
h4 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(Set{"a", "c"})
h1 == h2 == h3 == h4 # => true
h1                   # => {"a" => 1, "c" => 3}

Removes every element except the given ones.

h1 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!({"a", "c"})
h2 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!("a", "c")
h3 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(["a", "c"])
h4 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(Set{"a", "c"})
h1 == h2 == h3 == h4 # => true
h1                   # => {"a" => 1, "c" => 3}

Removes every element except the given ones.

h1 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!({"a", "c"})
h2 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!("a", "c")
h3 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(["a", "c"])
h4 = {"a" => 1, "b" => 2, "c" => 3, "d" => 4}.select!(Set{"a", "c"})
h1 == h2 == h3 == h4 # => true
h1                   # => {"a" => 1, "c" => 3}

Deletes and returns the first key-value pair in the hash, or raisesIndexError 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 returnsnil 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 the number of elements in this Hash.

Returnstrue ifself is a subset ofother or equals toother.

Returnstrue ifother is a subset ofself.

Returns anArray ofTuple(K, V) with key and values belonging to this Hash.

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

The order of the array follows the order the keys were inserted in the Hash.

Returns anArray with the results of runningblock against tuples with key and values belonging to this Hash.

h = {"first_name" => "foo", "last_name" => "bar"}
h.to_a { |_k, v| v.capitalize } # => ["Foo", "Bar"]

The order of the array follows the order the keys were inserted in the Hash.

Returnsself.

Serializes this Hash into JSON.

Keys are serialized by invokingto_json_object_key on them. Values are serialized with the usual#to_json(json : JSON::Builder) method.

Converts to aString.

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. The block yields the key and value.

hash = {:a => 1, :b => 2, :c => 3}
hash.transform_keys { |key| key.to_s }                # => {"a" => 1, "b" => 2, "c" => 3}
hash.transform_keys { |key, value| key.to_s * value } # => {"a" => 1, "bb" => 2, "ccc" => 3}

Destructively transforms all keys using a block. Same as transform_keys but modifies in place. The block cannot change a type of keys. The block yields the key and value.

hash = {"a" => 1, "b" => 2, "c" => 3}
hash.transform_keys! { |key| key.upcase }
hash # => {"A" => 1, "B" => 2, "C" => 3}
hash.transform_keys! { |key, value| key * value }
hash # => {"a" => 1, "bb" => 2, "ccc" => 3}

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

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

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

hash = {:a => 1, :b => 2, :c => 3}
hash.transform_values! { |value| value + 1 }
hash # => {:a => 2, :b => 3, :c => 4}
hash.transform_values! { |value, key| value + key.to_s[0].ord }
hash # => {:a => 99, :b => 101, :c => 103}

See#update for updating asingle value.

Updates the current value ofkey with the value returned by the given block (the current value is used as input for the block).

If no entry forkey is present, but there's a default value (or default block) then that default value is used as input for the given block.

If no entry forkey is present and the hash has no default value, it raisesKeyError.

It returns the value used as input for the given block (ie. the old value if key present, or the default value)

h = {"a" => 0, "b" => 1}
h.update("b") { |v| v + 41 } # => 1
h["b"]                       # => 42

h = Hash(String, Int32).new(40)
h.update("foo") { |v| v + 2 } # => 40
h["foo"]                      # => 42

h = {} of String => Int32
h.update("a") { 42 } # raises KeyError

See#transform_values! for updatingall the values.

Returns only the values as anArray.

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

Returns a tuple populated with the values of the givenkeys, with the same order. Raises if a key is not found.

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