From 36cc53daaec6b80f83d04edd6e11d8598ba2194a Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 25 Aug 2020 10:47:23 -0500 Subject: Comply with guide for method doc: hash.c (#3451) Methods: ::new ::[] ::try_convert #rehash #[] #fetch #default #default= #default_proc #default_proc= --- hash.c | 183 +++++++++++++++++------------------------------------------------ 1 file changed, 48 insertions(+), 135 deletions(-) (limited to 'hash.c') diff --git a/hash.c b/hash.c index 1594e84c97..3be0d0adc2 100644 --- a/hash.c +++ b/hash.c @@ -1740,49 +1740,33 @@ set_proc_default(VALUE hash, VALUE proc) /* * call-seq: - * Hash.new -> new_hash - * Hash.new(default_value) -> new_hash - * Hash.new{|hash, key| hash[key] = default_value} -> new_hash + * Hash.new(default_value = nil) -> new_hash + * Hash.new {|hash, key| ... } -> new_hash * * Returns a new empty \Hash object. * * The initial default value and initial default proc for the new hash * depend on which form above was used. See {Default Values}[#class-Hash-label-Default+Values]. * - * If neither argument nor block given, + * If neither an argument nor a block given, * initializes both the default value and the default proc to nil: * h = Hash.new - * h # => {} - * h.class # => Hash * h.default # => nil * h.default_proc # => nil - * h[:nosuch] # => nil * * If argument default_value given but no block given, * initializes the default value to the given default_value * and the default proc to nil: - * * h = Hash.new(false) - * h # => {} * h.default # => false * h.default_proc # => nil - * h[:nosuch] # => false * - * If block given but no argument given, stores the block as the default proc, + * If a block given but no argument, stores the block as the default proc * and sets the default value to nil: - * - * h = Hash.new { |hash, key| "Default value for #{key}" } - * h # => {} + * h = Hash.new {|hash, key| "Default value for #{key}" } * h.default # => nil * h.default_proc.class # => Proc * h[:nosuch] # => "Default value for nosuch" - * - * --- - * - * Raises an exception if both argument default_value and a block are given: - * - * # Raises ArgumentError (wrong number of arguments (given 1, expected 0)): - * Hash.new(0) { } */ static VALUE @@ -1808,68 +1792,30 @@ rb_hash_initialize(int argc, VALUE *argv, VALUE hash) /* * call-seq: * Hash[] -> new_empty_hash + * Hash[hash] -> new_hash * Hash[ [*2_element_arrays] ] -> new_hash * Hash[*objects] -> new_hash - * Hash[hash] -> new_hash * * Returns a new \Hash object populated with the given objects, if any. + * See Hash::new. * - * The initial default value and default proc are set to nil - * (see {Default Values}[#class-Hash-label-Default+Values]): + * With no argument, returns a new empty \Hash. * - * h = Hash[] - * h # => {} - * h.class # => Hash - * h.default # => nil - * h.default_proc # => nil + * When the single given argument is a \Hash, + * returns a new \Hash populated with the entries from the given \Hash. + * h = {foo: 0, bar: 1, baz: 2} + * Hash[h] # => {:foo=>0, :bar=>1, :baz=>2} * - * When argument [*2_element_arrays] is given, - * each element of the outer array must be a 2-element array; + * When the single given argument is an \Array of 2-element Arrays, * returns a new \Hash object wherein each 2-element array forms a key-value entry: - * * Hash[ [ [:foo, 0], [:bar, 1] ] ] # => {:foo=>0, :bar=>1} * - * When arguments *objects are given, - * the argument count must be an even number; - * returns a new \Hash object wherein each successive pair of arguments has become a key-value entry: - * - * Hash[] # => {} + * When the argument count is an even number; + * returns a new \Hash object wherein each successive pair of arguments + * has become a key-value entry: * Hash[:foo, 0, :bar, 1] # => {:foo=>0, :bar=>1} * - * When argument hash is given, - * the argument must be a \Hash: - * class Foo - * def to_hash - * {foo: 0, bar: 1} - * end - * end - * Hash[Foo.new] # => {:foo=>0, :bar=>1} - * - * --- - * - * Raises an exception if the argument count is 1, - * but the argument is not an array of 2-element arrays or a \Hash: - * # Raises ArgumentError (odd number of arguments for Hash): - * Hash[:foo] - * # Raises ArgumentError (invalid number of elements (3 for 1..2)): - * Hash[ [ [:foo, 0, 1] ] ] - * - * Raises an exception if the argument count is odd and greater than 1: - * - * # Raises ArgumentError (odd number of arguments for Hash): - * Hash[0, 1, 2] - * - * Raises an exception if the argument is an array containing an element - * that is not a 2-element array: - * - * # Raises ArgumentError (wrong element type Symbol at 0 (expected array)): - * Hash[ [ :foo ] ] - * - * Raises an exception if the argument is an array containing an element - * that is an array of size different from 2: - * - * # Raises ArgumentError (invalid number of elements (3 for 1..2)): - * Hash[ [ [0, 1, 2] ] ] + * Raises an exception if the argument list does not conform to any of the above. */ static VALUE @@ -1938,28 +1884,16 @@ rb_check_hash_type(VALUE hash) /* * call-seq: - * Hash.try_convert(obj) -> new_hash or nil + * Hash.try_convert(obj) -> obj, new_hash, or nil * - * Returns the Hash object created by calling obj.to_hash: - * require 'csv' # => true - * row = CSV::Row.new(['Name', 'Age'], ['Bob', 45]) - * row.respond_to?(:to_hash) # => true - * Hash.try_convert(row) # => {"Name"=>"Bob", "Age"=>45} + * If +obj+ is a \Hash object, returns +obj+. * - * Returns the given obj if it is a Hash. + * Otherwise if +obj+ responds to :to_hash, + * calls obj.to_hash and returns the result. * - * Returns nil unless obj.respond_to?(:to_hash). - * - * --- + * Returns +nil+ if +obj+ does not respond to :to_hash * - * Raises an exception unless obj.to_hash returns a \Hash object: - * class BadToHash - * def to_hash - * 1 - * end - * end - * bad = BadToHash.new - * Hash.try_convert(bad) # Raises TypeError (can't convert BadToHash to Hash (BadToHash#to_hash gives Integer)) + * Raises an exception unless obj.to_hash returns a \Hash object. */ static VALUE rb_hash_s_try_convert(VALUE dummy, VALUE hash) @@ -2040,14 +1974,6 @@ rb_hash_rehash_i(VALUE key, VALUE value, VALUE arg) * The hash table becomes invalid if the hash value of a key * has changed after the entry was created. * See {Modifying an Active Hash Key}[#class-Hash-label-Modifying+an+Active+Hash+Key]. - * - * --- - * - * Raises an exception if called while an iterator is traversing the hash: - * - * h = {foo: 0, bar: 1, baz: 2} - * # Raises RuntimeError (rehash during iteration): - * h.each { |x| h.rehash } */ VALUE @@ -2134,7 +2060,6 @@ rb_hash_stlike_lookup(VALUE hash, st_data_t key, st_data_t *pval) * (see {Default Values}[#class-Hash-label-Default+Values]): * h = {foo: 0, bar: 1, baz: 2} * h[:nosuch] # => nil - * */ VALUE @@ -2172,28 +2097,25 @@ rb_hash_lookup(VALUE hash, VALUE key) /* * call-seq: * hash.fetch(key) -> value - * hash.fetch(key, default) -> value - * hash.fetch(key) { |key| ... } -> value + * hash.fetch(key, default_value) -> value + * hash.fetch(key) {|key| ... } -> value * - * Returns the value for the given +key+. + * Returns the value for the given +key+, if found. * h = {foo: 0, bar: 1, baz: 2} * h.fetch(:bar) # => 1 * - * If +key+ is not found, then the given +default+ or - * block (if any) will be used: - * + * If +key+ is not found and no block was given, + * returns +default_value+: * {}.fetch(:nosuch, :default) # => :default - * {}.fetch(:nosuch) { |key| "No #{key}"}) # => "No nosuch" - * - * If neither is given, an error is raised: + * {}.fetch(:nosuch) # => nil * - * {}.fetch(:foo) # => KeyError (key not found: :nosuch) + * If +key+ is not found and a block was given, + * yields +key+ to the block and returns the block's return value: + * {}.fetch(:nosuch) {|key| "No key #{key}"} # => "No key nosuch" * - * Note that the #default or #default_proc are always ignored by `fetch` + * Raises KeyError if neither +default_value+ nor a block was given. * - * h = Hash.new(0) - * h[:nosuch] # => 0 - * h.fetch(:nosuch) # => KeyError + * Note that this method does not use the values of either #default or #default_proc. */ static VALUE @@ -2243,20 +2165,19 @@ rb_hash_fetch(VALUE hash, VALUE key) * hash.default -> value * hash.default(key) -> value * + * Returns the default value for the given +key+. + * The returned value will be determined either by the default proc or by the default value. + * See {Default Values}[#class-Hash-label-Default+Values]. + * * With no argument, returns the current default value: * h = {} * h.default # => nil - * h.default = false - * h.default # => false * - * With +key+ given, returns the default value for +key+, + * If +key+ is given, returns the default value for +key+, * regardless of whether that key exists: - * h = Hash.new { |hash, key| hash[key] = "No #{key}"} - # h[:foo] = "Hello" - * h.default(:foo) # => "No foo" - * - * 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 { |hash, key| hash[key] = "No key #{key}"} + * h[:foo] = "Hello" + * h.default(:foo) # => "No key foo" */ static VALUE @@ -2277,7 +2198,7 @@ rb_hash_default(int argc, VALUE *argv, VALUE hash) * call-seq: * hash.default = value -> value * - * Sets the default value to +value+, returning +value+: + * Sets the default value to +value+; returns +value+: * h = {} * h.default # => nil * h.default = false # => false @@ -2298,13 +2219,12 @@ rb_hash_set_default(VALUE hash, VALUE ifnone) * call-seq: * hash.default_proc -> proc or nil * - * Returns the default proc: + * Returns the default proc for +self+ + * (see {Default Values}[#class-Hash-label-Default+Values]): * h = {} * h.default_proc # => nil - * h.default_proc = proc { |hash, key| "Default value for #{key}" } + * h.default_proc = proc {|hash, key| "Default value for #{key}" } * h.default_proc.class # => Proc - * - * See {Default Values}[#class-Hash-label-Default+Values]. */ static VALUE @@ -2320,21 +2240,14 @@ rb_hash_default_proc(VALUE hash) * call-seq: * hash.default_proc = proc -> proc * - * Sets the default proc to +proc+: + * Sets the default proc for +self+ to +proc+: + * (see {Default Values}[#class-Hash-label-Default+Values]): * h = {} * h.default_proc # => nil * h.default_proc = proc { |hash, key| "Default value for #{key}" } * h.default_proc.class # => Proc * h.default_proc = nil * h.default_proc # => nil - * - * 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 */ VALUE -- cgit v1.2.3