ruby-changes:21357
From: drbrain <ko1@a...>
Date: Wed, 5 Oct 2011 05:59:03 +0900 (JST)
Subject: [ruby-changes:21357] drbrain:r33406 (trunk): * hash.c (Init_Hash): Improve Hash documentation. Patch by Alvaro
drbrain 2011-10-05 05:57:07 +0900 (Wed, 05 Oct 2011) New Revision: 33406 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=33406 Log: * hash.c (Init_Hash): Improve Hash documentation. Patch by Alvaro Pereyra Rabanal. [Ruby 1.9 - Bug #5405] Modified files: trunk/ChangeLog trunk/hash.c Index: ChangeLog =================================================================== --- ChangeLog (revision 33405) +++ ChangeLog (revision 33406) @@ -1,3 +1,8 @@ +Wed Oct 5 05:56:39 2011 Eric Hodel <drbrain@s...> + + * hash.c (Init_Hash): Improve Hash documentation. Patch by Alvaro + Pereyra Rabanal. [Ruby 1.9 - Bug #5405] + Wed Oct 5 05:47:59 2011 Eric Hodel <drbrain@s...> * random.c (Init_Random): Add a top-level comment for Random. Patch Index: hash.c =================================================================== --- hash.c (revision 33405) +++ hash.c (revision 33406) @@ -3150,15 +3150,71 @@ } /* - * A <code>Hash</code> is a collection of key-value pairs. It is - * similar to an <code>Array</code>, except that indexing is done via - * arbitrary keys of any object type, not an integer index. Hashes enumerate - * their values in the order that the corresponding keys were inserted. + * A Hash is a dictionary-like collection of unique keys and their values. + * Also called associative arrays, they are similar to Arrays, but where an + * Array uses integers as its index, a Hash allows you to use any object + * type. * + * Hashes enumerate their values in the order that the corresponding keys + * were inserted. + * + * A Hash can be easily created by using its implicit form: + * + * grades = { "Jane Doe" => 10, "Jim Doe" => 6 } + * + * Hashes allow an alternate syntax form when your keys are always symbols. + * Instead of + * + * options = { :font_size => 10, :font_family => "Arial" } + * + * You could write it as: + * + * options = { font_size: 10, font_family: "Arial" } + * + * Each named key is a symbol you can access in hash: + * + * options[:font_size] # => 10 + * + * A Hash can also be created through its ::new method: + * + * grades = Hash.new + * grades["Dorothy Doe"] = 9 + * * Hashes have a <em>default value</em> that is returned when accessing - * keys that do not exist in the hash. By default, that value is - * <code>nil</code>. + * keys that do not exist in the hash. If no default is set +nil+ is used. + * You can set the default value by sending it as an argument to Hash.new: * + * grades = Hash.new(0) + * + * Or by using the #default= method: + * + * grades = {"Timmy Doe" => 8} + * grades.default = 0 + * + * Accessing a value in a Hash requires using its key: + * + * puts grades["Jane Doe"] # => 10 + * + * === Common Uses + * + * Hashes are an easy way to represent data structures, such as + * + * books = {} + * books[:matz] = "The Ruby Language" + * books[:black] = "The Well-Grounded Rubyist" + * + * Hashes are also commonly used as a way to have named parameters in + * functions. Note that no brackets are used below. If a hash is the last + * argument on a method call, no braces are needed, thus creating a really + * clean interface: + * + * Person.create(name: "John Doe", age: 27) + * + * def self.create(params) + * @name = params[:name] + * @age = params[:age] + * end + * */ void -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/