Class: Hash

Inherits:
Object show all
Includes:
Enumerable
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 for keys that are 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 Hash.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 Programming 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 collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #chain, #chunk, #chunk_while, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #filter_map, #find, #find_all, #find_index, #first, #flat_map, #grep, #grep_v, #group_by, #inject, #lazy, #map, #max, #max_by, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reverse_each, #slice_after, #slice_before, #slice_when, #sort, #sort_by, #sum, #take, #take_while, #tally, #uniq, #zip

Constructor Details

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

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

Overloads:



1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
 
# File 'hash.c', line 1737

static VALUE
rb_hash_initialize(int argc, VALUE *argv, VALUE hash)
{
    VALUE ifnone;

    rb_hash_modify(hash);
    if (rb_block_given_p()) {
  rb_check_arity(argc, 0, 0);
  ifnone = rb_block_proc();
  SET_PROC_DEFAULT(hash, ifnone);
    }
    else {
  rb_check_arity(argc, 0, 1);
  ifnone = argc == 0 ? Qnil : argv[0];
  RHASH_SET_IFNONE(hash, ifnone);
    }

    return hash;
}

Class Method Details

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

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}



1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
 
# File 'hash.c', line 1777

static VALUE
rb_hash_s_create(int argc, VALUE *argv, VALUE klass)
{
    VALUE hash, tmp;

    if (argc == 1) {
        tmp = rb_hash_s_try_convert(Qnil, argv[0]);
  if (!NIL_P(tmp)) {
      hash = hash_alloc(klass);
            if (RHASH_AR_TABLE_P(tmp)) {
                ar_copy(hash, tmp);
      }
            else {
                RHASH_ST_TABLE_SET(hash, st_copy(RHASH_ST_TABLE(tmp)));
            }
      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 e = RARRAY_AREF(tmp, i);
    VALUE v = rb_check_array_type(e);
    VALUE key, val = Qnil;

    if (NIL_P(v)) {
        rb_raise(rb_eArgError, "wrong element type %s at %ld (expected array)",
           rb_builtin_class_name(e), i);
    }
    switch (RARRAY_LEN(v)) {
      default:
        rb_raise(rb_eArgError, "invalid number of elements (%ld for 1..2)",
           RARRAY_LEN(v));
      case 2:
        val = RARRAY_AREF(v, 1);
      case 1:
        key = RARRAY_AREF(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);
    rb_hash_bulk_insert(argc, argv, hash);
    hash_verify(hash);
    return hash;
}

.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

Returns:



1857
1858
1859
1860
1861
 
# File 'hash.c', line 1857

static VALUE
rb_hash_s_try_convert(VALUE dummy, VALUE hash)
{
    return rb_check_hash_type(hash);
}

Instance Method Details

#<(other) ⇒ Boolean

Returns true if hash is subset of other.

h1 = {a:1, b:2}
h2 = {a:1, b:2, c:3}
h1 < h2    #=> true
h2 < h1    #=> false
h1 < h1    #=> false

Returns:

  • (Boolean) 


4391
4392
4393
4394
4395
4396
4397
 
# File 'hash.c', line 4391

static VALUE
rb_hash_lt(VALUE hash, VALUE other)
{
    other = to_hash(other);
    if (RHASH_SIZE(hash) >= RHASH_SIZE(other)) return Qfalse;
    return hash_le(hash, other);
}

#<=(other) ⇒ Boolean

Returns true if hash is subset of other or equals to other.

h1 = {a:1, b:2}
h2 = {a:1, b:2, c:3}
h1 <= h2   #=> true
h2 <= h1   #=> false
h1 <= h1   #=> true

Returns:

  • (Boolean) 


4370
4371
4372
4373
4374
4375
4376
 
# File 'hash.c', line 4370

static VALUE
rb_hash_le(VALUE hash, VALUE other)
{
    other = to_hash(other);
    if (RHASH_SIZE(hash) > RHASH_SIZE(other)) return Qfalse;
    return hash_le(hash, other);
}

#==(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

The orders of each hashes are not compared.

h1 = { "a" => 1, "c" => 2 }
h2 = { "c" => 2, "a" => 1 }
h1 == h2   #=> true

Returns:

  • (Boolean) 


3599
3600
3601
3602
3603
 
# File 'hash.c', line 3599

static VALUE
rb_hash_equal(VALUE hash1, VALUE hash2)
{
    return hash_equal(hash1, hash2, FALSE);
}

#>(other) ⇒ Boolean

Returns true if other is subset of hash.

h1 = {a:1, b:2}
h2 = {a:1, b:2, c:3}
h1 > h2    #=> false
h2 > h1    #=> true
h1 > h1    #=> false

Returns:

  • (Boolean) 


4433
4434
4435
4436
4437
4438
4439
 
# File 'hash.c', line 4433

static VALUE
rb_hash_gt(VALUE hash, VALUE other)
{
    other = to_hash(other);
    if (RHASH_SIZE(hash) <= RHASH_SIZE(other)) return Qfalse;
    return hash_le(other, hash);
}

#>=(other) ⇒ Boolean

Returns true if other is subset of hash or equals to hash.

h1 = {a:1, b:2}
h2 = {a:1, b:2, c:3}
h1 >= h2   #=> false
h2 >= h1   #=> true
h1 >= h1   #=> true

Returns:

  • (Boolean) 


4412
4413
4414
4415
4416
4417
4418
 
# File 'hash.c', line 4412

static VALUE
rb_hash_ge(VALUE hash, VALUE other)
{
    other = to_hash(other);
    if (RHASH_SIZE(hash) < RHASH_SIZE(other)) return Qfalse;
    return hash_le(other, hash);
}

#[](key) ⇒ Object

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

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



1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
 
# File 'hash.c', line 1979

VALUE
rb_hash_aref(VALUE hash, VALUE key)
{
    st_data_t val;

    if (hash_stlike_lookup(hash, key, &val)) {
        return (VALUE)val;
    }
    else {
        return rb_hash_default_value(hash, key);
    }
}

#[]= ⇒ Object

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

See also Enumerable#any?

Overloads:

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

    Yields:

    • ((key, value))

    Returns:

    • (Boolean)
  • #any?(pattern) ⇒ Boolean

    Returns:

    • (Boolean) 


4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
 
# File 'hash.c', line 4279

static VALUE
rb_hash_any_p(int argc, VALUE *argv, VALUE hash)
{
    VALUE args[2];
    args[0] = Qfalse;

    rb_check_arity(argc, 0, 1);
    if (RHASH_EMPTY_P(hash)) return Qfalse;
    if (argc) {
        if (rb_block_given_p()) {
            rb_warn("given block not used");
        }
  args[1] = argv[0];

  rb_hash_foreach(hash, any_p_i_pattern, (VALUE)args);
    }
    else {
  if (!rb_block_given_p()) {
      /* yields pairs, never false */
      return Qtrue;
  }
  if (rb_block_arity() > 1)
      rb_hash_foreach(hash, any_p_i_fast, (VALUE)args);
  else
      rb_hash_foreach(hash, any_p_i, (VALUE)args);
    }
    return args[0];
}

#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

Returns:



3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
 
# File 'hash.c', line 3957

VALUE
rb_hash_assoc(VALUE hash, VALUE key)
{
    st_table *table;
    const struct st_hash_type *orighash;
    VALUE args[2];

    if (RHASH_EMPTY_P(hash)) return Qnil;

    ar_force_convert_table(hash, __FILE__, __LINE__);
    HASH_ASSERT(RHASH_ST_TABLE_P(hash));
    table = RHASH_ST_TABLE(hash);
    orighash = table->type;

    if (orighash != &identhash) {
  VALUE value;
  struct reset_hash_type_arg ensure_arg;
  struct st_hash_type assochash;

  assochash.compare = assoc_cmp;
  assochash.hash = orighash->hash;
        table->type = &assochash;
  args[0] = hash;
  args[1] = key;
  ensure_arg.hash = hash;
  ensure_arg.orighash = orighash;
  value = rb_ensure(lookup2_call, (VALUE)&args, reset_hash_type, (VALUE)&ensure_arg);
  if (value != Qundef) return rb_assoc_new(key, value);
    }

    args[0] = key;
    args[1] = Qnil;
    rb_hash_foreach(hash, assoc_i, (VALUE)args);
    return args[1];
}

#clear ⇒ Hash

Removes all key-value pairs from hsh.

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

Returns:



2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
 
# File 'hash.c', line 2711

VALUE
rb_hash_clear(VALUE hash)
{
    rb_hash_modify_check(hash);

    if (RHASH_ITER_LEV(hash) > 0) {
        rb_hash_foreach(hash, clear_i, 0);
    }
    else if (RHASH_AR_TABLE_P(hash)) {
        ar_clear(hash);
    }
    else {
        st_clear(RHASH_ST_TABLE(hash));
    }

    return hash;
}

#compact ⇒ Object

Returns a new hash with the nil values/key pairs removed

h = { a: 1, b: false, c: nil }
h.compact     #=> { a: 1, b: false }
h             #=> { a: 1, b: false, c: nil }



4120
4121
4122
4123
4124
4125
4126
4127
4128
 
# File 'hash.c', line 4120

static VALUE
rb_hash_compact(VALUE hash)
{
    VALUE result = rb_hash_new();
    if (!RHASH_EMPTY_P(hash)) {
  rb_hash_foreach(hash, set_if_not_nil, result);
    }
    return result;
}

#compact! ⇒ Hash?

Removes all nil values from the hash. Returns nil if no changes were made, otherwise returns the hash.

h = { a: 1, b: false, c: nil }
h.compact!     #=> { a: 1, b: false }

Returns:



4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
 
# File 'hash.c', line 4142

static VALUE
rb_hash_compact_bang(VALUE hash)
{
    st_index_t n;
    rb_hash_modify_check(hash);
    n = RHASH_SIZE(hash);
    if (n) {
  rb_hash_foreach(hash, delete_if_nil, hash);
        if (n != RHASH_SIZE(hash))
      return hash;
    }
    return Qnil;
}

#compare_by_identity ⇒ Hash

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.

Returns:



4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
 
# File 'hash.c', line 4174

static VALUE
rb_hash_compare_by_id(VALUE hash)
{
    VALUE tmp;
    st_table *identtable;

    if (rb_hash_compare_by_id_p(hash)) return hash;

    rb_hash_modify_check(hash);
    ar_force_convert_table(hash, __FILE__, __LINE__);
    HASH_ASSERT(RHASH_ST_TABLE_P(hash));

    tmp = hash_alloc(0);
    identtable = rb_init_identtable_with_size(RHASH_SIZE(hash));
    RHASH_ST_TABLE_SET(tmp, identtable);
    rb_hash_foreach(hash, rb_hash_rehash_i, (VALUE)tmp);
    st_free_table(RHASH_ST_TABLE(hash));
    RHASH_ST_TABLE_SET(hash, identtable);
    RHASH_ST_CLEAR(tmp);
    rb_gc_force_recycle(tmp);

    return hash;
}

#compare_by_identity? ⇒ Boolean

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

Returns:

  • (Boolean) 


4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
 
# File 'hash.c', line 4207

MJIT_FUNC_EXPORTED VALUE
rb_hash_compare_by_id_p(VALUE hash)
{
    if (RHASH_ST_TABLE_P(hash) && RHASH_ST_TABLE(hash)->type == &identhash) {
  return Qtrue;
    }
    else {
        return Qfalse;
    }
}

#deconstruct_keys(keys) ⇒ Object 



4467
4468
4469
4470
4471
 
# File 'hash.c', line 4467

static VALUE
rb_hash_deconstruct_keys(VALUE hash, VALUE keys)
{
    return hash;
}

#default(key = nil) ⇒ Object

Returns the default value, the value that would be returned by hsh[key] 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

Returns:



2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
 
# File 'hash.c', line 2103

static VALUE
rb_hash_default(int argc, VALUE *argv, VALUE hash)
{
    VALUE args[2], ifnone;

    rb_check_arity(argc, 0, 1);
    ifnone = RHASH_IFNONE(hash);
    if (FL_TEST(hash, RHASH_PROC_DEFAULT)) {
  if (argc == 0) return Qnil;
  args[0] = hash;
  args[1] = argv[0];
  return rb_funcallv(ifnone, id_yield, 2, args);
    }
    return ifnone;
}

#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>

Returns:



2139
2140
2141
2142
2143
2144
2145
 
# File 'hash.c', line 2139

static VALUE
rb_hash_set_default(VALUE hash, VALUE ifnone)
{
    rb_hash_modify_check(hash);
    SET_DEFAULT(hash, ifnone);
    return ifnone;
}

#default_proc ⇒ Object

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]

Returns:



2162
2163
2164
2165
2166
2167
2168
2169
 
# File 'hash.c', line 2162

static VALUE
rb_hash_default_proc(VALUE hash)
{
    if (FL_TEST(hash, RHASH_PROC_DEFAULT)) {
  return RHASH_IFNONE(hash);
    }
    return Qnil;
}

#default_proc=(proc_obj) ⇒ Object

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"



2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
 
# File 'hash.c', line 2184

VALUE
rb_hash_set_default_proc(VALUE hash, VALUE proc)
{
    VALUE b;

    rb_hash_modify_check(hash);
    if (NIL_P(proc)) {
  SET_DEFAULT(hash, proc);
  return proc;
    }
    b = rb_check_convert_type_with_id(proc, T_DATA, "Proc", idTo_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;
    SET_PROC_DEFAULT(hash, proc);
    return proc;
}

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

Deletes the key-value pair and returns the value from hsh whose key is equal to key. If the key is not found, it returns nil. 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"

Overloads:

  • #delete(key) {|key| ... } ⇒ Object

    Yields:



2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
 
# File 'hash.c', line 2317

static VALUE
rb_hash_delete_m(VALUE hash, VALUE key)
{
    VALUE val;

    rb_hash_modify_check(hash);
    val = rb_hash_delete_entry(hash, key);

    if (val != Qundef) {
  return val;
    }
    else {
  if (rb_block_given_p()) {
      return rb_yield(key);
  }
  else {
      return Qnil;
  }
    }
}

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

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}

Overloads:

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

    Yields:

    Returns:



2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
 
# File 'hash.c', line 2435

VALUE
rb_hash_delete_if(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);
    if (!RHASH_TABLE_EMPTY_P(hash)) {
        rb_hash_foreach(hash, delete_if_i, hash);
    }
    return hash;
}

#dig(key, ...) ⇒ Object

Extracts the nested value specified by the sequence of key objects by calling dig at each step, returning nil if any intermediate step is nil.

h = { foo: {bar: {baz: 1}}}

h.dig(:foo, :bar, :baz)     #=> 1
h.dig(:foo, :zot, :xyz)     #=> nil

g = { foo: [10, 11, 12] }
g.dig(:foo, 1)              #=> 11
g.dig(:foo, 1, 0)           #=> TypeError: Integer does not have #dig method
g.dig(:foo, :bar)           #=> TypeError: no implicit conversion of Symbol into Integer

Returns:



4327
4328
4329
4330
4331
4332
4333
4334
4335
 
# File 'hash.c', line 4327

static VALUE
rb_hash_dig(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    self = rb_hash_aref(self, *argv);
    if (!--argc) return self;
    ++argv;
    return rb_obj_dig(argc, argv, self, Qnil);
}

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

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

Overloads:

  • #each {|key, value| ... } ⇒ Hash

    Yields:

    Returns:

  • #each_pair {|key, value| ... } ⇒ Hash

    Yields:

    Returns:



3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
 
# File 'hash.c', line 3015

static VALUE
rb_hash_each_pair(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    if (rb_block_arity() > 1)
  rb_hash_foreach(hash, each_pair_i_fast, 0);
    else
  rb_hash_foreach(hash, each_pair_i, 0);
    return hash;
}

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

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

Overloads:

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

    Yields:

    Returns:



2968
2969
2970
2971
2972
2973
2974
 
# File 'hash.c', line 2968

static VALUE
rb_hash_each_key(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_foreach(hash, each_key_i, 0);
    return hash;
}

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

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

Overloads:

  • #each {|key, value| ... } ⇒ Hash

    Yields:

    Returns:

  • #each_pair {|key, value| ... } ⇒ Hash

    Yields:

    Returns:



3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
 
# File 'hash.c', line 3015

static VALUE
rb_hash_each_pair(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    if (rb_block_arity() > 1)
  rb_hash_foreach(hash, each_pair_i_fast, 0);
    else
  rb_hash_foreach(hash, each_pair_i, 0);
    return hash;
}

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

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

Overloads:

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

    Yields:

    • (value)

    Returns:



2935
2936
2937
2938
2939
2940
2941
 
# File 'hash.c', line 2935

static VALUE
rb_hash_each_value(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_foreach(hash, each_value_i, 0);
    return hash;
}

#empty? ⇒ Boolean

Returns true if hsh contains no key-value pairs.

{}.empty?   #=> true

Returns:

  • (Boolean) 


2903
2904
2905
2906
2907
 
# File 'hash.c', line 2903

static VALUE
rb_hash_empty_p(VALUE hash)
{
    return RHASH_EMPTY_P(hash) ? Qtrue : Qfalse;
}

#eql?(other) ⇒ Boolean

Returns true if hash and other are both hashes with the same content. The orders of each hashes are not compared.

Returns:

  • (Boolean) 


3614
3615
3616
3617
3618
 
# File 'hash.c', line 3614

static VALUE
rb_hash_eql(VALUE hash1, VALUE hash2)
{
    return hash_equal(hash1, hash2, TRUE);
}

#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 a 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

Overloads:



2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
 
# File 'hash.c', line 2040

static VALUE
rb_hash_fetch_m(int argc, VALUE *argv, VALUE hash)
{
    VALUE key;
    st_data_t val;
    long block_given;

    rb_check_arity(argc, 1, 2);
    key = argv[0];

    block_given = rb_block_given_p();
    if (block_given && argc == 2) {
  rb_warn("block supersedes default value argument");
    }

    if (hash_stlike_lookup(hash, key, &val)) {
        return (VALUE)val;
    }
    else {
        if (block_given) {
            return rb_yield(key);
        }
        else if (argc == 1) {
            VALUE desc = rb_protect(rb_inspect, key, 0);
            if (NIL_P(desc)) {
                desc = rb_any_to_s(key);
            }
            desc = rb_str_ellipsize(desc, 65);
            rb_key_err_raise(rb_sprintf("key not found: %"PRIsVALUE, desc), hash, key);
        }
        else {
            return argv[1];
        }
    }
}

#fetch_values(key, ...) ⇒ Array #fetch_values(key, ...) {|key| ... } ⇒ Array

Returns an array containing the values associated with the given keys but also raises KeyError when one of keys can’t be found. Also see Hash#values_at and Hash#fetch.

h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" }

h.fetch_values("cow", "cat")                   #=> ["bovine", "feline"]
h.fetch_values("cow", "bird")                  # raises KeyError
h.fetch_values("cow", "bird") { |k| k.upcase } #=> ["bovine", "BIRD"]

Overloads:

  • #fetch_values(key, ...) ⇒ Array

    Returns:

  • #fetch_values(key, ...) {|key| ... } ⇒ Array

    Yields:

    Returns:



2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
 
# File 'hash.c', line 2582

VALUE
rb_hash_fetch_values(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_fetch(hash, argv[i]));
    }
    return result;
}

