A Hash
is a collection of key-value pairs. It is similar to an
Array
, except that indexing is done via arbitrary keys of any
object type, not an integer index. Hashes enumerate their values in the
order that the corresponding keys were inserted.
Hashes have a default value that is returned when accessing keys
that do not exist in the hash. By default, that value is nil
.
Creates a new hash populated with the given objects. Equivalent to the
literal { key, value, ... }
. Keys and values
occur in pairs, so there must be an even number of arguments.
Hash["a", 100, "b", 200] #=> {"a"=>100, "b"=>200} Hash["a" => 100, "b" => 200] #=> {"a"=>100, "b"=>200} { "a" => 100, "b" => 200 } #=> {"a"=>100, "b"=>200}
static VALUE rb_hash_s_create(int argc, VALUE *argv, VALUE klass) { VALUE hash, tmp; int i; if (argc == 1) { tmp = rb_hash_s_try_convert(Qnil, argv[0]); if (!NIL_P(tmp)) { hash = hash_alloc(klass); if (RHASH(tmp)->ntbl) { RHASH(hash)->ntbl = st_copy(RHASH(tmp)->ntbl); } return hash; } tmp = rb_check_array_type(argv[0]); if (!NIL_P(tmp)) { long i; hash = hash_alloc(klass); for (i = 0; i < RARRAY_LEN(tmp); ++i) { VALUE v = rb_check_array_type(RARRAY_PTR(tmp)[i]); VALUE key, val = Qnil; if (NIL_P(v)) continue; switch (RARRAY_LEN(v)) { case 2: val = RARRAY_PTR(v)[1]; case 1: key = RARRAY_PTR(v)[0]; rb_hash_aset(hash, key, val); } } return hash; } } if (argc % 2 != 0) { rb_raise(rb_eArgError, "odd number of arguments for Hash"); } hash = hash_alloc(klass); for (i=0; i<argc; i+=2) { rb_hash_aset(hash, argv[i], argv[i + 1]); } return 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"]
static VALUE rb_hash_initialize(int argc, VALUE *argv, VALUE hash) { VALUE ifnone; rb_hash_modify(hash); if (rb_block_given_p()) { if (argc > 0) { rb_raise(rb_eArgError, "wrong number of arguments"); } RHASH(hash)->ifnone = rb_block_proc(); FL_SET(hash, HASH_PROC_DEFAULT); } else { rb_scan_args(argc, argv, "01", &ifnone); RHASH(hash)->ifnone = ifnone; } return 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
static VALUE rb_hash_s_try_convert(VALUE dummy, VALUE hash) { return rb_check_convert_type(hash, T_HASH, "Hash", "to_hash"); }
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
static VALUE rb_hash_equal(VALUE hash1, VALUE hash2) { return hash_equal(hash1, hash2, Qfalse); }
Element Reference—Retrieves the value object corresponding to the
key object. If not found, returns the a default value (see
Hash::new
for details).
h = { "a" => 100, "b" => 200 } h["a"] #=> 100 h["c"] #=> nil
VALUE rb_hash_aref(VALUE hash, VALUE key) { VALUE val; if (!RHASH(hash)->ntbl || !st_lookup(RHASH(hash)->ntbl, key, &val)) { return rb_funcall(hash, id_default, 1, key); } return val; }
Element Assignment—Associates the value given by value with the
key given by key. key should not have its value changed
while it is in use as a key (a String
passed as a key will be
duplicated and frozen).
h = { "a" => 100, "b" => 200 } h["a"] = 9 h["c"] = 4 h #=> {"a"=>9, "b"=>200, "c"=>4}
VALUE rb_hash_aset(VALUE hash, VALUE key, VALUE val) { rb_hash_modify(hash); if (RHASH(hash)->ntbl->type == &identhash || TYPE(key) != T_STRING || st_lookup(RHASH(hash)->ntbl, key, 0)) { st_insert(RHASH(hash)->ntbl, key, val); } else { st_add_direct(RHASH(hash)->ntbl, rb_str_new4(key), val); } return val; }
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
VALUE rb_hash_assoc(VALUE hash, VALUE obj) { VALUE args[2]; args[0] = obj; args[1] = Qnil; rb_hash_foreach(hash, assoc_i, (st_data_t)args); return args[1]; }
Removes all key-value pairs from hsh.
h = { "a" => 100, "b" => 200 } #=> {"a"=>100, "b"=>200} h.clear #=> {}
static VALUE rb_hash_clear(VALUE hash) { rb_hash_modify_check(hash); if (!RHASH(hash)->ntbl) return hash; if (RHASH(hash)->ntbl->num_entries > 0) { if (RHASH(hash)->iter_lev > 0) rb_hash_foreach(hash, clear_i, 0); else st_clear(RHASH(hash)->ntbl); } return hash; }
Makes hsh to 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"] #=> nil # different objects. h1[:c] #=> "c" # same symbols are all same.
static VALUE rb_hash_compare_by_id(VALUE hash) { rb_hash_modify(hash); RHASH(hash)->ntbl->type = &identhash; rb_hash_rehash(hash); return hash; }
Returns true
if hsh will compare its keys by their
identity. Also see Hash#compare_by_identity
.
static VALUE rb_hash_compare_by_id_p(VALUE hash) { if (!RHASH(hash)->ntbl) return Qfalse; if (RHASH(hash)->ntbl->type == &identhash) { return Qtrue; } return Qfalse; }
Returns the default value, the value that would be returned by hsh if key did not exist in hsh. See
also Hash::new
and Hash#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
static VALUE rb_hash_default(int argc, VALUE *argv, VALUE hash) { VALUE key; rb_scan_args(argc, argv, "01", &key); if (FL_TEST(hash, HASH_PROC_DEFAULT)) { if (argc == 0) return Qnil; return rb_funcall(RHASH(hash)->ifnone, id_yield, 2, hash, key); } return RHASH(hash)->ifnone; }
Sets the default value, the value returned for a key that does not exist in
the hash. It is not possible to set the a 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>
static VALUE rb_hash_set_default(VALUE hash, VALUE ifnone) { rb_hash_modify(hash); RHASH(hash)->ifnone = ifnone; FL_UNSET(hash, HASH_PROC_DEFAULT); return ifnone; }
If Hash::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]
static VALUE rb_hash_default_proc(VALUE hash) { if (FL_TEST(hash, HASH_PROC_DEFAULT)) { return RHASH(hash)->ifnone; } return Qnil; }
Sets the default proc to be executed on each key lookup.
h.default_proc = proc do |hash, key| hash[key] = key + key end h[2] #=> 4 h["cat"] #=> "catcat"
static VALUE rb_hash_set_default_proc(VALUE hash, VALUE proc) { VALUE b; rb_hash_modify(hash); b = rb_check_convert_type(proc, T_DATA, "Proc", "to_proc"); if (NIL_P(b) || !rb_obj_is_proc(b)) { rb_raise(rb_eTypeError, "wrong default_proc type %s (expected Proc)", rb_obj_classname(proc)); } proc = b; RHASH(hash)->ifnone = proc; FL_SET(hash, HASH_PROC_DEFAULT); return proc; }
Deletes and returns a key-value pair 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"
VALUE rb_hash_delete(VALUE hash, VALUE key) { VALUE val; rb_hash_modify(hash); val = rb_hash_delete_key(hash, key); if (val != Qundef) return val; if (rb_block_given_p()) { return rb_yield(key); } return Qnil; }
Deletes every key-value pair from hsh for which block
evaluates to true
.
h = { "a" => 100, "b" => 200, "c" => 300 } h.delete_if {|key, value| key >= "b" } #=> {"a"=>100}
VALUE rb_hash_delete_if(VALUE hash) { RETURN_ENUMERATOR(hash, 0, 0); rb_hash_modify(hash); rb_hash_foreach(hash, delete_if_i, hash); return hash; }
Calls block once for each key in hsh, passing the key-value pair as parameters.
h = { "a" => 100, "b" => 200 } h.each {|key, value| puts "#{key} is #{value}" }
produces:
a is 100 b is 200
static VALUE rb_hash_each_pair(VALUE hash) { RETURN_ENUMERATOR(hash, 0, 0); rb_hash_foreach(hash, each_pair_i, 0); return hash; }
Calls block once for each key in hsh, passing the key as a parameter.
h = { "a" => 100, "b" => 200 } h.each_key {|key| puts key }
produces:
a b
static VALUE rb_hash_each_key(VALUE hash) { RETURN_ENUMERATOR(hash, 0, 0); rb_hash_foreach(hash, each_key_i, 0); return hash; }
Calls block once for each key in hsh, passing the key-value pair as parameters.
h = { "a" => 100, "b" => 200 } h.each {|key, value| puts "#{key} is #{value}" }
produces:
a is 100 b is 200
static VALUE rb_hash_each_pair(VALUE hash) { RETURN_ENUMERATOR(hash, 0, 0); rb_hash_foreach(hash, each_pair_i, 0); return hash; }
Calls block once for each key in hsh, passing the value as a parameter.
h = { "a" => 100, "b" => 200 } h.each_value {|value| puts value }
produces:
100 200
static VALUE rb_hash_each_value(VALUE hash) { RETURN_ENUMERATOR(hash, 0, 0); rb_hash_foreach(hash, each_value_i, 0); return hash; }
Returns true
if hsh contains no key-value pairs.
{}.empty? #=> true
static VALUE rb_hash_empty_p(VALUE hash) { return RHASH_EMPTY_P(hash) ? Qtrue : Qfalse; }
Returns true
if hash and other are both
hashes with the same content.
static VALUE rb_hash_eql(VALUE hash1, VALUE hash2) { return hash_equal(hash1, hash2, Qtrue); }
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
static VALUE rb_hash_fetch_m(int argc, VALUE *argv, VALUE hash) { VALUE key, if_none; VALUE val; long block_given; rb_scan_args(argc, argv, "11", &key, &if_none); block_given = rb_block_given_p(); if (block_given && argc == 2) { rb_warn("block supersedes default value argument"); } if (!RHASH(hash)->ntbl || !st_lookup(RHASH(hash)->ntbl, key, &val)) { if (block_given) return rb_yield(key); if (argc == 1) { rb_raise(rb_eKeyError, "key not found"); } return if_none; } return val; }
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. If 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"]
static VALUE rb_hash_flatten(int argc, VALUE *argv, VALUE hash) { VALUE ary, tmp; ary = rb_hash_to_a(hash); if (argc == 0) { argc = 1; tmp = INT2FIX(1); argv = &tmp; } rb_funcall2(ary, rb_intern("flatten!"), argc, argv); return ary; }
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
static VALUE rb_hash_has_key(VALUE hash, VALUE key) { if (!RHASH(hash)->ntbl) return Qfalse; if (st_lookup(RHASH(hash)->ntbl, key, 0)) { return Qtrue; } return Qfalse; }
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
static VALUE rb_hash_has_value(VALUE hash, VALUE val) { VALUE data[2]; data[0] = Qfalse; data[1] = val; rb_hash_foreach(hash, rb_hash_search_value, (st_data_t)data); return data[0]; }
Compute a hash-code for this hash. Two hashes with the same content will
have the same hash code (and will compare using eql?
).
static VALUE rb_hash_hash(VALUE hash) { return rb_exec_recursive(recursive_hash, hash, 0); }
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
static VALUE rb_hash_has_key(VALUE hash, VALUE key) { if (!RHASH(hash)->ntbl) return Qfalse; if (st_lookup(RHASH(hash)->ntbl, key, 0)) { return Qtrue; } return Qfalse; }
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}
static VALUE rb_hash_replace(VALUE hash, VALUE hash2) { hash2 = to_hash(hash2); if (hash == hash2) return hash; rb_hash_clear(hash); rb_hash_foreach(hash2, replace_i, hash); RHASH(hash)->ifnone = RHASH(hash2)->ifnone; if (FL_TEST(hash2, HASH_PROC_DEFAULT)) { FL_SET(hash, HASH_PROC_DEFAULT); } else { FL_UNSET(hash, HASH_PROC_DEFAULT); } return hash; }
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}"
static VALUE rb_hash_inspect(VALUE hash) { if (RHASH_EMPTY_P(hash)) return rb_usascii_str_new2("{}"); return rb_exec_recursive(inspect_hash, hash, 0); }
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"}
static VALUE rb_hash_invert(VALUE hash) { VALUE h = rb_hash_new(); rb_hash_foreach(hash, rb_hash_invert_i, h); return h; }
Returns the key for a given value. If not found, returns nil
.
h = { "a" => 100, "b" => 200 } h.key(200) #=> "b" h.key(999) #=> nil
static VALUE rb_hash_key(VALUE hash, VALUE value) { VALUE args[2]; args[0] = value; args[1] = Qnil; rb_hash_foreach(hash, key_i, (st_data_t)args); return args[1]; }
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
static VALUE rb_hash_has_key(VALUE hash, VALUE key) { if (!RHASH(hash)->ntbl) return Qfalse; if (st_lookup(RHASH(hash)->ntbl, key, 0)) { return Qtrue; } return Qfalse; }
Returns a new array populated with the keys from this hash. See also
Hash#values
.
h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 } h.keys #=> ["a", "b", "c", "d"]
static VALUE rb_hash_keys(VALUE hash) { VALUE ary; ary = rb_ary_new(); rb_hash_foreach(hash, keys_i, ary); return ary; }
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
static VALUE rb_hash_size(VALUE hash) { if (!RHASH(hash)->ntbl) return INT2FIX(0); return INT2FIX(RHASH(hash)->ntbl->num_entries); }
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
static VALUE rb_hash_has_key(VALUE hash, VALUE key) { if (!RHASH(hash)->ntbl) return Qfalse; if (st_lookup(RHASH(hash)->ntbl, key, 0)) { return Qtrue; } return Qfalse; }
Returns a new hash containing the contents of other_hash and the contents of hsh, overwriting entries in hsh with duplicate keys with those from 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}
static VALUE rb_hash_merge(VALUE hash1, VALUE hash2) { return rb_hash_update(rb_obj_dup(hash1), hash2); }
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}
static VALUE rb_hash_update(VALUE hash1, VALUE hash2) { hash2 = to_hash(hash2); if (rb_block_given_p()) { rb_hash_foreach(hash2, rb_hash_update_block_i, hash1); } else { rb_hash_foreach(hash2, rb_hash_update_i, hash1); } return hash1; }
Searches through the hash comparing obj with the value using
==
. Returns the first key-value pair (two elements 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
VALUE rb_hash_rassoc(VALUE hash, VALUE obj) { VALUE args[2]; args[0] = obj; args[1] = Qnil; rb_hash_foreach(hash, rassoc_i, (st_data_t)args); return args[1]; }
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 Hash#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
static VALUE rb_hash_rehash(VALUE hash) { st_table *tbl; if (RHASH(hash)->iter_lev > 0) { rb_raise(rb_eRuntimeError, "rehash during iteration"); } rb_hash_modify_check(hash); if (!RHASH(hash)->ntbl) return hash; tbl = st_init_table_with_size(RHASH(hash)->ntbl->type, RHASH(hash)->ntbl->num_entries); rb_hash_foreach(hash, rb_hash_rehash_i, (st_data_t)tbl); st_free_table(RHASH(hash)->ntbl); RHASH(hash)->ntbl = tbl; return hash; }
Same as Hash#delete_if
, but works on (and returns) a copy of
the hsh. Equivalent to hsh.dup.delete_if
.
static VALUE rb_hash_reject(VALUE hash) { return rb_hash_delete_if(rb_obj_dup(hash)); }
Equivalent to Hash#delete_if
, but returns nil
if
no changes were made.
VALUE rb_hash_reject_bang(VALUE hash) { int n; RETURN_ENUMERATOR(hash, 0, 0); if (!RHASH(hash)->ntbl) return Qnil; n = RHASH(hash)->ntbl->num_entries; rb_hash_delete_if(hash); if (n == RHASH(hash)->ntbl->num_entries) return Qnil; return 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}
static VALUE rb_hash_replace(VALUE hash, VALUE hash2) { hash2 = to_hash(hash2); if (hash == hash2) return hash; rb_hash_clear(hash); rb_hash_foreach(hash2, replace_i, hash); RHASH(hash)->ifnone = RHASH(hash2)->ifnone; if (FL_TEST(hash2, HASH_PROC_DEFAULT)) { FL_SET(hash, HASH_PROC_DEFAULT); } else { FL_UNSET(hash, HASH_PROC_DEFAULT); } return hash; }
Returns a new hash consisting of entries 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}
VALUE rb_hash_select(VALUE hash) { VALUE result; RETURN_ENUMERATOR(hash, 0, 0); result = rb_hash_new(); rb_hash_foreach(hash, select_i, result); return result; }
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"}
static VALUE rb_hash_shift(VALUE hash) { struct shift_var var; rb_hash_modify(hash); var.key = Qundef; rb_hash_foreach(hash, RHASH(hash)->iter_lev > 0 ? shift_i_safe : shift_i, (st_data_t)&var); if (var.key != Qundef) { if (RHASH(hash)->iter_lev > 0) { rb_hash_delete_key(hash, var.key); } return rb_assoc_new(var.key, var.val); } else if (FL_TEST(hash, HASH_PROC_DEFAULT)) { return rb_funcall(RHASH(hash)->ifnone, id_yield, 2, hash, Qnil); } else { return RHASH(hash)->ifnone; } }
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
static VALUE rb_hash_size(VALUE hash) { if (!RHASH(hash)->ntbl) return INT2FIX(0); return INT2FIX(RHASH(hash)->ntbl->num_entries); }
Element Assignment—Associates the value given by value with the
key given by key. key should not have its value changed
while it is in use as a key (a String
passed as a key will be
duplicated and frozen).
h = { "a" => 100, "b" => 200 } h["a"] = 9 h["c"] = 4 h #=> {"a"=>9, "b"=>200, "c"=>4}
VALUE rb_hash_aset(VALUE hash, VALUE key, VALUE val) { rb_hash_modify(hash); if (RHASH(hash)->ntbl->type == &identhash || TYPE(key) != T_STRING || st_lookup(RHASH(hash)->ntbl, key, 0)) { st_insert(RHASH(hash)->ntbl, key, val); } else { st_add_direct(RHASH(hash)->ntbl, rb_str_new4(key), val); } return val; }
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]]
static VALUE rb_hash_to_a(VALUE hash) { VALUE ary; ary = rb_ary_new(); rb_hash_foreach(hash, to_a_i, ary); OBJ_INFECT(ary, hash); return ary; }
Returns self.
static VALUE rb_hash_to_hash(VALUE hash) { return hash; }
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}"
static VALUE rb_hash_inspect(VALUE hash) { if (RHASH_EMPTY_P(hash)) return rb_usascii_str_new2("{}"); return rb_exec_recursive(inspect_hash, hash, 0); }
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}
static VALUE rb_hash_update(VALUE hash1, VALUE hash2) { hash2 = to_hash(hash2); if (rb_block_given_p()) { rb_hash_foreach(hash2, rb_hash_update_block_i, hash1); } else { rb_hash_foreach(hash2, rb_hash_update_i, hash1); } return hash1; }
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
static VALUE rb_hash_has_value(VALUE hash, VALUE val) { VALUE data[2]; data[0] = Qfalse; data[1] = val; rb_hash_foreach(hash, rb_hash_search_value, (st_data_t)data); return data[0]; }
Returns a new array populated with the values from hsh. See also
Hash#keys
.
h = { "a" => 100, "b" => 200, "c" => 300 } h.values #=> [100, 200, 300]
static VALUE rb_hash_values(VALUE hash) { VALUE ary; ary = rb_ary_new(); rb_hash_foreach(hash, values_i, ary); return ary; }
Return an array containing the values associated with the given keys. Also
see Hash.select
.
h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" } h.values_at("cow", "cat") #=> ["bovine", "feline"]
VALUE rb_hash_values_at(int argc, VALUE *argv, VALUE hash) { VALUE result = rb_ary_new2(argc); long i; for (i=0; i<argc; i++) { rb_ary_push(result, rb_hash_aref(hash, argv[i])); } return result; }