Class: Hash

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
mrblib/hash.rb,
src/hash.c,
mrblib/hash.rb,
mrbgems/mruby-hash-ext/mrblib/hash.rb

Overview

Hash is enumerable

ISO 15.2.13.3

Constant Summary

Constants included from Enumerable

Enumerable::NONE

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

__update_hash, #all?, #any?, #chain, #collect, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_slice, #each_with_index, #each_with_object, #entries, #filter_map, #find_all, #find_index, #first, #flat_map, #grep, #group_by, #hash, #inject, #lazy, #max, #max_by, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reverse_each, #sort, #sort_by, #take, #take_while, #tally, #uniq, #zip

Constructor Details

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

  • #new {|hash, key| ... } ⇒ Object

    Yields:



792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
# File 'src/hash.c', line 792

static mrb_value
mrb_hash_init(mrb_state *mrb, mrb_value hash)
{
  mrb_value block, ifnone;
  mrb_bool ifnone_p;

  ifnone = mrb_nil_value();
  mrb_get_args(mrb, "&|o?", &block, &ifnone, &ifnone_p);
  mrb_hash_modify(mrb, hash);
  if (!mrb_nil_p(block)) {
    if (ifnone_p) {
      mrb_raise(mrb, E_ARGUMENT_ERROR, "wrong number of arguments");
    }
    RHASH(hash)->flags |= MRB_HASH_PROC_DEFAULT;
    ifnone = block;
  }
  if (!mrb_nil_p(ifnone)) {
    RHASH(hash)->flags |= MRB_HASH_DEFAULT;
    mrb_iv_set(mrb, hash, mrb_intern_lit(mrb, "ifnone"), ifnone);
  }
  return hash;
}

Class Method Details

.[](*object) ⇒ Object

call-seq: Hash[ key, value, … ] -> new_hash Hash[ [ [key, value], … ] ] -> new_hash Hash[ object ] -> new_hash

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}


26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 26

def self.[](*object)
  length = object.length
  if length == 1
    o = object[0]
    if Hash === o
      h = self.new
      o.each { |k, v| h[k] = v }
      return h
    elsif o.respond_to?(:to_a)
      h = self.new
      o.to_a.each do |i|
        raise ArgumentError, "wrong element type #{i.class} (expected array)" unless i.respond_to?(:to_a)
        k, v = nil
        case i.size
        when 2
          k = i[0]
          v = i[1]
        when 1
          k = i[0]
        else
          raise ArgumentError, "invalid number of elements (#{i.size} for 1..2)"
        end
        h[k] = v
      end
      return h
    end
  end
  unless length % 2 == 0
    raise ArgumentError, 'odd number of arguments for Hash'
  end
  h = self.new
  0.step(length - 2, 2) do |i|
    h[object[i]] = object[i + 1]
  end
  h
end

Instance Method Details

#<(hash) ⇒ Object

call-seq: hash < other -> true or false

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

Raises:



312
313
314
315
316
317
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 312

def <(hash)
  raise TypeError, "can't convert #{hash.class} to Hash" unless Hash === hash
  size < hash.size and all? {|key, val|
    hash.key?(key) and hash[key] == val
  }
end

#<=(hash) ⇒ Object

call-seq: hash <= other -> true or false

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

Raises:



332
333
334
335
336
337
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 332

def <=(hash)
  raise TypeError, "can't convert #{hash.class} to Hash" unless Hash === hash
  size <= hash.size and all? {|key, val|
    hash.key?(key) and hash[key] == val
  }
end

#==(hash) ⇒ Object

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.

ISO 15.2.13.4.1



13
14
15
16
17
18
19
20
21
22
23
24
# File 'mrblib/hash.rb', line 13

def ==(hash)
  return true if self.equal?(hash)
  unless Hash === hash
    return false
  end
  return false if self.size != hash.size
  self.each do |k,v|
    return false unless hash.key?(k)
    return false unless self[k] == hash[k]
  end
  return true
end

#>(hash) ⇒ Object

call-seq: hash > other -> true or false

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

Raises:



352
353
354
355
356
357
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 352

def >(hash)
  raise TypeError, "can't convert #{hash.class} to Hash" unless Hash === hash
  size > hash.size and hash.all? {|key, val|
    key?(key) and self[key] == val
  }
end

#>=(hash) ⇒ Object

call-seq: hash >= other -> true or false

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

Raises:



372
373
374
375
376
377
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 372