#select {|key, value| ... } ⇒ Hash #select ⇒ Object #filter {|key, value| ... } ⇒ Hash #filter ⇒ Object

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}

Hash#filter is an alias for Hash#select.

Overloads:

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

    Yields:

    Returns:

  • #filter {|key, value| ... } ⇒ Hash

    Yields:

    Returns:



2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
 
# File 'hash.c', line 2621

VALUE
rb_hash_select(VALUE hash)
{
    VALUE result;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    result = rb_hash_new();
    if (!RHASH_EMPTY_P(hash)) {
  rb_hash_foreach(hash, select_i, result);
    }
    return result;
}

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

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

Hash#filter! is an alias for Hash#select!.

Overloads:

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

    Yields:

    Returns:

  • #filter! {|key, value| ... } ⇒ Hash?

    Yields:

    Returns:



2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
 
# File 'hash.c', line 2656

VALUE
rb_hash_select_bang(VALUE hash)
{
    st_index_t n;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);
    n = RHASH_SIZE(hash);
    if (!n) return Qnil;
    rb_hash_foreach(hash, keep_if_i, hash);
    if (n == RHASH_SIZE(hash)) return Qnil;
    return hash;
}

#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"]

Overloads:



4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
 
# File 'hash.c', line 4057

static VALUE
rb_hash_flatten(int argc, VALUE *argv, VALUE hash)
{
    VALUE ary;

    rb_check_arity(argc, 0, 1);

    if (argc) {
  int level = NUM2INT(argv[0]);

  if (level == 0) return rb_hash_to_a(hash);

  ary = rb_ary_new_capa(RHASH_SIZE(hash) * 2);
  rb_hash_foreach(hash, flatten_i, ary);
  level--;

  if (level > 0) {
      VALUE ary_flatten_level = INT2FIX(level);
      rb_funcallv(ary, id_flatten_bang, 1, &ary_flatten_level);
  }
  else if (level < 0) {
      /* flatten recursively */
      rb_funcallv(ary, id_flatten_bang, 0, 0);
  }
    }
    else {
  ary = rb_ary_new_capa(RHASH_SIZE(hash) * 2);
  rb_hash_foreach(hash, flatten_i, ary);
    }

    return ary;
}

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

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

