diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2020-04-13 08:57:10 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-04-14 01:57:10 +1200 |
commit | c28e230ab5865df55399431239c5fdd9b54206d6 (patch) | |
tree | d098c02098e8729232a0b2ba8ea5776face1dba5 | |
parent | 67bcac879a2e0ddfb4e7bbd7cb5e5401422de76a (diff) | |
download | ruby-c28e230ab5865df55399431239c5fdd9b54206d6.tar.gz |
Improve Hash documentation.
-rw-r--r-- | hash.c | 97 |
1 files changed, 62 insertions, 35 deletions
@@ -1747,36 +1747,45 @@ set_proc_default(VALUE hash, VALUE proc) /* * call-seq: * Hash.new -> new_hash - * Hash.new(obj) -> new_hash + * Hash.new(default_value) -> new_hash * Hash.new {|hash, key| block } -> new_hash * - * 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 <code>new</code> used to create the hash. In - * the first form, the access returns <code>nil</code>. If - * <i>obj</i> is specified, this single object will be used for - * all <em>default values</em>. 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"] + * 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, + * initializes both the default value and the default proc to <tt>nil</tt>: + * h = Hash.new + * h # => {} + * h.class # => Hash + * h.default # => nil + * h.default_proc # => nil + * h[:nosuch] # => nil + * + * If argument <tt>default_value</tt> given but no block given, + * initializes the default value to the given <tt>default_value</tt> + * and the default proc to <tt>nil</tt>: + * + * 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, + * and sets the default value to <tt>nil</tt>: + * + * h = Hash.new { |hash, key| "Default value for #{key}" } + * h # => {} + * h.default # => nil + * h.default_proc.class # => Proc + * h[:nosuch] # => "Default value for nosuch" + * + * Raises an exception if both argument <tt>default_value</tt> and a block are given: + * + * Hash.new(0) { } # Raises ArgumentError (wrong number of arguments (given 1, expected 0)) * */ static VALUE @@ -1885,14 +1894,32 @@ rb_check_hash_type(VALUE hash) /* * call-seq: - * Hash.try_convert(obj) -> hash or nil - * - * Try to convert <i>obj</i> into a hash, using to_hash method. - * Returns converted hash or nil if <i>obj</i> cannot be converted - * for any reason. - * - * Hash.try_convert({1=>2}) # => {1=>2} - * Hash.try_convert("1=>2") # => nil + * Hash.try_convert(obj) -> new_hash or nil + * + * Returns the Hash object created by calling <tt>obj.to_hash</tt>: + * 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} + * + * Returns the given <tt>obj</tt> if it is a Hash: + * h = {} + * h1 = Hash.try_convert(h) + * h1.equal?(h) # => true # Identity check + * + * Returns <tt>nil</tt> unless <tt>obj.respond_to?(:to_hash)</tt>: + * s = 'foo' + * 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 + * 1 + * end + * end + * bad = BadToHash.new + * Hash.try_convert(bad) # Raises TypeError (can't convert BadToHash to Hash (BadToHash#to_hash gives Integer)) */ static VALUE rb_hash_s_try_convert(VALUE dummy, VALUE hash) |