def >=(hash)
  raise TypeError, "can't convert #{hash.class} to Hash" unless Hash === hash
  size >= hash.size and hash.all? {|key, val|
    key?(key) and self[key] == val
  }
end

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



829
830
831
832
833
834
835
836
# File 'src/hash.c', line 829

static mrb_value
mrb_hash_aget(mrb_state *mrb, mrb_value self)
{
  mrb_value key;

  mrb_get_args(mrb, "o", &key);
  return mrb_hash_get(mrb, self, key);
}

#[]=(key) ⇒ Object #store(key, value) ⇒ Object

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}


1125
1126
1127
1128
1129
1130
1131
1132
1133
# File 'src/hash.c', line 1125

static mrb_value
mrb_hash_aset(mrb_state *mrb, mrb_value self)
{
  mrb_value key, val;

  mrb_get_args(mrb, "oo", &key, &val);
  mrb_hash_set(mrb, self, key, val);
  return val;
}

#__deleteObject

core of 15.2.13.4.8



1004
1005
1006
1007
1008
1009
1010
1011
1012
# File 'src/hash.c', line 1004

static mrb_value
mrb_hash_delete(mrb_state *mrb, mrb_value self)
{
  mrb_value key;

  mrb_get_args(mrb, "o", &key);
  mrb_hash_modify(mrb, self);
  return mrb_hash_delete_key(mrb, self, key);
}

#_inspect(recur_list) ⇒ Object

internal method for Hash inspection



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
# File 'mrblib/hash.rb', line 189

def _inspect(recur_list)
  return "{}" if self.size == 0
  return "{...}" if recur_list[self.object_id]
  recur_list[self.object_id] = true
  ary=[]
  keys=self.keys
  size=keys.size
  i=0
  while i<size
    k=keys[i]
    ary<<(k._inspect(recur_list) + "=>" + self[k]._inspect(recur_list))
    i+=1
  end
  "{"+ary.join(", ")+"}"
end

#clearHash

Removes all key-value pairs from hsh.

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

Returns:



1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
# File 'src/hash.c', line 1093

MRB_API mrb_value
mrb_hash_clear(mrb_state *mrb, mrb_value hash)
{
  htable *t = RHASH_TBL(hash);

  mrb_hash_modify(mrb, hash);
  if (t) {
    ht_free(mrb, t);
    RHASH_TBL(hash) = NULL;
  }
  return hash;
}

#compactObject

call-seq: hsh.compact -> new_hsh

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 }



133
134
135
136
137
138
139
140
141
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 133

def compact
  h = {}
  self.keys.select{|k|
    self[k] != nil
  }.each {|k|
    h[k] = self[k]
  }
  h
end

#compact!Object

call-seq: hsh.compact! -> hsh

Removes all nil values from the hash. Returns the hash. Returns nil if the hash does not contain nil values.

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



109
110
111
112
113
114
115
116
117
118
119
120
121
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 109

def compact!
  keys = self.keys
  nk = keys.select{|k|
    self[k] != nil
  }
  return nil if (keys.size == nk.size)
  h = {}
  nk.each {|k|
    h[k] = self[k]
  }
  h
  self.replace(h)
end

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

  • (Object)


874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
# File 'src/hash.c', line 874

static mrb_value
mrb_hash_default(mrb_state *mrb, mrb_value hash)
{
  mrb_value key;
  mrb_bool given;

  mrb_get_args(mrb, "|o?", &key, &given);
  if (MRB_RHASH_DEFAULT_P(hash)) {
    if (MRB_RHASH_PROCDEFAULT_P(hash)) {
      if (!given) return mrb_nil_value();
      return mrb_funcall(mrb, RHASH_PROCDEFAULT(hash), "call", 2, hash, key);
    }
    else {
      return RHASH_IFNONE(hash);
    }
  }
  return mrb_nil_value();
}

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

  • (Object)


914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
# File 'src/hash.c', line 914

static mrb_value
mrb_hash_set_default(mrb_state *mrb, mrb_value hash)
{
  mrb_value ifnone;

  mrb_get_args(mrb, "o", &ifnone);
  mrb_hash_modify(mrb, hash);
  mrb_iv_set(mrb, hash, mrb_intern_lit(mrb, "ifnone"), ifnone);
  RHASH(hash)->flags &= ~MRB_HASH_PROC_DEFAULT;
  if (!mrb_nil_p(ifnone)) {
    RHASH(hash)->flags |= MRB_HASH_DEFAULT;
  }
  else {
    RHASH(hash)->flags &= ~MRB_HASH_DEFAULT;
  }
  return ifnone;
}