Note that #include? and #member? do not test member equality using == as do other Enumerables.

See also Enumerable#include?

Overloads:

  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean) 


3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
 
# File 'hash.c', line 3447

MJIT_FUNC_EXPORTED VALUE
rb_hash_has_key(VALUE hash, VALUE key)
{
    if (hash_stlike_lookup(hash, key, NULL)) {
        return Qtrue;
    }
    else {
        return Qfalse;
    }
}

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

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

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

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

    • (Boolean)
  • #value?(value) ⇒ Boolean

    Returns:

    • (Boolean) 


3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
 
# File 'hash.c', line 3483

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, (VALUE)data);
    return data[0];
}

#hash ⇒ Integer

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.

Returns:



3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
 
# File 'hash.c', line 3642

static VALUE
rb_hash_hash(VALUE hash)
{
    st_index_t size = RHASH_SIZE(hash);
    st_index_t hval = rb_hash_start(size);
    hval = rb_hash_uint(hval, (st_index_t)rb_hash_hash);
    if (size) {
  rb_hash_foreach(hash, hash_i, (VALUE)&hval);
    }
    hval = rb_hash_end(hval);
    return ST2FIX(hval);
}

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

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

Note that #include? and #member? do not test member equality using == as do other Enumerables.

See also Enumerable#include?

