Project

General

Profile

Bug #5405 ยป 0001-adding-documentation-for-Hash.patch

View differences:

hash.c
3150 3150
}
3151 3151

  
3152 3152
/*
3153
 *  A <code>Hash</code> is a collection of key-value pairs. It is
3154
 *  similar to an <code>Array</code>, except that indexing is done via
3155
 *  arbitrary keys of any object type, not an integer index. Hashes enumerate
3156
 *  their values in the order that the corresponding keys were inserted.
3153
 *  A <code>Hash</code> is a dictionary-like collection of unique keys and 
3154
 *  their values. Also called associative arrays, they are similar to
3155
 *  Arrays, but where an <code>Array</code> uses integers 
3156
 *  as its index, a <code>Hash</code> allows you to use any object type. 
3157
 *
3158
 *  Hashes enumerate their values in the order that
3159
 *  the corresponding keys were inserted. 
3160
 *
3161
 *  A Hash can be easily created by using its implicit form:
3162
 *
3163
 *    grades = {"Jane Doe" => 10, "Jim Doe" => 6}
3164
 *  
3165
 *  Hashes allow an alternate syntax form when your keys are always symbols.
3166
 *  Instead of 
3167
 *
3168
 *    options = {:font_size => 10, :font_family => "Arial"}
3169
 * 
3170
 *  You could write it as: 
3171
 *
3172
 *    options = {font_size: 10, font_family: "Arial"}
3173
 * 
3174
 *  Each named key is a symbol you can access in hash:
3175
 *
3176
 *    options[:font_size]  #=> 10
3177
 *
3178
 *  A Hash can also be created through its <code>new</code> method:
3179
 *
3180
 *    grades = Hash.new
3181
 *    grades["Dorothy Doe"] = 9
3157 3182
 *
3158 3183
 *  Hashes have a <em>default value</em> that is returned when accessing
3159 3184
 *  keys that do not exist in the hash. By default, that value is
3160
 *  <code>nil</code>.
3185
 *  <code>nil</code>. You can setup its default value by sending it as
3186
 *  an argument on the Hash initialization: 
3187
 *
3188
 *    grades = Hash.new(0)
3189
 *
3190
 *  Or by using its <code>default</code> method:
3191
 *
3192
 *    grades = {"Timmy Doe" => 8}
3193
 *    grades.default = 0
3194
 *     
3195
 *  Accessing a Hash requires using its key:
3196
 *
3197
 *    puts grades["Jane Doe"] #=> 10
3198
 *   
3199
 *  === Common Uses
3200
 *
3201
 *  Hashes are an easy way to represent data structures, such as
3202
 *
3203
 *    books         = {}
3204
 *    books[:matz]  = "The Ruby Language"
3205
 *    books[:black] = "The Well-Grounded Rubyist"
3206
 * 
3207
 *  Hashes are also commonly used as a way to have named parameters
3208
 *  in functions. Note that no brackes are used below. If a hash is 
3209
 *  the last argument on a method call, no braces are needed,  
3210
 *  thus creating a really clean interface: 
3211
 *  
3212
 *    Person.create(name: "John Doe", age: 27)
3213
 *
3214
 *    def self.create(params)
3215
 *      @name = params[:name]
3216
 *      @age  = params[:age]
3217
 *    end
3218
 *
3161 3219
 *
3162 3220
 */
3163 3221

  
3164
-