#default_procObject

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:

  • (Object)


948
949
950
951
952
953
954
955
# File 'src/hash.c', line 948

static mrb_value
mrb_hash_default_proc(mrb_state *mrb, mrb_value hash)
{
  if (MRB_RHASH_PROCDEFAULT_P(hash)) {
    return RHASH_PROCDEFAULT(hash);
  }
  return mrb_nil_value();
}

#default_proc=(proc_obj) ⇒ Proc

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”

Returns:



970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
# File 'src/hash.c', line 970

static mrb_value
mrb_hash_set_default_proc(mrb_state *mrb, mrb_value hash)
{
  mrb_value ifnone;

  mrb_get_args(mrb, "o", &ifnone);
  mrb_hash_modify(mrb, hash);
  mrb_iv_set(mrb, hash, mrb_intern_lit(mrb, "ifnone"), ifnone);
  if (!mrb_nil_p(ifnone)) {
    RHASH(hash)->flags |= MRB_HASH_PROC_DEFAULT;
    RHASH(hash)->flags |= MRB_HASH_DEFAULT;
  }
  else {
    RHASH(hash)->flags &= ~MRB_HASH_DEFAULT;
    RHASH(hash)->flags &= ~MRB_HASH_PROC_DEFAULT;
  }

  return ifnone;
}

#delete(key, &block) ⇒ Object

Delete the element with the key +key+. Return the value of the element if +key+ was found. Return nil if nothing was found. If a block is given, call the block with the value of the element.

ISO 15.2.13.4.8



52
53
54
55
56
57
# File 'mrblib/hash.rb', line 52

def delete(key, &block)
  if block && !self.has_key?(key)
    return block.call(key)
  end
  self.__delete(key)
end

#delete_if(&block) ⇒ Object

call-seq: hsh.delete_if {| key, value | block } -> hsh hsh.delete_if -> an_enumerator

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}


199
200
201
202
203
204
205
206
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 199

def delete_if(&block)
  return to_enum :delete_if unless block

  self.each do |k, v|
    self.delete(k) if block.call(k, v)
  end
  self
end

#dig(idx, *args) ⇒ Object

call-seq: hsh.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+.



387
388
389
390
391
392
393
394
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 387

def dig(idx,*args)
  n = self[idx]
  if args.size > 0
    n&.dig(*args)
  else
    n
  end
end

#each(&block) ⇒ Object Also known as: each_pair

Calls the given block for each element of +self+ and pass the key and value of each element.

call-seq: hsh.each {| key, value | block } -> hsh hsh.each_pair {| key, value | block } -> hsh hsh.each -> an_enumerator hsh.each_pair -> an_enumerator

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

ISO 15.2.13.4.9



81
82
83
84
85
86
87
88
89
90
91
92
93
# File 'mrblib/hash.rb', line 81

def each(&block)
  return to_enum :each unless block

  keys = self.keys
  vals = self.values
  len = self.size
  i = 0
  while i < len
    block.call [keys[i], vals[i]]
    i += 1
  end
  self
end

#each_key(&block) ⇒ Object

Calls the given block for each element of +self+ and pass the key of each element.

call-seq: hsh.each_key {| key | block } -> hsh hsh.each_key -> an_enumerator

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

h = { “a” => 100, “b” => 200 } h.each_key {|key| puts key }

produces:

a b

ISO 15.2.13.4.10



114
115
116
117
118
119
# File 'mrblib/hash.rb', line 114

def each_key(&block)
  return to_enum :each_key unless block

  self.keys.each{|k| block.call(k)}
  self
end

#each_value(&block) ⇒ Object

Calls the given block for each element of +self+ and pass the value of each element.

call-seq: hsh.each_value {| value | block } -> hsh hsh.each_value -> an_enumerator

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

h = { “a” => 100, “b” => 200 } h.each_value {|value| puts value }

produces:

100 200

ISO 15.2.13.4.11



140
141
142
143
144
145
# File 'mrblib/hash.rb', line 140

def each_value(&block)
  return to_enum :each_value unless block

  self.keys.each{|k| block.call(self[k])}
  self
end

#empty?Boolean

Returns true if hsh contains no key-value pairs.

{}.empty? #=> true