Overloads:

  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean) 


3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
 
# File 'hash.c', line 3447

MJIT_FUNC_EXPORTED VALUE
rb_hash_has_key(VALUE hash, VALUE key)
{
    if (hash_stlike_lookup(hash, key, NULL)) {
        return Qtrue;
    }
    else {
        return Qfalse;
    }
}

#index(value) ⇒ Object

:nodoc:



2245
2246
2247
2248
2249
2250
 
# File 'hash.c', line 2245

static VALUE
rb_hash_index(VALUE hash, VALUE value)
{
    rb_warn_deprecated("Hash#index", "Hash#key");
    return rb_hash_key(hash, value);
}

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

Returns:



2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
 
# File 'hash.c', line 2827

static VALUE
rb_hash_replace(VALUE hash, VALUE hash2)
{
    rb_hash_modify_check(hash);
    if (hash == hash2) return hash;
    if (RHASH_ITER_LEV(hash) > 0) {
        rb_raise(rb_eRuntimeError, "can't replace hash during iteration");
    }
    hash2 = to_hash(hash2);

    COPY_DEFAULT(hash, hash2);

    if (RHASH_AR_TABLE_P(hash)) {
        if (RHASH_AR_TABLE_P(hash2)) {
            ar_clear(hash);
        }
        else {
            ar_free_and_clear_table(hash);
            RHASH_ST_TABLE_SET(hash, st_init_table_with_size(RHASH_TYPE(hash2), RHASH_SIZE(hash2)));
        }
    }
    else {
        if (RHASH_AR_TABLE_P(hash2)) {
            st_free_table(RHASH_ST_TABLE(hash));
            RHASH_ST_CLEAR(hash);
        }
        else {
            st_clear(RHASH_ST_TABLE(hash));
            RHASH_TBL_RAW(hash)->type = RHASH_ST_TABLE(hash2)->type;
        }
    }
    rb_hash_foreach(hash2, rb_hash_rehash_i, (VALUE)hash);

    rb_gc_writebarrier_remember(hash);

    return hash;
}

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

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

