-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.methods.html
502 lines (358 loc) · 34.5 KB
/
file.methods.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>File: Methods — Ruby-2.6.10</title>
<link rel='stylesheet' type='text/css' href='../css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='../css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='../css/y_style.css' />
<link rel='stylesheet' type='text/css' href='../css/y_list.css' />
<link rel='stylesheet' type='text/css' href='../css/y_color.css' />
<script type='text/javascript'>
var pathId = "methods",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='../js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='../js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a id='home_no_xhr' href='/'>Home</a> »
<a href='.'>Ruby-2.6.10</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>File: Methods ▲</a></span>
</div>
<a id='list_href' href="file_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<h1 id="label-Methods">Methods</h1>
<p>Methods implement the functionality of your program. Here is a simple method definition:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_one_plus_one'>one_plus_one</span>
<span class='int'>1</span> <span class='op'>+</span> <span class='int'>1</span>
<span class='kw'>end</span></code></pre>
<p>A method definition consists of the <code>def</code> keyword, a method name, the body of the method, <code>return</code> value and the <code>end</code> keyword. When called the method will execute the body of the method. This method returns <code>2</code>.</p>
<p>This section only covers defining methods. See also the <a href="file.calling_methods.html" title="syntax documentation on calling methods">syntax documentation on calling methods</a>.</p>
<h2 id="label-Method+Names">Method Names</h2>
<p>Method names may be one of the operators or must start a letter or a character with the eight bit set. It may contain letters, numbers, an <code>_</code> (underscore or low line) or a character with the eight bit set. The convention is to use underscores to separate words in a multiword method name:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_method_name'>method_name</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>use underscores to separate words</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span></code></pre>
<p>Ruby programs must be written in a US-ASCII-compatible character set such as UTF-8, ISO-8859-1 etc. In such character sets if the eight bit is set it indicates an extended character. Ruby allows method names and other identifiers to contain such characters. Ruby programs cannot contain some characters like ASCII NUL (<code>\x00</code>).</p>
<p>The following are examples of valid Ruby methods:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_hello'>hello</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>hello</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_こんにちは'>こんにちは</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>means hello in Japanese</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span></code></pre>
<p>Typically method names are US-ASCII compatible since the keys to type them exist on all keyboards.</p>
<p>Method names may end with a <code>!</code> (bang or exclamation mark), a <code>?</code> (question mark), or <code>=</code> (equals sign).</p>
<p>The bang methods (<code>!</code> at the end of the method name) are called and executed just like any other method. However, by convention, a method with an exclamation point or bang is considered dangerous. In Ruby’s core library the dangerous method implies that when a method ends with a bang (<code>!</code>), it indicates that unlike its non-bang equivalent, permanently modifies its receiver. Almost always, the Ruby core library will have a non-bang counterpart (method name which does NOT end with <code>!</code>) of every bang method (method name which does end with <code>!</code>) that does not modify the receiver. This convention is typically true for the Ruby core library but may or may not hold true for other Ruby libraries.</p>
<p>Methods that end with a question mark by convention return boolean, but they may not always return just <code>true</code> or <code>false</code>. Often, they will return an object to indicate a true value (or “truthy” value).</p>
<p>Methods that end with an equals sign indicate an assignment method. For assignment methods, the return value is ignored and the arguments are returned instead.</p>
<p>These are method names for the various Ruby operators. Each of these operators accepts only one argument. Following the operator is the typical use or name of the operator. Creating an alternate meaning for the operator may lead to confusion as the user expects plus to add things, minus to subtract things, etc. Additionally, you cannot alter the precedence of the operators.</p>
<dl class="rdoc-list note-list"><dt><code>+</code>
<dd>
<p>add</p>
</dd><dt><code>-</code>
<dd>
<p>subtract</p>
</dd><dt><code>*</code>
<dd>
<p>multiply</p>
</dd><dt><code>**</code>
<dd>
<p>power</p>
</dd><dt><code>/</code>
<dd>
<p>divide</p>
</dd><dt><code>%</code>
<dd>
<p>modulus division, String#%</p>
</dd><dt><code>&</code>
<dd>
<p>AND</p>
</dd><dt><code>^</code>
<dd>
<p>XOR (exclusive OR)</p>
</dd><dt><code>>></code>
<dd>
<p>right-shift</p>
</dd><dt><code><<</code>
<dd>
<p>left-shift, append</p>
</dd><dt><code>==</code>
<dd>
<p>equal</p>
</dd><dt><code>!=</code>
<dd>
<p>not equal</p>
</dd><dt><code>===</code>
<dd>
<p>case equality. See Object#===</p>
</dd><dt><code>=~</code>
<dd>
<p>pattern match. (Not just for regular expressions)</p>
</dd><dt><code>!~</code>
<dd>
<p>does not match</p>
</dd><dt><code><=></code>
<dd>
<p>comparison aka spaceship operator. See Comparable</p>
</dd><dt><code><</code>
<dd>
<p>less-than</p>
</dd><dt><code><=</code>
<dd>
<p>less-than or equal</p>
</dd><dt><code>></code>
<dd>
<p>greater-than</p>
</dd><dt><code>>=</code>
<dd>
<p>greater-than or equal</p>
</dd></dl>
<p>To define unary methods minus, plus, tilde and not (<code>!</code>) follow the operator with an <code>@</code> as in <code>+@</code> or <code>!@</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>def</span> <span class='op'>-@</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>you inverted this object</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_obj'>obj</span> <span class='op'>=</span> <span class='const'>C</span>.<span class='id identifier rubyid_new'>new</span>
<span class='op'>-</span><span class='id identifier rubyid_obj'>obj</span> <span class='comment'># prints "you inverted this object"</span></code></pre>
<p>Unary methods accept zero arguments.</p>
<p>Additionally, methods for element reference and assignment may be defined: <code>[]</code> and <code>[]=</code> respectively. Both can take one or more arguments, and element reference can take none.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>def</span> <span class='op'>[]</span>(<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span>)
<span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_a'>a</span> <span class='op'>+</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='op'>[]=</span>(<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span><span class='comma'>,</span> <span class='id identifier rubyid_c'>c</span>)
<span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_a'>a</span> <span class='op'>*</span> <span class='id identifier rubyid_b'>b</span> <span class='op'>+</span> <span class='id identifier rubyid_c'>c</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_obj'>obj</span> <span class='op'>=</span> <span class='const'>C</span>.<span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_obj'>obj</span>[<span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>] <span class='comment'># prints "5"
</span><span class='id identifier rubyid_obj'>obj</span>[<span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>] <span class='op'>=</span> <span class='int'>4</span> <span class='comment'># prints "10"</span></code></pre>
<h2 id="label-Return+Values">Return Values</h2>
<p>By default, a method returns the last expression that was evaluated in the body of the method. In the example above, the last (and only) expression evaluated was the simple sum <code>1 + 1</code>. The <code>return</code> keyword can be used to make it explicit that a method returns a value.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_one_plus_one'>one_plus_one</span>
<span class='kw'>return</span> <span class='int'>1</span> <span class='op'>+</span> <span class='int'>1</span>
<span class='kw'>end</span></code></pre>
<p>It can also be used to make a method return before the last expression is evaluated.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_two_plus_two'>two_plus_two</span>
<span class='kw'>return</span> <span class='int'>2</span> <span class='op'>+</span> <span class='int'>2</span>
<span class='int'>1</span> <span class='op'>+</span> <span class='int'>1</span> <span class='comment'># this expression is never evaluated
</span><span class='kw'>end</span></code></pre>
<p>Note that for assignment methods the return value will be ignored when using the assignment syntax. Instead, the argument will be returned:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_a='>a=</span>(<span class='id identifier rubyid_value'>value</span>)
<span class='kw'>return</span> <span class='int'>1</span> <span class='op'>+</span> <span class='id identifier rubyid_value'>value</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_p'>p</span>(<span class='kw'>self</span>.<span class='id identifier rubyid_a'>a</span> <span class='op'>=</span> <span class='int'>5</span>) <span class='comment'># prints 5</span></code></pre>
<p>The actual return value will be returned when invoking the method directly:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_send'>send</span>(<span class='symbeg'>:</span><span class='id identifier rubyid_a='>a=</span><span class='comma'>,</span> <span class='int'>5</span>) <span class='comment'># prints 6</span></code></pre>
<h2 id="label-Scope">Scope</h2>
<p>The standard syntax to define a method:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>
<span class='comment'># ...
</span><span class='kw'>end</span></code></pre>
<p>adds the method to a class. You can define an instance method on a specific class with the <code>class</code> keyword:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>
<span class='comment'># ...
</span> <span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>A method may be defined on another object. You may define a “class method” (a method that is defined on the class, not an instance of the class) like this:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>def</span> <span class='kw'>self</span>.<span class='id identifier rubyid_my_method'>my_method</span>
<span class='comment'># ...
</span> <span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>However, this is simply a special case of a greater syntactical power in Ruby, the ability to add methods to any object. Classes are objects, so adding class methods is simply adding methods to the Class object.</p>
<p>The syntax for adding a method to an object is as follows:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_greeting'>greeting</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Hello</span><span class='tstring_end'>"</span></span>
<span class='kw'>def</span> <span class='id identifier rubyid_greeting'>greeting</span>.<span class='id identifier rubyid_broaden'>broaden</span>
<span class='kw'>self</span> <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>, world!</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='id identifier rubyid_greeting'>greeting</span>.<span class='id identifier rubyid_broaden'>broaden</span> <span class='comment'># returns "Hello, world!"</span></code></pre>
<p><code>self</code> is a keyword referring to the current object under consideration by the compiler, which might make the use of <code>self</code> in defining a class method above a little clearer. Indeed, the example of adding a <code>hello</code> method to the class <code>String</code> can be rewritten thus:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='const'>String</span>.<span class='id identifier rubyid_hello'>hello</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>Hello, world!</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span></code></pre>
<p>A method defined like this is called a “singleton method”. <code>broaden</code> will only exist on the string instance <code>greeting</code>. Other strings will not have <code>broaden</code>.</p>
<h2 id="label-Overriding">Overriding</h2>
<p>When Ruby encounters the <code>def</code> keyword, it doesn’t consider it an error if the method already exists: it simply redefines it. This is called <em>overriding</em>. Rather like extending core classes, this is a potentially dangerous ability, and should be used sparingly because it can cause unexpected results. For example, consider this irb session:</p>
<pre class="code ruby"><code class="ruby">>> "43".to_i
#=> 43
>> class String
>> def to_i
>> 42
>> end
>> end
#=> nil
>> "43".to_i
#=> 42</code></pre>
<p>This will effectively sabotage any code which makes use of the method <code>String#to_i</code> to parse numbers from strings.</p>
<h2 id="label-Arguments">Arguments</h2>
<p>A method may accept arguments. The argument list follows the method name:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_one'>add_one</span>(<span class='id identifier rubyid_value'>value</span>)
<span class='id identifier rubyid_value'>value</span> <span class='op'>+</span> <span class='int'>1</span>
<span class='kw'>end</span></code></pre>
<p>When called, the user of the <code>add_one</code> method must provide an argument. The argument is a local variable in the method body. The method will then add one to this argument and return the value. If given <code>1</code> this method will return <code>2</code>.</p>
<p>The parentheses around the arguments are optional:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_one'>add_one</span> <span class='id identifier rubyid_value'>value</span>
<span class='id identifier rubyid_value'>value</span> <span class='op'>+</span> <span class='int'>1</span>
<span class='kw'>end</span></code></pre>
<p>Multiple arguments are separated by a comma:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_values'>add_values</span>(<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span>)
<span class='id identifier rubyid_a'>a</span> <span class='op'>+</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span></code></pre>
<p>When called, the arguments must be provided in the exact order. In other words, the arguments are positional.</p>
<h3 id="label-Default+Values">Default Values</h3>
<p>Arguments may have default values:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_values'>add_values</span>(<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='int'>1</span>)
<span class='id identifier rubyid_a'>a</span> <span class='op'>+</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span></code></pre>
<p>The default value does not need to appear first, but arguments with defaults must be grouped together. This is ok:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_values'>add_values</span>(<span class='id identifier rubyid_a'>a</span> <span class='op'>=</span> <span class='int'>1</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span> <span class='op'>=</span> <span class='int'>2</span><span class='comma'>,</span> <span class='id identifier rubyid_c'>c</span>)
<span class='id identifier rubyid_a'>a</span> <span class='op'>+</span> <span class='id identifier rubyid_b'>b</span> <span class='op'>+</span> <span class='id identifier rubyid_c'>c</span>
<span class='kw'>end</span></code></pre>
<p>This will raise a SyntaxError:</p>
<pre class="code ruby"><code class="ruby">def add_values(a = 1, b, c = 1)
a + b + c
end</code></pre>
<h3 id="label-Array+Decomposition">Array Decomposition</h3>
<p>You can decompose (unpack or extract values from) an Array using extra parentheses in the arguments:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>((<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span>))
<span class='id identifier rubyid_p'>p</span> <span class='label'>a:</span> <span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='label'>b:</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_my_method'>my_method</span>([<span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span>])</code></pre>
<p>This prints:</p>
<pre class="code ruby"><code class="ruby">{<span class='symbeg'>:</span><span class='id identifier rubyid_a'>a</span><span class='op'>=></span><span class='int'>1</span><span class='comma'>,</span> <span class='symbeg'>:</span><span class='id identifier rubyid_b'>b</span><span class='op'>=></span><span class='int'>2</span>}</code></pre>
<p>If the argument has extra elements in the Array they will be ignored:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>((<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span>))
<span class='id identifier rubyid_p'>p</span> <span class='label'>a:</span> <span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='label'>b:</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_my_method'>my_method</span>([<span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>])</code></pre>
<p>This has the same output as above.</p>
<p>You can use a <code>*</code> to collect the remaining arguments. This splits an Array into a first element and the rest:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>((<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='op'>*</span><span class='id identifier rubyid_b'>b</span>))
<span class='id identifier rubyid_p'>p</span> <span class='label'>a:</span> <span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='label'>b:</span> <span class='id identifier rubyid_b'>b</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_my_method'>my_method</span>([<span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>])</code></pre>
<p>This prints:</p>
<pre class="code ruby"><code class="ruby">{<span class='symbeg'>:</span><span class='id identifier rubyid_a'>a</span><span class='op'>=></span><span class='int'>1</span><span class='comma'>,</span> <span class='symbeg'>:</span><span class='id identifier rubyid_b'>b</span><span class='op'>=></span>[<span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>]}</code></pre>
<p>The argument will be decomposed if it responds to #to_ary. You should only define #to_ary if you can use your object in place of an Array.</p>
<p>Use of the inner parentheses only uses one of the sent arguments. If the argument is not an Array it will be assigned to the first argument in the decomposition and the remaining arguments in the decomposition will be <code>nil</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>(<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> (<span class='id identifier rubyid_b'>b</span><span class='comma'>,</span> <span class='id identifier rubyid_c'>c</span>)<span class='comma'>,</span> <span class='id identifier rubyid_d'>d</span>)
<span class='id identifier rubyid_p'>p</span> <span class='label'>a:</span> <span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='label'>b:</span> <span class='id identifier rubyid_b'>b</span><span class='comma'>,</span> <span class='label'>c:</span> <span class='id identifier rubyid_c'>c</span><span class='comma'>,</span> <span class='label'>d:</span> <span class='id identifier rubyid_d'>d</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_my_method'>my_method</span>(<span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span>)</code></pre>
<p>This prints:</p>
<pre class="code ruby"><code class="ruby">{<span class='symbeg'>:</span><span class='id identifier rubyid_a'>a</span><span class='op'>=></span><span class='int'>1</span><span class='comma'>,</span> <span class='symbeg'>:</span><span class='id identifier rubyid_b'>b</span><span class='op'>=></span><span class='int'>2</span><span class='comma'>,</span> <span class='symbeg'>:</span><span class='id identifier rubyid_c'>c</span><span class='op'>=></span><span class='kw'>nil</span><span class='comma'>,</span> <span class='symbeg'>:</span><span class='id identifier rubyid_d'>d</span><span class='op'>=></span><span class='int'>3</span>}</code></pre>
<p>You can nest decomposition arbitrarily:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>(((<span class='id identifier rubyid_a'>a</span><span class='comma'>,</span> <span class='id identifier rubyid_b'>b</span>)<span class='comma'>,</span> <span class='id identifier rubyid_c'>c</span>))
<span class='comment'># ...
</span><span class='kw'>end</span></code></pre>
<h3 id="label-Array-2FHash+Argument">Array/Hash Argument</h3>
<p>Prefixing an argument with <code>*</code> causes any remaining arguments to be converted to an Array:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_gather_arguments'>gather_arguments</span>(<span class='op'>*</span><span class='id identifier rubyid_arguments'>arguments</span>)
<span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_arguments'>arguments</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_gather_arguments'>gather_arguments</span> <span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span> <span class='comment'># prints [1, 2, 3]</span></code></pre>
<p>The array argument must appear before any keyword arguments.</p>
<p>It is possible to gather arguments at the beginning or in the middle:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_gather_arguments'>gather_arguments</span>(<span class='id identifier rubyid_first_arg'>first_arg</span><span class='comma'>,</span> <span class='op'>*</span><span class='id identifier rubyid_middle_arguments'>middle_arguments</span><span class='comma'>,</span> <span class='id identifier rubyid_last_arg'>last_arg</span>)
<span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_middle_arguments'>middle_arguments</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_gather_arguments'>gather_arguments</span> <span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='int'>3</span><span class='comma'>,</span> <span class='int'>4</span> <span class='comment'># prints [2, 3]</span></code></pre>
<p>The array argument will capture a Hash as the last entry if a hash was sent by the caller after all positional arguments.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_gather_arguments'>gather_arguments</span>(<span class='op'>*</span><span class='id identifier rubyid_arguments'>arguments</span>)
<span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_arguments'>arguments</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_gather_arguments'>gather_arguments</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>a:</span> <span class='int'>2</span> <span class='comment'># prints [1, {:a=>2}]</span></code></pre>
<p>However, this only occurs if the method does not declare any keyword arguments.</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_gather_arguments_keyword'>gather_arguments_keyword</span>(<span class='op'>*</span><span class='id identifier rubyid_positional'>positional</span><span class='comma'>,</span> <span class='label'>keyword:</span> <span class='kw'>nil</span>)
<span class='id identifier rubyid_p'>p</span> <span class='label'>positional:</span> <span class='id identifier rubyid_positional'>positional</span><span class='comma'>,</span> <span class='label'>keyword:</span> <span class='id identifier rubyid_keyword'>keyword</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_gather_arguments_keyword'>gather_arguments_keyword</span> <span class='int'>1</span><span class='comma'>,</span> <span class='int'>2</span><span class='comma'>,</span> <span class='label'>three:</span> <span class='int'>3</span>
<span class='comment'>#=> raises: unknown keyword: three (ArgumentError)</span></code></pre>
<p>Also, note that a bare <code>*</code> can be used to ignore arguments:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_ignore_arguments'>ignore_arguments</span>(<span class='op'>*</span>)
<span class='kw'>end</span></code></pre>
<h3 id="label-Keyword+Arguments">Keyword Arguments</h3>
<p>Keyword arguments are similar to positional arguments with default values:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_add_values'>add_values</span>(<span class='label'>first:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>second:</span> <span class='int'>2</span>)
<span class='id identifier rubyid_first'>first</span> <span class='op'>+</span> <span class='id identifier rubyid_second'>second</span>
<span class='kw'>end</span></code></pre>
<p>Arbitrary keyword arguments will be accepted with <code>**</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_gather_arguments'>gather_arguments</span>(<span class='label'>first:</span> <span class='kw'>nil</span><span class='comma'>,</span> <span class='op'>**</span><span class='id identifier rubyid_rest'>rest</span>)
<span class='id identifier rubyid_p'>p</span> <span class='id identifier rubyid_first'>first</span><span class='comma'>,</span> <span class='id identifier rubyid_rest'>rest</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_gather_arguments'>gather_arguments</span> <span class='label'>first:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>second:</span> <span class='int'>2</span><span class='comma'>,</span> <span class='label'>third:</span> <span class='int'>3</span>
<span class='comment'># prints 1 then {:second=>2, :third=>3}</span></code></pre>
<p>When calling a method with keyword arguments the arguments may appear in any order. If an unknown keyword argument is sent by the caller an ArgumentError is raised.</p>
<p>When mixing keyword arguments and positional arguments, all positional arguments must appear before any keyword arguments.</p>
<h2 id="label-Block+Argument">Block Argument</h2>
<p>The block argument is indicated by <code>&</code> and must come last:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>(<span class='op'>&</span><span class='id identifier rubyid_my_block'>my_block</span>)
<span class='id identifier rubyid_my_block'>my_block</span>.<span class='id identifier rubyid_call'>call</span>(<span class='kw'>self</span>)
<span class='kw'>end</span></code></pre>
<p>Most frequently the block argument is used to pass a block to another method:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_each_item'>each_item</span>(<span class='op'>&</span><span class='id identifier rubyid_block'>block</span>)
<span class='ivar'>@items</span>.<span class='id identifier rubyid_each'>each</span>(<span class='op'>&</span><span class='id identifier rubyid_block'>block</span>)
<span class='kw'>end</span></code></pre>
<p>If you are only going to call the block and will not otherwise manipulate it or send it to another method using <code>yield</code> without an explicit block parameter is preferred. This method is equivalent to the first method in this section:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>
<span class='kw'>yield</span> <span class='kw'>self</span>
<span class='kw'>end</span></code></pre>
<p>There is also a performance benefit to using yield over a calling a block parameter. When a block argument is assigned to a variable a Proc object is created which holds the block. When using yield this Proc object is not created.</p>
<p>If you only need to use the block sometimes you can use Proc.new to create a proc from the block that was passed to your method. See Proc.new for further details.</p>
<h2 id="label-Exception+Handling">Exception Handling</h2>
<p>Methods have an implied exception handling block so you do not need to use <code>begin</code> or <code>end</code> to handle exceptions. This:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>
<span class='kw'>begin</span>
<span class='comment'># code that may raise an exception
</span> <span class='kw'>rescue</span>
<span class='comment'># handle exception
</span> <span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>May be written as:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_my_method'>my_method</span>
<span class='comment'># code that may raise an exception
</span><span class='kw'>rescue</span>
<span class='comment'># handle exception
</span><span class='kw'>end</span></code></pre>
<p>If you wish to rescue an exception for only part of your method, use <code>begin</code> and <code>end</code>. For more details see the page on <a href="file.exceptions.html" title="exception handling">exception handling</a>.</p>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>