Returns:

  • (Boolean)


1184
1185
1186
1187
1188
# File 'src/hash.c', line 1184

static mrb_value
mrb_hash_empty_m(mrb_state *mrb, mrb_value self)
{
  return mrb_bool_value(mrb_hash_empty_p(mrb, self));
}

#eql?(hash) ⇒ Boolean

Returns true if hash and other are both hashes with the same content compared by eql?.

ISO 15.2.13.4.32 (x)

Returns:

  • (Boolean)


31
32
33
34
35
36
37
38
39
40
41
42
# File 'mrblib/hash.rb', line 31

def eql?(hash)
  return true if self.equal?(hash)
  unless Hash === hash
    return false
  end
  return false if self.size != hash.size
  self.each do |k,v|
    return false unless hash.key?(k)
    return false unless self[k].eql?(hash[k])
  end
  return true
end

#fetch(key, none = NONE, &block) ⇒ Object

call-seq: hsh.fetch(key [, default] ) -> obj hsh.fetch(key) {| key | block } -> obj

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


171
172
173
174
175
176
177
178
179
180
181
182
183
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 171

def fetch(key, none=NONE, &block)
  unless self.key?(key)
    if block
      block.call(key)
    elsif none != NONE
      none
    else
      raise KeyError, "Key not found: #{key.inspect}"
    end
  else
    self[key]
  end
end

#fetch_values(*keys, &block) ⇒ Object

call-seq: hsh.fetch_values(key, …) -> array hsh.fetch_values(key, …) { |key| block } -> 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”]



492
493
494
495
496
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 492

def fetch_values(*keys, &block)
  keys.map do |k|
    self.fetch(k, &block)
  end
end

#flatten(level = 1) ⇒ Object

call-seq: hash.flatten -> an_array hash.flatten(level) -> an_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"]


224
225
226
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 224

def flatten(level=1)
  self.to_a.flatten(level)
end

#has_key?Boolean

15.2.13.4.13

Returns:

  • (Boolean)


1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
# File 'src/hash.c', line 1289

static mrb_value
mrb_hash_has_key(mrb_state *mrb, mrb_value hash)
{
  mrb_value key;
  mrb_bool key_p;

  mrb_get_args(mrb, "o", &key);
  key_p = mrb_hash_key_p(mrb, hash, key);
  return mrb_bool_value(key_p);
}

#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.has_value?(100) #=> true h.has_value?(999) #=> false

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean)


1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
# File 'src/hash.c', line 1332

static mrb_value
mrb_hash_has_value(mrb_state *mrb, mrb_value hash)
{
  mrb_value val;
  struct has_v_arg arg;
  
  mrb_get_args(mrb, "o", &val);
  arg.found = FALSE;
  arg.val = val;
  ht_foreach(mrb, RHASH_TBL(hash), hash_has_value_i, &arg);
  return mrb_bool_value(arg.found);
}

#include?Boolean

15.2.13.4.15

Returns:

  • (Boolean)


1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
# File 'src/hash.c', line 1289

static mrb_value
mrb_hash_has_key(mrb_state *mrb, mrb_value hash)
{
  mrb_value key;
  mrb_bool key_p;

  mrb_get_args(mrb, "o", &key);
  key_p = mrb_hash_key_p(mrb, hash, key);
  return mrb_bool_value(key_p);
}

#inspectObject Also known as: to_s

ISO 15.2.13.4.30 (x)



208
209
210
# File 'mrblib/hash.rb', line 208

def inspect
  self._inspect({})
end

#invertObject

call-seq: hsh.invert -> new_hash

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


239
240
241
242
243
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 239

def invert
  h = self.class.new
  self.each {|k, v| h[v] = k }
  h
end

#keep_if(&block) ⇒ Object

call-seq: hsh.keep_if {| key, value | block } -> hsh hsh.keep_if -> an_enumerator

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

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



256
257
258
259
260
261
262
263
264
265
266
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 256

def keep_if(&block)
  return to_enum :keep_if unless block

  keys = []
  self.each do |k, v|
    unless block.call([k, v])
      self.delete(k)
    end
  end
  self
end

#key(val) ⇒ Object

call-seq: hsh.key(value) -> key

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


281
282
283
284
285
286
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 281

def key(val)
  self.each do |k, v|
    return k if v == val
  end
  nil
end

#key?Boolean

15.2.13.4.18

Returns:

  • (Boolean)


1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
# File 'src/hash.c', line 1289