Overloads:



3251
3252
3253
3254
3255
3256
3257
 
# File 'hash.c', line 3251

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);
}

#invert ⇒ Object

Returns a new hash created by using hsh’s values as keys, and the keys as values. If a key with the same value already exists in the hsh, then the last one defined will be used, the earlier value(s) will be discarded.

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

If there is no key with the same value, Hash#invert is involutive.

h = { a: 1, b: 3, c: 4 }
h.invert.invert == h #=> true

The condition, no key with the same value, can be tested by comparing the size of inverted hash.

# no key with the same value
h = { a: 1, b: 3, c: 4 }
h.size == h.invert.size #=> true

# two (or more) keys has the same value
h = { a: 1, b: 3, c: 1 }
h.size == h.invert.size #=> false



3692
3693
3694
3695
3696
3697
3698
3699
 
# File 'hash.c', line 3692

static VALUE
rb_hash_invert(VALUE hash)
{
    VALUE h = rb_hash_new_with_size(RHASH_SIZE(hash));

    rb_hash_foreach(hash, rb_hash_invert_i, h);
    return h;
}

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

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

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

See also Hash#select!.

Overloads:

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

    Yields:

    Returns:



2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
 
# File 'hash.c', line 2683

VALUE
rb_hash_keep_if(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);
    if (!RHASH_TABLE_EMPTY_P(hash)) {
        rb_hash_foreach(hash, keep_if_i, hash);
    }
    return hash;
}

#key(value) ⇒ Object

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



2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
 
# File 'hash.c', line 2231

static VALUE
rb_hash_key(VALUE hash, VALUE value)
{
    VALUE args[2];

    args[0] = value;
    args[1] = Qnil;

    rb_hash_foreach(hash, key_i, (VALUE)args);

    return args[1];
}

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

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

Note that #include? and #member? do not test member equality using == as do other Enumerables.

See also Enumerable#include?

Overloads:

  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean) 


3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
 
# File 'hash.c', line 3447

MJIT_FUNC_EXPORTED VALUE
rb_hash_has_key(VALUE hash, VALUE key)
{
    if (hash_stlike_lookup(hash, key, NULL)) {
        return Qtrue;
    }
    else {
        return Qfalse;
    }
}

#keys ⇒ Array

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

Returns:



3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
 
# File 'hash.c', line 3349

MJIT_FUNC_EXPORTED VALUE
rb_hash_keys(VALUE hash)
{
    st_index_t size = RHASH_SIZE(hash);
    VALUE keys =  rb_ary_new_capa(size);

    if (size == 0) return keys;

    if (ST_DATA_COMPATIBLE_P(VALUE)) {
        RARRAY_PTR_USE_TRANSIENT(keys, ptr, {
            if (RHASH_AR_TABLE_P(hash)) {
                size = ar_keys(hash, ptr, size);
            }
            else {
                st_table *table = RHASH_ST_TABLE(hash);
                size = st_keys(table, ptr, size);
            }
        });
        rb_gc_writebarrier_remember(keys);
  rb_ary_set_len(keys, size);
    }
    else {
  rb_hash_foreach(hash, keys_i, keys);
    }

    return keys;
}

#length ⇒ Integer #size ⇒ Integer

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

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

Hash#length is an alias for Hash#size.

Overloads:



2881
2882
2883
2884
2885
 
# File 'hash.c', line 2881

VALUE
rb_hash_size(VALUE hash)
{
    return INT2FIX(RHASH_SIZE(hash));
}

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

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

Note that #include? and #member? do not test member equality using == as do other Enumerables.

See also Enumerable#include?

Overloads:

  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean) 


3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
 
# File 'hash.c', line 3447

MJIT_FUNC_EXPORTED VALUE
rb_hash_has_key(VALUE hash, VALUE key)
{
    if (hash_stlike_lookup(hash, key, NULL)) {
        return Qtrue;
    }
    else {
        return Qfalse;
    }
}

#merge(other_hash1, other_hash2, ...) ⇒ Object #merge(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object #- ⇒ Object

Returns a new hash that combines the contents of the receiver and the contents of the given hashes.

If no block is given, entries with duplicate keys are overwritten with the values from each other_hash successively, otherwise the value for each duplicate key is determined by calling the block with the key, its value in the receiver and its value in each other_hash.

When called without any argument, returns a copy of the receiver.

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 246, "c" => 300 }
h3 = { "b" => 357, "d" => 400 }
h1.merge          #=> {"a"=>100, "b"=>200}
h1.merge(h2)      #=> {"a"=>100, "b"=>246, "c"=>300}
h1.merge(h2, h3)  #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
h1.merge(h2) {|key, oldval, newval| newval - oldval}
                  #=> {"a"=>100, "b"=>46,  "c"=>300}
h1.merge(h2, h3) {|key, oldval, newval| newval - oldval}
                  #=> {"a"=>100, "b"=>311, "c"=>300, "d"=>400}
h1                #=> {"a"=>100, "b"=>200}

Overloads:

  • #merge(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object

    Yields:

    • (key, oldval, newval) 


3898
3899
3900
3901
3902
 
# File 'hash.c', line 3898

static VALUE
rb_hash_merge(int argc, VALUE *argv, VALUE self)
{
    return rb_hash_update(argc, argv, rb_hash_dup(self));
}

#merge!(other_hash1, other_hash2, ...) ⇒ Hash #update(other_hash1, other_hash2, ...) ⇒ Hash #merge!(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object #- ⇒ Object #update(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object #- ⇒ Object

Adds the contents of the given hashes to the receiver.

If no block is given, entries with duplicate keys are overwritten with the values from each other_hash successively, otherwise the value for each duplicate key is determined by calling the block with the key, its value in the receiver and its value in each other_hash.

