ruby-changes:61305
From: Burdette <ko1@a...>
Date: Thu, 21 May 2020 07:57:54 +0900 (JST)
Subject: [ruby-changes:61305] 140d4e4a5f (master): [ci skip] Enhanced rdoc for Hash (#3121)
https://git.ruby-lang.org/ruby.git/commit/?id=140d4e4a5f From 140d4e4a5fb4480feeb59565464f197e6a09587d Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Wed, 20 May 2020 17:57:38 -0500 Subject: [ci skip] Enhanced rdoc for Hash (#3121) diff --git a/hash.c b/hash.c index 79fe433..a8077f9 100644 --- a/hash.c +++ b/hash.c @@ -1978,6 +1978,8 @@ rb_check_hash_type(VALUE hash) https://github.com/ruby/ruby/blob/trunk/hash.c#L1978 * s.respond_to?(:to_hash) # => false * Hash.try_convert(s) # => nil * + * --- + * * Raises an exception unless <tt>obj.to_hash</tt> returns a Hash object: * class BadToHash * def to_hash @@ -2058,7 +2060,7 @@ rb_hash_rehash_i(VALUE key, VALUE value, VALUE arg) https://github.com/ruby/ruby/blob/trunk/hash.c#L2060 /* * call-seq: - * hsh.rehash -> self + * hash.rehash -> self * * Rebuilds the hash table by recomputing the hash index for each key; * returns <tt>self</tt>. @@ -2150,15 +2152,16 @@ rb_hash_stlike_lookup(VALUE hash, st_data_t key, st_data_t *pval) https://github.com/ruby/ruby/blob/trunk/hash.c#L2152 /* * call-seq: - * hsh[key] -> value + * hash[key] -> value * - * Element Reference---Retrieves the <i>value</i> object corresponding - * to the <i>key</i> object. If not found, returns the default value (see - * Hash::new for details). + * Returns the value associated with the given +key+, if found: + * h = {foo: 0, bar: 1, baz: 2} + * h[:foo] # => 0 * - * h = { "a" => 100, "b" => 200 } - * h["a"] #=> 100 - * h["c"] #=> nil + * If +key+ is not found, returns a default value + * (see {Default Values}[#class-Hash-label-Default+Values]): + * h = {foo: 0, bar: 1, baz: 2} + * h[:nosuch] # => nil * */ @@ -2196,31 +2199,52 @@ rb_hash_lookup(VALUE hash, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L2199 /* * call-seq: - * hsh.fetch(key [, default] ) -> obj - * hsh.fetch(key) {| key | block } -> obj + * hash.fetch(key) -> value + * hash.fetch(key, default) -> value + * hash.fetch(key) { |key| ... } -> value * - * 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 <i>default</i> is given, - * then that will be returned; if the optional code block is specified, - * then that will be run and its result returned. + * Returns the value for the given +key+. * - * 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") + * --- * - * <em>produces:</em> + * When neither +default+ nor a block given: + * * If +key+ is found, returns its associated value. + * * Otherwise, raises an exception: + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch(:bar) # => 1 + * # Raises KeyError (key not found: :nosuch): + * h.fetch(:nosuch) + * + * When +default+ is given, but no block: + * * If +key+ is found, returns its associated value. + * * Otherwise, returns the given +default+: + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch(:bar, :default) # => 1 + * h.fetch(:nosuch, :default) # => :default + * + * When a block is given, but no +default+: + * * If +key+ is found, returns its associated value. + * * Otherwise, calls the block with +key+, and returns the block's return value. + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch(:bar) { |key| fail 'Ignored'} # => 1 + * h.fetch(:nosuch) { |key| "Value for #{key}"} # => "Value for nosuch" + * + * When both +default+ and a block are given: + * * Ignores +default+ and issues a warning: 'block supersedes default value argument'. + * * If +key+ is found, returns its associated value. + * * Otherwise, calls the block with +key+, and returns the block's return value. + * h = {foo: 0, bar: 1, baz: 2} + * h.fetch(:bar, :default) { |key| fail 'Ignored'} # => 1 + * h.fetch(:nosuch, :default) { |key| "Value for #{key}"} # => "Value for nosuch" * - * prog.rb:2:in `fetch': key not found (KeyError) - * from prog.rb:2 + * --- * + * Raises an exception if +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(BasicObject.new) */ static VALUE @@ -2267,23 +2291,23 @@ rb_hash_fetch(VALUE hash, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L2291 /* * call-seq: - * hsh.default(key=nil) -> obj + * hash.default -> value + * hash.default(key) -> value * - * Returns the default value, the value that would be returned by - * <i>hsh</i>[<i>key</i>] if <i>key</i> did not exist in <i>hsh</i>. - * See also Hash::new and Hash#default=. + * With no argument, returns the current default value: + * h = {} + * h.default # => nil + * h.default = false + * h.default # => false * - * h = Hash.new #=> {} - * h.default #=> nil - * h.default(2) #=> nil + * With +key+ given, returns the default value for +key+, + * regardless of whether that key exists: + * h = {} + * h.default(:nosuch) # => nil * - * h = Hash.new("cat") #=> {} - * h.default #=> "cat" - * h.default(2) #=> "cat" + * The returned value will be determined either by the default proc or by the default value. + * See {Default Values}[#class-Hash-label-Default+Values]. * - * h = Hash.new {|h,k| h[k] = k.to_i*10} #=> {} - * h.default #=> nil - * h.default(2) #=> 20 */ static VALUE @@ -2302,22 +2326,15 @@ rb_hash_default(int argc, VALUE *argv, VALUE hash) https://github.com/ruby/ruby/blob/trunk/hash.c#L2326 /* * call-seq: - * hsh.default = obj -> obj + * hash.default = value -> value * - * 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. + * Sets the default value to +value+, returning +value+: + * h = {} + * h.default # => nil + * h.default = false # => false + * h.default # => false * - * 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> + * See {Default Values}[#class-Hash-label-Default+Values]. */ static VALUE -- cgit v0.10.2 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/