static mrb_value
mrb_hash_has_key(mrb_state *mrb, mrb_value hash)
{
  mrb_value key;
  mrb_bool key_p;

  mrb_get_args(mrb, "o", &key);
  key_p = mrb_hash_key_p(mrb, hash, key);
  return mrb_bool_value(key_p);
}

#keysArray

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:



1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
# File 'src/hash.c', line 1210

MRB_API mrb_value
mrb_hash_keys(mrb_state *mrb, mrb_value hash)
{
  htable *t = RHASH_TBL(hash);
  mrb_int size;
  mrb_value ary;

  if (!t || (size = t->size) == 0)
    return mrb_ary_new(mrb);
  ary = mrb_ary_new_capa(mrb, size);
  ht_foreach(mrb, t, hash_keys_i, (void*)&ary);
  return ary;
}

#lengthFixnum #sizeFixnum

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

Overloads:



1158
1159
1160
1161
1162
1163
# File 'src/hash.c', line 1158

static mrb_value
mrb_hash_size_m(mrb_state *mrb, mrb_value self)
{
  mrb_int size = mrb_hash_size(mrb, self);
  return mrb_fixnum_value(size);
}

#member?Boolean

15.2.13.4.21

Returns:

  • (Boolean)


1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
# File 'src/hash.c', line 1289

static mrb_value
mrb_hash_has_key(mrb_state *mrb, mrb_value hash)
{
  mrb_value key;
  mrb_bool key_p;

  mrb_get_args(mrb, "o", &key);
  key_p = mrb_hash_key_p(mrb, hash, key);
  return mrb_bool_value(key_p);
}

#merge(other, &block) ⇒ Object

Return a hash which contains the content of +self+ and +other+. If a block is given it will be called for each element with a duplicate key. The value of the block will be the final value of this element.

ISO 15.2.13.4.22

Raises:



175
176
177
178
179
180
181
182
183
184
185
186
# File 'mrblib/hash.rb', line 175

def merge(other, &block)
  raise TypeError, "Hash required (#{other.class} given)" unless Hash === other
  h = self.dup
  if block
    other.each_key{|k|
      h[k] = (self.has_key?(k))? block.call(k, self[k], other[k]): other[k]
    }
  else
    other.each_key{|k| h[k] = other[k]}
  end
  h
end

#merge!(other, &block) ⇒ Object Also known as: update

call-seq: hsh.merge!(other_hash) -> hsh hsh.merge!(other_hash){|key, oldval, newval| block} -> hsh

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}

Raises:



84
85
86
87
88
89
90
91
92
93
94
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 84

def merge!(other, &block)
  raise TypeError, "Hash required (#{other.class} given)" unless Hash === other
  if block
    other.each_key{|k|
      self[k] = (self.has_key?(k))? block.call(k, self[k], other[k]): other[k]
    }
  else
    other.each_key{|k| self[k] = other[k]}
  end
  self
end

#rehashHash

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.

keys = (1..17).map{|n| [n]} k = keys[0] h = {} keys.each{|key| h[key] = key[0]} h #=> { [1]=> 1, [2]=> 2, [3]=> 3, [4]=> 4, [5]=> 5, [6]=> 6, [7]=> 7, [8]=> 8, [9]=> 9,[10]=>10,[11]=>11,[12]=>12,[13]=>13,[14]=>14, [15]=>15,[16]=>16,[17]=>17} h[k] #=> 1 k[0] = keys.size + 1 h #=> 1, [2]=> 2, [3]=> 3, [4]=> 4, [5]=> 5, [6]=> 6, [7]=> 7, [8]=> 8, [9]=> 9,[10]=>10,[11]=>11,[12]=>12,[13]=>13,[14]=>14, [15]=>15,[16]=>16,[17]=>17 h[k] #=> nil h.rehash h[k] #=> 1

Returns:



1398
1399
1400
1401
1402
1403
# File 'src/hash.c', line 1398

static mrb_value
mrb_hash_rehash(mrb_state *mrb, mrb_value self)
{
  ht_compact(mrb, RHASH_TBL(self));
  return self;
}

#reject(&block) ⇒ Object

call-seq: hsh.reject {|key, value| block} -> a_hash hsh.reject -> an_enumerator

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}

1.8/1.9 Hash#reject returns Hash; ISO says nothing.



255
256
257
258
259
260
261
262
263
264
265
# File 'mrblib/hash.rb', line 255

