diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-10-04 20:57:07 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-10-04 20:57:07 +0000 |
commit | 6f8f555d2f8d46a4358d3aecdc6914022c20c5cb (patch) | |
tree | d9a39bce706ecefb42cbd59de8bb9d5f8340c941 /hash.c | |
parent | 9654a4c9855d2dff19dbc2e446949b43e31dcd3d (diff) | |
download | ruby-6f8f555d2f8d46a4358d3aecdc6914022c20c5cb.tar.gz |
* hash.c (Init_Hash): Improve Hash documentation. Patch by Alvaro
Pereyra Rabanal. [Ruby 1.9 - Bug #5405]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33406 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'hash.c')
-rw-r--r-- | hash.c | 68 |
1 files changed, 62 insertions, 6 deletions
@@ -3150,14 +3150,70 @@ env_update(VALUE env, VALUE hash) } /* - * 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 * */ |