class Hash(K, V)

Overview

A Hash represents a mapping of keys to values.

See the official docs for the basics.

Defined in:

hash.cr
json/to_json.cr
yaml/to_yaml.cr

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

! !, ==(other)
==(other : self)
==
, hash hash, inspect(io : IO) : Nil inspect, nil? nil?, object_id object_id, same?(other : Nil)
same?(other : Reference)
same?
, to_s(io : IO) : Nil to_s

Instance methods inherited from class Object

! !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other) ===, =~(other) =~, class class, clone clone, crystal_type_id crystal_type_id, dup dup, hash hash, inspect
inspect(io : IO)
inspect
, itself itself, not_nil! not_nil!, tap(&block) tap, to_json to_json, to_pretty_json(io : IO)
to_pretty_json
to_pretty_json
, to_s
to_s(io : IO)
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&block) try

Class methods inherited from class Object

==(other : Class) ==, ===(other) ===, cast(other) : self cast, from_json(string_or_io) from_json, from_yaml(string : String) from_yaml, hash hash, inspect(io) inspect, name : String name, to_s(io) to_s

Class Method Detail

def self.new(pull : JSON::PullParser) #

[View source]
def self.new(pull : YAML::PullParser) #

[View source]
def self.new(comparator) #

[View source]
def self.new(pull : YAML::PullParser, &block) #

[View source]
def self.new(comp = StandardComparator, initial_capacity = nil, &block : Hash(K, V), K -> V) #

[View source]
def self.new(default_value : V, comp = StandardComparator, initial_capacity = nil) #

[View source]
def self.zip(ary1 : Array(K), ary2 : Array(V)) #

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

Hash.zip(["foo", "bar"], ["baz", "qux"]) # => {"foo" => "baz", "baz" => "quz"}

[View source]
def self.new(block = nil : Hash(K, V), K -> V | Nil, comp = StandardComparator, initial_capacity = nil) #

[View source]

Instance Method Detail

def ==(other : Hash) #

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


[View source]
def [](key) #

[View source]
def []=(key : K, value : V) #

Sets the value of key to the given value.

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

[View source]
def []?(key) #

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

[View source]
def all?(&block) #

Yields all key-value pairs to the given block, and returns true if the block returns a truthy value for all key-value pairs, else false.

hash = {
  "foo":   "bar",
  "hello": "world",
}
hash.all? { |k, v| v.is_a? String } # => true
hash.all? { |k, v| v.size == 3 }    # => false

[View source]
def any? #

Returns true if a Hash has any key-value pair.


[View source]
def any?(&block) #

Yields all key-value pairs to the given block, and returns true if the block returns a truthy value for any key-value pair, else false.

hash = {
  "foo":   "bar",
  "hello": "world",
}
hash.any? { |k, v| v.is_a? Int } # => false
hash.any? { |k, v| v.size == 3 } # => true

[View source]
def clear #

Empties a Hash and returns it.

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

[View source]
def clone #

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"}}

[View source]
def delete(key) #

Deletes the key-value pair and returns the value.

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

[View source]
def delete_if(&block) #

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" }

[View source]
def dup #

Duplicates a Hash.

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

[View source]
def each(&block) #

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

[View source]
def each #

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

entry = iterator.next
entry[0] # => "foo"
entry[1] # => "bar"

entry = iterator.next
entry[0] # => "baz"
entry[1] # => "qux"

[View source]
def each_key(&block) #

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

[View source]
def each_key #

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"

[View source]
def each_value #

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"

[View source]
def each_value(&block) #

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

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

[View source]
def each_with_index(offset = 0, &block) #

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

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

h.each_with_index do |key, value, index|
  key   # => "foo"
  value # => "bar"
  index # => 0
end

h.each_with_index(3) do |key, value, index|
  key   # => "foo"
  value # => "bar"
  index # => 3
end

[View source]
def each_with_object(memo, &block) #

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

evens = (1..10).each_with_object([] of Int32) { |i, a| a << i*2 }
# => [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

[View source]
def empty? #

Returns true when hash contains no key-value pairs.

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

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

[View source]
def fetch(key, default) #

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"

[View source]
def fetch(key) #

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

[View source]
def fetch(key, &block) #

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") { |key| key.upcase } # => "bar"
h.fetch("bar") { |key| key.upcase } # => "BAR"

[View source]
def first #

Returns a Tuple of the first key-value pair in the hash.


[View source]
def first_key #

Returns the first key in the hash.


[View source]
def first_key? #

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

hash = {"foo": "bar"}
hash.first_key? # => "foo"
hash.clear
hash.first_key? # => nil

[View source]
def first_value #

Returns the first value in the hash.


[View source]
def first_value? #

Similar to #first_key?, but returns its value.


[View source]
def has_key?(key) #

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

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

[View source]
def hash #

See Object#hash.

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

[View source]
def inspect(io : IO) #

[View source]
def invert #

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"}

[View source]
def key(value, &block) #

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

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

[View source]
def key(value) #

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

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

[View source]
def key?(value) #

Returns the first key with the given value, else nil.

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

[View source]
def key_index(key) #

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

[View source]
def keys #

Returns a new Array with all the keys.

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

[View source]
def map(&block : K, V -> U) #

Returns an Array populated with the results of each iteration in the given block.

h = {"foo" => "bar", "baz" => "qux"}
h.map { |k, v| v } # => ["bar", "qux"]

[View source]
def merge(other : Hash(L, W), &block : K, V, W -> V | W) #

[View source]
def merge(other : Hash(L, W)) #

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"}

[View source]
def merge!(other : Hash(K, V), &block : K, V, V -> V) #

[View source]
def merge!(other : Hash(K, V)) #

Similar to #merge, but the receiver is modified.

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

[View source]
def reduce(memo, &block) #

Yields all key-value pairs to the given block with a initial value memo, which is replaced with each returned value in iteration. Returns the last value of memo.

prices = {
  "apple":  5,
  "lemon":  3,
  "papaya": 6,
  "orange": 4,
}

prices.reduce("apple") do |highest, item, price|
  if price > prices[highest]
    item
  else
    highest
  end
end
# => "papaya"

[View source]
def rehash #

[View source]
def reject(*keys) #

Returns a new Hash without the given keys.

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

[View source]
def reject(&block : K, V -> U) #

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}

[View source]
def reject!(*keys) #

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}

[View source]
def reject!(&block : K, V -> U) #

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


[View source]
def select(*keys) #

Returns a new Hash with the given keys.

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

[View source]
def select(&block : K, V -> U) #

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}

[View source]
def select!(&block : K, V -> U) #

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


[View source]
def select!(*keys) #

Removes every element except the given ones.

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

[View source]
def shift(&block) #

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                # => {}

[View source]
def shift #

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 # => Index out of bounds (IndexError)

[View source]
def shift? #

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

[View source]
def size #

[View source]
def to_a #

Returns a new Array of tuples populated with each key-value pair.

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

[View source]
def to_h #

Returns self.


[View source]
def to_json(io) #

[View source]
def to_s(io : IO) #

Converts to a String.

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

[View source]
def to_yaml(yaml : YAML::Generator) #

[View source]
def values #

Returns only the values as an Array.

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

[View source]
def values_at(*indexes : K) #

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}

[View source]