def reject(&block)
  return to_enum :reject unless block

  h = {}
  self.each{|k,v|
    unless block.call([k, v])
      h[k] = v
    end
  }
  h
end

#reject!(&block) ⇒ Object

call-seq: hsh.reject! {| key, value | block } -> hsh or nil hsh.reject! -> an_enumerator

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

1.8/1.9 Hash#reject! returns Hash; ISO says nothing.



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
# File 'mrblib/hash.rb', line 224

def reject!(&block)
  return to_enum :reject! unless block

  keys = []
  self.each{|k,v|
    if block.call([k, v])
      keys.push(k)
    end
  }
  return nil if keys.size == 0
  keys.each{|k|
    self.delete(k)
  }
  self
end

#replace(hash) ⇒ Object Also known as: initialize_copy

Replaces the contents of hsh with the contents of other hash

ISO 15.2.13.4.23

Raises:



151
152
153
154
155
156
157
158
159
160
161
162
163
# File 'mrblib/hash.rb', line 151

def replace(hash)
  raise TypeError, "Hash required (#{hash.class} given)" unless Hash === hash
  self.clear
  hash.each_key{|k|
    self[k] = hash[k]
  }
  if hash.default_proc
    self.default_proc = hash.default_proc
  else
    self.default = hash.default
  end
  self
end

#select(&block) ⇒ Object Also known as: filter

call-seq: hsh.select {|key, value| block} -> a_hash hsh.select -> an_enumerator

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}

1.9 Hash#select returns Hash; ISO says nothing



308
309
310
311
312
313
314
315
316
317
318
# File 'mrblib/hash.rb', line 308

def select(&block)
  return to_enum :select unless block

  h = {}
  self.each{|k,v|
    if block.call([k, v])
      h[k] = v
    end
  }
  h
end

#select!(&block) ⇒ Object Also known as: filter!

call-seq: hsh.select! {| key, value | block } -> hsh or nil hsh.select! -> an_enumerator

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

1.9 Hash#select! returns Hash; ISO says nothing.



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
# File 'mrblib/hash.rb', line 277

def select!(&block)
  return to_enum :select! unless block

  keys = []
  self.each{|k,v|
    unless block.call([k, v])
      keys.push(k)
    end
  }
  return nil if keys.size == 0
  keys.each{|k|
    self.delete(k)
  }
  self
end

#shiftArray, 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:



1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
# File 'src/hash.c', line 1055

static mrb_value
mrb_hash_shift(mrb_state *mrb, mrb_value hash)
{
  htable *t = RHASH_TBL(hash);

  mrb_hash_modify(mrb, hash);
  if (t && t->size > 0) {
    mrb_value del_key, del_val;

    ht_shift(mrb, t, &del_key, &del_val);
    mrb_gc_protect(mrb, del_key);
    mrb_gc_protect(mrb, del_val);
    return mrb_assoc_new(mrb, del_key, del_val);
  }

  if (MRB_RHASH_DEFAULT_P(hash)) {
    if (MRB_RHASH_PROCDEFAULT_P(hash)) {
      return mrb_funcall(mrb, RHASH_PROCDEFAULT(hash), "call", 2, hash, mrb_nil_value());
    }
    else {
      return RHASH_IFNONE(hash);
    }
  }
  return mrb_nil_value();
}

#lengthFixnum #sizeFixnum

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

Overloads:



1158
1159
1160
1161
1162
1163
# File 'src/hash.c', line 1158

static mrb_value
mrb_hash_size_m(mrb_state *mrb, mrb_value self)
{
  mrb_int size = mrb_hash_size(mrb, self);
  return mrb_fixnum_value(size);
}

#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) #=> :c=>300

Returns:



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
# File 'mrbgems/mruby-hash-ext/src/hash-ext.c', line 49

static mrb_value
hash_slice(mrb_state *mrb, mrb_value hash)
{
  mrb_value *argv, result;
  mrb_int argc, i;

  mrb_get_args(mrb, "*", &argv, &argc);
  if (argc == 0) {
    return mrb_hash_new_capa(mrb, argc);
  }
  result = mrb_hash_new_capa(mrb, argc);
  for (i = 0; i < argc; i++) {
    mrb_value key = argv[i];
    mrb_value val;

    val = mrb_hash_fetch(mrb, hash, key, mrb_undef_value());
    if (!mrb_undef_p(val)) {
      mrb_hash_set(mrb, result, key, val);
    }
  }
  return result;
}