h1 = { "a" => 100, "b" => 200 }
h1.merge!          #=> {"a"=>100, "b"=>200}
h1                 #=> {"a"=>100, "b"=>200}

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

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 246, "c" => 300 }
h3 = { "b" => 357, "d" => 400 }
h1.merge!(h2, h3)
                   #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
h1                 #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}

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

Hash#update is an alias for Hash#merge!.

Overloads:

  • #merge!(other_hash1, other_hash2, ...) ⇒ Hash

    Returns:

  • #update(other_hash1, other_hash2, ...) ⇒ Hash

    Returns:

  • #merge!(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object

    Yields:

    • (key, oldval, newval)
  • #update(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object

    Yields:

    • (key, oldval, newval) 


3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
 
# File 'hash.c', line 3794

static VALUE
rb_hash_update(int argc, VALUE *argv, VALUE self)
{
    int i;
    bool block_given = rb_block_given_p();

    rb_hash_modify(self);
    for (i = 0; i < argc; i++){
       VALUE hash = to_hash(argv[i]);
       if (block_given) {
           rb_hash_foreach(hash, rb_hash_update_block_i, self);
       }
       else {
           rb_hash_foreach(hash, rb_hash_update_i, self);
       }
    }
    return self;
}

#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

Returns:



4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
 
# File 'hash.c', line 4018

VALUE
rb_hash_rassoc(VALUE hash, VALUE obj)
{
    VALUE args[2];

    args[0] = obj;
    args[1] = Qnil;
    rb_hash_foreach(hash, rassoc_i, (VALUE)args);
    return args[1];
}

#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 Hash#rehash is called while an iterator is traversing the hash, a 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

Returns:



1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
 
# File 'hash.c', line 1900

VALUE
rb_hash_rehash(VALUE hash)
{
    VALUE tmp;
    st_table *tbl;

    if (RHASH_ITER_LEV(hash) > 0) {
  rb_raise(rb_eRuntimeError, "rehash during iteration");
    }
    rb_hash_modify_check(hash);
    if (RHASH_AR_TABLE_P(hash)) {
        tmp = hash_alloc(0);
        ar_alloc_table(tmp);
        rb_hash_foreach(hash, rb_hash_rehash_i, (VALUE)tmp);
        ar_free_and_clear_table(hash);
        ar_copy(hash, tmp);
        ar_free_and_clear_table(tmp);
    }
    else if (RHASH_ST_TABLE_P(hash)) {
        st_table *old_tab = RHASH_ST_TABLE(hash);
        tmp = hash_alloc(0);
        tbl = st_init_table_with_size(old_tab->type, old_tab->num_entries);
        RHASH_ST_TABLE_SET(tmp, tbl);
        rb_hash_foreach(hash, rb_hash_rehash_i, (VALUE)tmp);
        st_free_table(old_tab);
        RHASH_ST_TABLE_SET(hash, tbl);
        RHASH_ST_CLEAR(tmp);
    }
    hash_verify(hash);
    return hash;
}

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

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}

Overloads:

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

    Yields:

    Returns:



2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
 
# File 'hash.c', line 2492

VALUE
rb_hash_reject(VALUE hash)
{
    VALUE result;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    if (RTEST(ruby_verbose)) {
  VALUE klass;
  if (HAS_EXTRA_STATES(hash, klass)) {
      rb_warn("extra states are no longer copied: %+"PRIsVALUE, hash);
  }
    }
    result = rb_hash_new();
    if (!RHASH_EMPTY_P(hash)) {
  rb_hash_foreach(hash, reject_i, result);
    }
    return result;
}

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

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

Overloads:

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

    Yields:

    Returns:



2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
 
# File 'hash.c', line 2455

VALUE
rb_hash_reject_bang(VALUE hash)
{
    st_index_t n;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify(hash);
    n = RHASH_SIZE(hash);
    if (!n) return Qnil;
    rb_hash_foreach(hash, delete_if_i, hash);
    if (n == RHASH_SIZE(hash)) return Qnil;
    return hash;
}

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

Returns:



2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
 
# File 'hash.c', line 2827

static VALUE
rb_hash_replace(VALUE hash, VALUE hash2)
{
    rb_hash_modify_check(hash);
    if (hash == hash2) return hash;
    if (RHASH_ITER_LEV(hash) > 0) {
        rb_raise(rb_eRuntimeError, "can't replace hash during iteration");
    }
    hash2 = to_hash(hash2);

    COPY_DEFAULT(hash, hash2);

    if (RHASH_AR_TABLE_P(hash)) {
        if (RHASH_AR_TABLE_P(hash2)) {
            ar_clear(hash);
        }
        else {
            ar_free_and_clear_table(hash);
            RHASH_ST_TABLE_SET(hash, st_init_table_with_size(RHASH_TYPE(hash2), RHASH_SIZE(hash2)));
        }
    }
    else {
        if (RHASH_AR_TABLE_P(hash2)) {
            st_free_table(RHASH_ST_TABLE(hash));
            RHASH_ST_CLEAR(hash);
        }
        else {
            st_clear(RHASH_ST_TABLE(hash));
            RHASH_TBL_RAW(hash)->type = RHASH_ST_TABLE(hash2)->type;
        }
    }
    rb_hash_foreach(hash2, rb_hash_rehash_i, (VALUE)hash);

    rb_gc_writebarrier_remember(hash);

    return hash;
}

#select {|key, value| ... } ⇒ Hash #select ⇒ Object #filter {|key, value| ... } ⇒ Hash #filter ⇒ Object

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}

Hash#filter is an alias for Hash#select.

Overloads:

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

    Yields:

    Returns:

  • #filter {|key, value| ... } ⇒ Hash

    Yields:

    Returns:



2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
 
# File 'hash.c', line 2621

VALUE
rb_hash_select(VALUE hash)
{
    VALUE result;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    result = rb_hash_new();
    if (!RHASH_EMPTY_P(hash)) {
  rb_hash_foreach(hash, select_i, result);
    }
    return result;
}

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

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

Hash#filter! is an alias for Hash#select!.

Overloads:

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

    Yields:

    Returns:

  • #filter! {|key, value| ... } ⇒ Hash?

    Yields:

    Returns:



2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
 
# File 'hash.c', line 2656

