diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2020-05-23 20:35:05 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-05-23 20:35:05 -0500 |
commit | 8b8b7c78762f1ec7446f4a35c7bb8093d78fb248 (patch) | |
tree | 403da3e1a3054dec91f6c41d7d43145f3f6a2be7 /hash.c | |
parent | 0b161774d92cd35e42bf18cd7ae9e4f6c28192da (diff) |
Enhanced Rdoc for Hash (#3139)
Notes
Notes:
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'hash.c')
-rw-r--r-- | hash.c | 149 |
1 files changed, 109 insertions, 40 deletions
@@ -2382,6 +2382,7 @@ rb_hash_default_proc(VALUE hash) * See {Default Values}[#class-Hash-label-Default+Values]. * * --- + * * Raises an exception if +proc+ is not a \Proc: * # Raises TypeError (wrong default_proc type Integer (expected Proc)): * h.default_proc = 1 @@ -2755,7 +2756,7 @@ reject_i(VALUE key, VALUE value, VALUE result) * h1 = h.reject {|key, value| key.start_with?('b') } * h1 # => {:foo=>0} * - * Returns a new Enumerator if no block given: + * Returns a new \Enumerator if no block given: * h = {foo: 0, bar: 1, baz: 2} * e = h.reject # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:reject> * h1 = e.each {|key, value| key.start_with?('b') } @@ -2783,13 +2784,21 @@ rb_hash_reject(VALUE hash) /* * call-seq: - * hsh.slice(*keys) -> a_hash + * hash.slice(*keys) -> new_hash + * + * Returns a new \Hash object containing the entries for the given +keys+: + * h = {foo: 0, bar: 1, baz: 2} + * h1 = h.slice(:baz, :foo) + * h1 # => {:baz=>2, :foo=>0} + * h1.equal?(h) # => false * - * 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} + * Raises an exception if any given key is invalid + * (see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]): + * h = {foo: 0, bar: 1, baz: 2} + * # Raises NoMethodError (undefined method `hash' for #<BasicObject:>): + * h.slice(:foo, BasicObject.new) */ static VALUE @@ -2814,14 +2823,24 @@ rb_hash_slice(int argc, VALUE *argv, VALUE hash) } /* - * call-seq: - * hsh.values_at(key, ...) -> array + * call-seq: + * hash.values_at(*keys) -> new_array + * + * Returns a new \Array containing values for the given +keys+: + * h = {foo: 0, bar: 1, baz: 2} + * h.values_at(:foo, :baz) # => [0, 2] * - * Return an array containing the values associated with the given keys. - * Also see Hash.select. + * Returns an empty Array if no arguments given: + * h = {foo: 0, bar: 1, baz: 2} + * h.values_at # => [] + * + * --- * - * h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" } - * h.values_at("cow", "cat") #=> ["bovine", "feline"] + * Raises an exception if any given key is invalid + * (see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]): + * h = {foo: 0, bar: 1, baz: 2} + * # Raises NoMethodError (undefined method `hash' for #<BasicObject:>) + * h.values_at(BasicObject.new) */ VALUE @@ -2837,19 +2856,35 @@ rb_hash_values_at(int argc, VALUE *argv, VALUE hash) } /* - * call-seq: - * hsh.fetch_values(key, ...) -> array - * hsh.fetch_values(key, ...) { |key| block } -> array + * call-seq: + * hash.fetch_values(*keys) -> new_array + * hash.fetch_values(*keys) {|key| ... } -> new_array + * + * Returns a new \Array containing the values associated with the given keys *keys: + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch_values(:baz, :foo) # => [2, 0] + * + * Returns a new empty \Array if no arguments given: + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch_values # => [] * - * 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. + * When a block given, calls the block with each missing key, + * treating the block's return value as the value for that key: + * h = {foo: 0, bar: 1, baz: 2} + * values = h.fetch_values(:bar, :foo, :bad, :bam) {|key| key.to_s} + * values # => [1, 0, "bad", "bam"] * - * 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"] + * Raises an exception if any given key is not found: + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch_values(:baz, :nosuch) # Raises KeyError (key not found: :nosuch) + * + * Raises an exception if any given key is invalid + * (see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]): + * h = {foo: 0, bar: 1, baz: 2} + * # Raises NoMethodError (undefined method `hash' for #<BasicObject:>): + * h.fetch_values(:baz, BasicObject.new) */ static VALUE @@ -2875,20 +2910,32 @@ select_i(VALUE key, VALUE value, VALUE result) /* * call-seq: - * hsh.select {|key, value| block} -> a_hash - * hsh.select -> an_enumerator - * hsh.filter {|key, value| block} -> a_hash - * hsh.filter -> an_enumerator + * hash.select {|key, value| ... } -> new_hash + * hash.select -> new_enumerator + * hash.filter {|key, value| ... } -> new_hash + * hash.filter -> new_enumerator * - * Returns a new hash consisting of entries for which the block returns true. + * Hash#filter is an alias for Hash#select. * - * If no block is given, an enumerator is returned instead. + * Returns a new \Hash object whose entries are those for which the block returns a truthy value: + * h = {foo: 0, bar: 1, baz: 2} + * h1 = h.select {|key, value| value < 2 } + * h1 # => {:foo=>0, :bar=>1} + * h1.equal?(h) # => false * - * h = { "a" => 100, "b" => 200, "c" => 300 } - * h.select {|k,v| k > "a"} #=> {"b" => 200, "c" => 300} - * h.select {|k,v| v < 200} #=> {"a" => 100} + * Returns a new \Enumerator if no block given: + * h = {foo: 0, bar: 1, baz: 2} + * e = h.select # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select> + * h1 = e.each {|key, value| value < 2 } + * h1 # => {:foo=>0, :bar=>1} + * h1.equal?(h) # => false * - * Hash#filter is an alias for Hash#select. + * --- + * + * Raises an exception if the block attempts to add a new key: + * h = {foo: 0, bar: 1, baz: 2} + * # Raises RuntimeError (can't add a new key into hash during iteration): + * h.select {|key, value| h[:new_key] = 3 } */ static VALUE @@ -2915,15 +2962,37 @@ keep_if_i(VALUE key, VALUE value, VALUE hash) /* * call-seq: - * hsh.select! {| key, value | block } -> hsh or nil - * hsh.select! -> an_enumerator - * hsh.filter! {| key, value | block } -> hsh or nil - * hsh.filter! -> an_enumerator - * - * Equivalent to Hash#keep_if, but returns - * +nil+ if no changes were made. + * hash.select! {|key, value| ... } -> self or nil + * hash.select! -> new_enumerator + * hash.filter! {|key, value| ... } -> self or nil + * hash.filter! -> new_enumerator * * Hash#filter! is an alias for Hash#select!. + * + * Returns +self+, whose entries are those for which the block returns a truthy value: + * h = {foo: 0, bar: 1, baz: 2} + * h1 = h.select! {|key, value| value < 2 } + * h # => {:foo=>0, :bar=>1} + * h1.equal?(h) # => true + * + * Returns +nil+ if no entries were removed: + * h = {foo: 0, bar: 1, baz: 2} + * h.select! {|key, value| value < 3} # => nil + * h # => {:foo=>0, :bar=>1, :baz=>2} + * + * Returns a new \Enumerator if no block given: + * h = {foo: 0, bar: 1, baz: 2} + * e = h.select! # => #<Enumerator: {:foo=>0, :bar=>1, :baz=>2}:select!> + * h1 = e.each { |key, value| value < 2 } + * h1 # => {:foo=>0, :bar=>1} + * h1.equal?(h) # => true + * + * --- + * + * Raises an exception if the block attempts to add a new key: + * h = {foo: 0, bar: 1, baz: 2} + * # Raises RuntimeError (can't add a new key into hash during iteration) + * h.select! {|key, value| h[:new_key] = 3 } */ static VALUE @@ -6775,7 +6844,7 @@ env_update(VALUE env, VALUE hash) * - Other order-sensitive methods such as <tt>shift</tt>, <tt>keys</tt>, <tt>values</tt>. * - The String returned by method <tt>inspect</tt>. * - * A new Hash has its initial ordering per the given entries: + * A new \Hash has its initial ordering per the given entries: * * h = Hash[foo: 0, bar: 1] * h # => {:foo=>0, :bar=>1} |