#[]=(key) ⇒ Object #store(key, value) ⇒ Object

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}


1125
1126
1127
1128
1129
1130
1131
1132
1133
# File 'src/hash.c', line 1125

static mrb_value
mrb_hash_aset(mrb_state *mrb, mrb_value self)
{
  mrb_value key, val;

  mrb_get_args(mrb, "oo", &key, &val);
  mrb_hash_set(mrb, self, key, val);
  return val;
}

#to_hObject

call-seq: hsh.to_h -> hsh or new_hash

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



295
296
297
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 295

def to_h
  self
end

#to_procObject



473
474
475
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 473

def to_proc
  ->x{self[x]}
end

#transform_keys(&block) ⇒ Object

call-seq: hsh.transform_keys {|key| block } -> new_hash hsh.transform_keys -> an_enumerator

Returns a new hash, with the keys computed from running the block once for each key in the hash, and the values unchanged.

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



406
407
408
409
410
411
412
413
414
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 406

def transform_keys(&block)
  return to_enum :transform_keys unless block
  hash = {}
  self.keys.each do |k|
    new_key = block.call(k)
    hash[new_key] = self[k]
  end
  hash
end

#transform_keys!(&block) ⇒ Object

call-seq: hsh.transform_keys! {|key| block } -> hsh hsh.transform_keys! -> an_enumerator

Invokes the given block once for each key in hsh, replacing it with the new key returned by the block, and then returns hsh.

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



425
426
427
428
429
430
431
432
433
434
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 425

def transform_keys!(&block)
  return to_enum :transform_keys! unless block
  self.keys.each do |k|
    value = self[k]
    self.__delete(k)
    k = block.call(k) if block
    self[k] = value
  end
  self
end

#transform_values(&b) ⇒ Object

call-seq: hsh.transform_values {|value| block } -> new_hash hsh.transform_values -> an_enumerator

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

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



446
447
448
449
450
451
452
453
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 446

def transform_values(&b)
  return to_enum :transform_values unless block_given?
  hash = {}
  self.keys.each do |k|
    hash[k] = yield(self[k])
  end
  hash
end

#transform_values!(&b) ⇒ Object

call-seq: hsh.transform_values! {|key| block } -> hsh hsh.transform_values! -> an_enumerator

Invokes the given block once for each value in the hash, replacing with the new value returned by the block, and then returns hsh.

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



465
466
467
468
469
470
471
# File 'mrbgems/mruby-hash-ext/mrblib/hash.rb', line 465

def transform_values!(&b)
  return to_enum :transform_values! unless block_given?
  self.keys.each do |k|
    self[k] = yield(self[k])
  end
  self
end

#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.has_value?(100) #=> true h.has_value?(999) #=> false

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean)


1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
# File 'src/hash.c', line 1332

static mrb_value
mrb_hash_has_value(mrb_state *mrb, mrb_value hash)
{
  mrb_value val;
  struct has_v_arg arg;
  
  mrb_get_args(mrb, "o", &val);
  arg.found = FALSE;
  arg.val = val;
  ht_foreach(mrb, RHASH_TBL(hash), hash_has_value_i, &arg);
  return mrb_bool_value(arg.found);
}

#valuesArray

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:



1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
# File 'src/hash.c', line 1244

MRB_API mrb_value
mrb_hash_values(mrb_state *mrb, mrb_value hash)
{
  htable *t = RHASH_TBL(hash);
  mrb_int size;
  mrb_value ary;

  if (!t || (size = t->size) == 0)
    return mrb_ary_new(mrb);
  ary = mrb_ary_new_capa(mrb, size);
  ht_foreach(mrb, t, hash_vals_i, (void*)&ary);
  return ary;
}

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



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# File 'mrbgems/mruby-hash-ext/src/hash-ext.c', line 22

static mrb_value
hash_values_at(mrb_state *mrb, mrb_value hash)
{
  mrb_value *argv, result;
  mrb_int argc, i;
  int ai;

  mrb_get_args(mrb, "*", &argv, &argc);
  result = mrb_ary_new_capa(mrb, argc);
  ai = mrb_gc_arena_save(mrb);
  for (i = 0; i < argc; i++) {
    mrb_ary_push(mrb, result, mrb_hash_get(mrb, hash, argv[i]));
    mrb_gc_arena_restore(mrb, ai);
  }
  return result;
}