[前][次][番号順一覧][スレッド一覧]

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/

[前][次][番号順一覧][スレッド一覧]