VALUE
rb_hash_select_bang(VALUE hash)
{
    st_index_t n;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);
    n = RHASH_SIZE(hash);
    if (!n) return Qnil;
    rb_hash_foreach(hash, keep_if_i, hash);
    if (n == RHASH_SIZE(hash)) return Qnil;
    return hash;
}

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

Returns:



2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
 
# File 'hash.c', line 2366

static VALUE
rb_hash_shift(VALUE hash)
{
    struct shift_var var;

    rb_hash_modify_check(hash);
    if (RHASH_AR_TABLE_P(hash)) {
  var.key = Qundef;
  if (RHASH_ITER_LEV(hash) == 0) {
            if (ar_shift(hash, &var.key, &var.val)) {
    return rb_assoc_new(var.key, var.val);
      }
  }
  else {
            rb_hash_foreach(hash, shift_i_safe, (VALUE)&var);
            if (var.key != Qundef) {
                rb_hash_delete_entry(hash, var.key);
                return rb_assoc_new(var.key, var.val);
            }
        }
    }
    if (RHASH_ST_TABLE_P(hash)) {
        var.key = Qundef;
        if (RHASH_ITER_LEV(hash) == 0) {
            if (st_shift(RHASH_ST_TABLE(hash), &var.key, &var.val)) {
                return rb_assoc_new(var.key, var.val);
            }
        }
        else {
      rb_hash_foreach(hash, shift_i_safe, (VALUE)&var);
      if (var.key != Qundef) {
    rb_hash_delete_entry(hash, var.key);
    return rb_assoc_new(var.key, var.val);
      }
  }
    }
    return rb_hash_default_value(hash, Qnil);
}

#length ⇒ Integer #size ⇒ Integer

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

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

Hash#length is an alias for Hash#size.

Overloads:



2881
2882
2883
2884
2885
 
# File 'hash.c', line 2881

VALUE
rb_hash_size(VALUE hash)
{
    return INT2FIX(RHASH_SIZE(hash));
}

#slice(*keys) ⇒ Hash

Returns a hash containing only the given keys and their values.

h = { a: 100, b: 200, c: 300 }
h.slice(:a)           #=> {:a=>100}
h.slice(:b, :c, :d)   #=> {:b=>200, :c=>300}

Returns:



2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
 
# File 'hash.c', line 2522

static VALUE
rb_hash_slice(int argc, VALUE *argv, VALUE hash)
{
    int i;
    VALUE key, value, result;

    if (argc == 0 || RHASH_EMPTY_P(hash)) {
  return rb_hash_new();
    }
    result = rb_hash_new_with_size(argc);

    for (i = 0; i < argc; i++) {
  key = argv[i];
  value = rb_hash_lookup2(hash, key, Qundef);
  if (value != Qundef)
      rb_hash_aset(result, key, value);
    }

    return result;
}

#store ⇒ Object

#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]]

Returns:



3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
 
# File 'hash.c', line 3196

static VALUE
rb_hash_to_a(VALUE hash)
{
    VALUE ary;

    ary = rb_ary_new_capa(RHASH_SIZE(hash));
    rb_hash_foreach(hash, to_a_i, ary);

    return ary;
}

#to_h ⇒ Hash #to_h {|key, value| ... } ⇒ Object

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

If a block is given, the results of the block on each pair of the receiver will be used as pairs.

Overloads:

  • #to_h ⇒ Hash

    Returns:

  • #to_h {|key, value| ... } ⇒ Object

    Yields:



3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
 
# File 'hash.c', line 3317

static VALUE
rb_hash_to_h(VALUE hash)
{
    if (rb_block_given_p()) {
        return rb_hash_to_h_block(hash);
    }
    if (rb_obj_class(hash) != rb_cHash) {
  const VALUE flags = RBASIC(hash)->flags;
        hash = hash_dup(hash, rb_cHash, flags & RHASH_PROC_DEFAULT);
    }
    return hash;
}

#to_hash ⇒ Hash

Returns self.

Returns:



3266
3267
3268
3269
3270
 
# File 'hash.c', line 3266

static VALUE
rb_hash_to_hash(VALUE hash)
{
    return hash;
}

#to_proc ⇒ Proc

Returns a Proc which maps keys to values.

h = {a:1, b:2}
hp = h.to_proc
hp.call(:a)          #=> 1
hp.call(:b)          #=> 2
hp.call(:c)          #=> nil
[:a, :b, :c].map(&h) #=> [1, 2, nil]

Returns:



4461
4462
4463
4464
4465
 
# File 'hash.c', line 4461

static VALUE
rb_hash_to_proc(VALUE hash)
{
    return rb_func_proc_new(hash_proc_call, hash);
}

#transform_keys {|key| ... } ⇒ Object #transform_keys ⇒ Object

Returns a new hash with the results of running the block once for every key. This method does not change the values.

h = { a: 1, b: 2, c: 3 }
h.transform_keys {|k| k.to_s }  #=> { "a" => 1, "b" => 2, "c" => 3 }
h.transform_keys(&:to_s)        #=> { "a" => 1, "b" => 2, "c" => 3 }
h.transform_keys.with_index {|k, i| "#{k}.#{i}" }
                                #=> { "a.0" => 1, "b.1" => 2, "c.2" => 3 }

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

Overloads:

  • #transform_keys {|key| ... } ⇒ Object

    Yields:



3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
 
# File 'hash.c', line 3051

static VALUE
rb_hash_transform_keys(VALUE hash)
{
    VALUE result;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    result = rb_hash_new();
    if (!RHASH_EMPTY_P(hash)) {
        rb_hash_foreach(hash, transform_keys_i, result);
    }

    return result;
}

#transform_keys! {|key| ... } ⇒ Hash #transform_keys! ⇒ Object

Invokes the given block once for each key in hsh, replacing it with the new key returned by the block, and then returns hsh. This method does not change the values.

h = { a: 1, b: 2, c: 3 }
h.transform_keys! {|k| k.to_s }  #=> { "a" => 1, "b" => 2, "c" => 3 }
h.transform_keys!(&:to_sym)      #=> { a: 1, b: 2, c: 3 }
h.transform_keys!.with_index {|k, i| "#{k}.#{i}" }
                                 #=> { "a.0" => 1, "b.1" => 2, "c.2" => 3 }

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

Overloads:

  • #transform_keys! {|key| ... } ⇒ Hash

    Yields:

    Returns:



3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
 
# File 'hash.c', line 3084

static VALUE
rb_hash_transform_keys_bang(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);
    if (!RHASH_TABLE_EMPTY_P(hash)) {
        long i;
        VALUE pairs = rb_hash_flatten(0, NULL, hash);
        rb_hash_clear(hash);
        for (i = 0; i < RARRAY_LEN(pairs); i += 2) {
            VALUE key = RARRAY_AREF(pairs, i), new_key = rb_yield(key),
                  val = RARRAY_AREF(pairs, i+1);
            rb_hash_aset(hash, new_key, val);
        }
    }
    return hash;
}

#transform_values {|value| ... } ⇒ Object #transform_values ⇒ Object

Returns a new hash with the results of running the block once for every value. This method does not change the keys.

h = { a: 1, b: 2, c: 3 }
h.transform_values {|v| v * v + 1 }  #=> { a: 2, b: 5, c: 10 }
h.transform_values(&:to_s)           #=> { a: "1", b: "2", c: "3" }
h.transform_values.with_index {|v, i| "#{v}.#{i}" }
                                     #=> { a: "1.0", b: "2.1", c: "3.2" }

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

Overloads:

  • #transform_values {|value| ... } ⇒ Object

    Yields:

    • (value) 


3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
 
# File 'hash.c', line 3133

static VALUE
rb_hash_transform_values(VALUE hash)
{
    VALUE result;

    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    result = hash_dup(hash, rb_cHash, 0);

    if (!RHASH_EMPTY_P(hash)) {
        rb_hash_stlike_foreach_with_replace(result, transform_values_foreach_func, transform_values_foreach_replace, 0);
    }

    return result;
}

#transform_values! {|value| ... } ⇒ Hash #transform_values! ⇒ Object

Invokes the given block once for each value in hsh, replacing it with the new value returned by the block, and then returns hsh. This method does not change the keys.

h = { a: 1, b: 2, c: 3 }
h.transform_values! {|v| v * v + 1 }  #=> { a: 2, b: 5, c: 10 }
h.transform_values!(&:to_s)           #=> { a: "2", b: "5", c: "10" }
h.transform_values!.with_index {|v, i| "#{v}.#{i}" }
                                      #=> { a: "2.0", b: "5.1", c: "10.2" }

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

Overloads:

  • #transform_values! {|value| ... } ⇒ Hash

    Yields:

    • (value)

    Returns:



3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
 
# File 'hash.c', line 3165

static VALUE
rb_hash_transform_values_bang(VALUE hash)
{
    RETURN_SIZED_ENUMERATOR(hash, 0, 0, hash_enum_size);
    rb_hash_modify_check(hash);

    if (!RHASH_TABLE_EMPTY_P(hash)) {
        rb_hash_stlike_foreach_with_replace(hash, transform_values_foreach_func, transform_values_foreach_replace, 0);
    }

    return hash;
}

#merge!(other_hash1, other_hash2, ...) ⇒ Hash #update(other_hash1, other_hash2, ...) ⇒ Hash #merge!(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object #- ⇒ Object #update(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object #- ⇒ Object

Adds the contents of the given hashes to the receiver.

If no block is given, entries with duplicate keys are overwritten with the values from each other_hash successively, otherwise the value for each duplicate key is determined by calling the block with the key, its value in the receiver and its value in each other_hash.

h1 = { "a" => 100, "b" => 200 }
h1.merge!          #=> {"a"=>100, "b"=>200}
h1                 #=> {"a"=>100, "b"=>200}

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

h1 = { "a" => 100, "b" => 200 }
h2 = { "b" => 246, "c" => 300 }
h3 = { "b" => 357, "d" => 400 }
h1.merge!(h2, h3)
                   #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}
h1                 #=> {"a"=>100, "b"=>357, "c"=>300, "d"=>400}

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

Hash#update is an alias for Hash#merge!.

Overloads:

  • #merge!(other_hash1, other_hash2, ...) ⇒ Hash

    Returns:

  • #update(other_hash1, other_hash2, ...) ⇒ Hash

    Returns:

  • #merge!(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object

    Yields:

    • (key, oldval, newval)
  • #update(other_hash1, other_hash2, ...) {|key, oldval, newval| ... } ⇒ Object

    Yields:

    • (key, oldval, newval) 


3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
 
# File 'hash.c', line 3794

static VALUE
rb_hash_update(int argc, VALUE *argv, VALUE self)
{
    int i;
    bool block_given = rb_block_given_p();

    rb_hash_modify(self);
    for (i = 0; i < argc; i++){
       VALUE hash = to_hash(argv[i]);
       if (block_given) {
           rb_hash_foreach(hash, rb_hash_update_block_i, self);
       }
       else {
           rb_hash_foreach(hash, rb_hash_update_i, self);
       }
    }
    return self;
}

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

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

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

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

    • (Boolean)
  • #value?(value) ⇒ Boolean

    Returns:

    • (Boolean) 


3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
 
# File 'hash.c', line 3483

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, (VALUE)data);
    return data[0];
}

#values ⇒ Array

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]

Returns:



3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
 
# File 'hash.c', line 3396

VALUE
rb_hash_values(VALUE hash)
{
    VALUE values;
    st_index_t size = RHASH_SIZE(hash);

    values = rb_ary_new_capa(size);
    if (size == 0) return values;

    if (ST_DATA_COMPATIBLE_P(VALUE)) {
        if (RHASH_AR_TABLE_P(hash)) {
            rb_gc_writebarrier_remember(values);
            RARRAY_PTR_USE_TRANSIENT(values, ptr, {
                size = ar_values(hash, ptr, size);
            });
        }
        else if (RHASH_ST_TABLE_P(hash)) {
            st_table *table = RHASH_ST_TABLE(hash);
            rb_gc_writebarrier_remember(values);
            RARRAY_PTR_USE_TRANSIENT(values, ptr, {
                size = st_values(table, ptr, size);
            });
        }
  rb_ary_set_len(values, size);
    }
    else {
  rb_hash_foreach(hash, values_i, values);
    }

    return values;
}

#values_at(key, ...) ⇒ Array

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

Returns:



2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
 
# File 'hash.c', line 2554

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