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
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 78: Method Selection</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap78" onload="jscontent()">
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</a> <a href="chap11.html">11</a> <a href="chap12.html">12</a> <a href="chap13.html">13</a> <a href="chap14.html">14</a> <a href="chap15.html">15</a> <a href="chap16.html">16</a> <a href="chap17.html">17</a> <a href="chap18.html">18</a> <a href="chap19.html">19</a> <a href="chap20.html">20</a> <a href="chap21.html">21</a> <a href="chap22.html">22</a> <a href="chap23.html">23</a> <a href="chap24.html">24</a> <a href="chap25.html">25</a> <a href="chap26.html">26</a> <a href="chap27.html">27</a> <a href="chap28.html">28</a> <a href="chap29.html">29</a> <a href="chap30.html">30</a> <a href="chap31.html">31</a> <a href="chap32.html">32</a> <a href="chap33.html">33</a> <a href="chap34.html">34</a> <a href="chap35.html">35</a> <a href="chap36.html">36</a> <a href="chap37.html">37</a> <a href="chap38.html">38</a> <a href="chap39.html">39</a> <a href="chap40.html">40</a> <a href="chap41.html">41</a> <a href="chap42.html">42</a> <a href="chap43.html">43</a> <a href="chap44.html">44</a> <a href="chap45.html">45</a> <a href="chap46.html">46</a> <a href="chap47.html">47</a> <a href="chap48.html">48</a> <a href="chap49.html">49</a> <a href="chap50.html">50</a> <a href="chap51.html">51</a> <a href="chap52.html">52</a> <a href="chap53.html">53</a> <a href="chap54.html">54</a> <a href="chap55.html">55</a> <a href="chap56.html">56</a> <a href="chap57.html">57</a> <a href="chap58.html">58</a> <a href="chap59.html">59</a> <a href="chap60.html">60</a> <a href="chap61.html">61</a> <a href="chap62.html">62</a> <a href="chap63.html">63</a> <a href="chap64.html">64</a> <a href="chap65.html">65</a> <a href="chap66.html">66</a> <a href="chap67.html">67</a> <a href="chap68.html">68</a> <a href="chap69.html">69</a> <a href="chap70.html">70</a> <a href="chap71.html">71</a> <a href="chap72.html">72</a> <a href="chap73.html">73</a> <a href="chap74.html">74</a> <a href="chap75.html">75</a> <a href="chap76.html">76</a> <a href="chap77.html">77</a> <a href="chap78.html">78</a> <a href="chap79.html">79</a> <a href="chap80.html">80</a> <a href="chap81.html">81</a> <a href="chap82.html">82</a> <a href="chap83.html">83</a> <a href="chap84.html">84</a> <a href="chap85.html">85</a> <a href="chap86.html">86</a> <a href="chap87.html">87</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap77.html">[Previous Chapter]</a> <a href="chap79.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap78_mj.html">[MathJax on]</a></p>
<p><a id="X8058CC8187162644" name="X8058CC8187162644"></a></p>
<div class="ChapSects"><a href="chap78.html#X8058CC8187162644">78 <span class="Heading">Method Selection</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X7AEED9AB824CD4DA">78.1 <span class="Heading">Operations and Methods</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X874C7C6D8650D648">78.1-1 IsOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X813BE52887A3E0FA">78.1-2 TypeOfOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X838E29D485D2BAB9">78.1-3 ShowDeclarationsOfOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X85A9E019795B79D6">78.1-4 NewOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X843F48137B899BC3">78.1-5 DeclareOperation</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X799081B4854DC003">78.1-6 <span class="Heading">Tag Based Operations</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X86EC0F0A78ECBC10">78.2 <span class="Heading">Constructors</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X783FA45E7858A8CF">78.2-1 NewConstructor</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7EB6830886F62CC0">78.2-2 DeclareConstructor</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X795EE8257848B438">78.3 <span class="Heading">Method Installation</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X837EFDAB7BEF290B">78.3-1 InstallMethod</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7D2C12DB841CE539">78.3-2 InstallOtherMethod</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7D54FB8A80C0AC3C">78.3-3 InstallEarlyMethod</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X78CA646678B0539F">78.3-4 InstallMethodWithRandomSource</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X851FC6387CA2B241">78.4 <span class="Heading">Applicable Methods and Method Selection</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X846865A681D4A623">78.5 <span class="Heading">Partial Methods</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7EED949B83046A7F">78.5-1 TryNextMethod</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X7B85DD797A907106">78.6 <span class="Heading">Redispatching</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7D4A46CE7BCFCCF5">78.6-1 RedispatchOnCondition</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X87D38D2584D0A8AF">78.7 <span class="Heading">Immediate Methods</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X87B47AC0849611F8">78.7-1 InstallImmediateMethod</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X80C3A19E7B99BB41">78.7-2 IsNoImmediateMethodsObject</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X7FB5016E83DB4349">78.8 <span class="Heading">Logical Implications</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X860B8B707995CFE3">78.8-1 InstallTrueMethod</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap78.html#X7B26BDF68754DF7A">78.8-2 SuspendMethodReordering</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap78.html#X855FE25783FB0D4E">78.9 <span class="Heading">Operations and Mathematical Terms</span></a>
</span>
</div>
</div>
<h3>78 <span class="Heading">Method Selection</span></h3>
<p>This chapter explains how <strong class="pkg">GAP</strong> decides which function to call for which types of objects. It assumes that you have read the chapters about objects (Chapter <a href="chap12.html#X86710F997832ABA4"><span class="RefLink">12</span></a>) and types (Chapter <a href="chap13.html#X7E8202627B421DB1"><span class="RefLink">13</span></a>).</p>
<p>An <em>operation</em> is a special <strong class="pkg">GAP</strong> function that bundles a set of functions, its <em>methods</em>.</p>
<p>All methods of an operation compute the same result. But each method is installed for specific types of arguments.</p>
<p>If an operation is called with a tuple of arguments, one of the applicable methods is selected and called.</p>
<p>Special cases of methods are partial methods, immediate methods, and logical implications.</p>
<p><a id="X7AEED9AB824CD4DA" name="X7AEED9AB824CD4DA"></a></p>
<h4>78.1 <span class="Heading">Operations and Methods</span></h4>
<p>Operations are functions in the category <code class="func">IsOperation</code> (<a href="chap78.html#X874C7C6D8650D648"><span class="RefLink">78.1-1</span></a>).</p>
<p>So on the one hand, <em>operations</em> are <strong class="pkg">GAP</strong> functions, that is, they can be applied to arguments and return a result or cause a side-effect.</p>
<p>On the other hand, operations are more. Namely, an operation corresponds to a set of <strong class="pkg">GAP</strong> functions, called the <em>methods</em> of the operation.</p>
<p>Each call of an operation causes a suitable method to be selected and then called. The choice of which method to select is made according to the types of the arguments, the underlying mechanism is described in the following sections.</p>
<p>Examples of operations are the binary infix operators <code class="code">=</code>, <code class="code">+</code> etc., and <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) is the operation that is called for each argument of <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>).</p>
<p>Also all attributes and properties are operations. Each attribute has a special method which is called if the attribute value is already stored; this method of course simply returns this value.</p>
<p>The setter of an attribute is called automatically if an attribute value has been computed. Attribute setters are operations, too. They have a default method that ignores the request to store the value. Depending on the type of the object, there may be another method to store the value in a suitable way, and then set the attribute tester for the object to <code class="keyw">true</code>.</p>
<p><a id="X874C7C6D8650D648" name="X874C7C6D8650D648"></a></p>
<h5>78.1-1 IsOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsOperation</code>( <var class="Arg">obj</var> )</td><td class="tdright">( category )</td></tr></table></div>
<p>is the category of operations. Every operation is a function, but not vice versa.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">MinimalPolynomial;</span>
<Operation "MinimalPolynomial">
<span class="GAPprompt">gap></span> <span class="GAPinput">IsOperation(MinimalPolynomial);</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">IsFunction(MinimalPolynomial);</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">Factorial;</span>
function( n ) ... end
<span class="GAPprompt">gap></span> <span class="GAPinput">IsOperation(Factorial);</span>
false
</pre></div>
<p><a id="X813BE52887A3E0FA" name="X813BE52887A3E0FA"></a></p>
<h5>78.1-2 TypeOfOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TypeOfOperation</code>( <var class="Arg">object</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>returns a string from the list <code class="code">[ "Attribute", "Operation", "Property", "Category", "Representation", "Filter", "Setter"]</code> reflecting which type of operation <var class="Arg">op</var> is.</p>
<p>(see <a href="chap13.html#X7CC6903E78F24167"><span class="RefLink">13.3</span></a>, <a href="chap13.html#X8698205F8648EB33"><span class="RefLink">13.4</span></a>, <a href="chap13.html#X7C701DBF7BAE649A"><span class="RefLink">13.5</span></a>, <a href="chap13.html#X79DE5208877AE42A"><span class="RefLink">13.6</span></a>, <a href="chap13.html#X871597447BB998A1"><span class="RefLink">13.7</span></a>, <a href="chap13.html#X7997705185C7E720"><span class="RefLink">13.8</span></a>)</p>
<p><a id="X838E29D485D2BAB9" name="X838E29D485D2BAB9"></a></p>
<h5>78.1-3 ShowDeclarationsOfOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ShowDeclarationsOfOperation</code>( <var class="Arg">oper</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Displays information about all declarations of the operation <var class="Arg">oper</var>, including the location of each declaration and the argument filters.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ShowDeclarationsOfOperation(IsFinite);</span>
Available declarations for operation <Property "IsFinite">:
1: GAPROOT/lib/coll.gd:1451 with 1 argument, and filters [ IsListOrCollection ]
2: GAPROOT/lib/float.gd:212 with 1 argument, and filters [ IsFloat ]
3: GAPROOT/lib/ctbl.gd:1195 with 1 argument, and filters [ IsNearlyCharacterTable ]
</pre></div>
<p><a id="X85A9E019795B79D6" name="X85A9E019795B79D6"></a></p>
<h5>78.1-4 NewOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NewOperation</code>( <var class="Arg">name</var>, <var class="Arg">args-filts</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">NewOperation</code> returns an operation <var class="Arg">opr</var> with name <var class="Arg">name</var>. The list <var class="Arg">args-filts</var> describes requirements about the arguments of <var class="Arg">opr</var>, namely the number of arguments must be equal to the length of <var class="Arg">args-filts</var>, and the <span class="SimpleMath">i</span>-th argument must lie in the filter <var class="Arg">args-filts</var><span class="SimpleMath">[i]</span>.</p>
<p>Each method that is installed for <var class="Arg">opr</var> via <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) must require that the <span class="SimpleMath">i</span>-th argument lies in the filter <var class="Arg">args-filts</var><span class="SimpleMath">[i]</span>.</p>
<p>One can install methods for other argument tuples via <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>), this way it is also possible to install methods for a different number of arguments than the length of <var class="Arg">args-filts</var>.</p>
<p><a id="X843F48137B899BC3" name="X843F48137B899BC3"></a></p>
<h5>78.1-5 DeclareOperation</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DeclareOperation</code>( <var class="Arg">name</var>, <var class="Arg">filters</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>does the same as <code class="func">NewOperation</code> (<a href="chap78.html#X85A9E019795B79D6"><span class="RefLink">78.1-4</span></a>) and then binds the new operation to the global variable <var class="Arg">name</var>. The variable must previously be writable, and is made read-only by this function.</p>
<p><a id="X799081B4854DC003" name="X799081B4854DC003"></a></p>
<h5>78.1-6 <span class="Heading">Tag Based Operations</span></h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NewTagBasedOperation</code>( <var class="Arg">name</var>, <var class="Arg">requirements</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DeclareTagBasedOperation</code>( <var class="Arg">name</var>, <var class="Arg">requirements</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallTagBasedMethod</code>( <var class="Arg">oper</var>[, <var class="Arg">tag</var>], <var class="Arg">meth</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">NewTagBasedOperation</code> returns an operation with name <var class="Arg">name</var> that is declared as <em>tag based</em> w.r.t. the list <var class="Arg">requirements</var> of filters for its arguments. If an operation with name <var class="Arg">name</var> exists already before the call then this operation is returned, otherwise a new operation gets created.</p>
<p><code class="func">DeclareTagBasedOperation</code> does the same and additionally binds the returned operation to the global variable <var class="Arg">name</var> if the operation is new.</p>
<p>Declaring the operation <var class="Arg">oper</var> as tag based w.r.t. <var class="Arg">requirements</var> means that <code class="func">InstallTagBasedMethod</code> can be used to install the method <var class="Arg">meth</var> for <var class="Arg">oper</var>, a function whose arguments satisfy <var class="Arg">requirements</var>, with the following meaning.</p>
<ul>
<li><p>The method <var class="Arg">meth</var> is applicable if the first argument of the call to <var class="Arg">oper</var> is identical (in the sense of <code class="func">IsIdenticalObj</code> (<a href="chap12.html#X7961183378DFB902"><span class="RefLink">12.5-1</span></a>)) with the tag <var class="Arg">tag</var> that has been specified in the <code class="func">InstallTagBasedMethod</code> call.</p>
</li>
<li><p>If none of the tag based methods for <var class="Arg">oper</var> has a <var class="Arg">tag</var> that is identical with the first argument of the call to <var class="Arg">oper</var> and if there is a tag based method for <var class="Arg">oper</var> for which no <var class="Arg">tag</var> was specified then this method is applicable.</p>
</li>
</ul>
<p>Thus at most <em>one</em> tag based method for <var class="Arg">oper</var> is applicable, and if a method without <var class="Arg">tag</var> has been installed then it serves as the default method. This is in contrast to the situation with constructors (see <a href="chap78.html#X86EC0F0A78ECBC10"><span class="RefLink">78.2</span></a>) where the first argument is a filter that is used as a tag, but several methods can be applicable in a call to a constructor and one cannot define a default method for it.</p>
<p>Typical use cases for tag based operations are operations that shall create objects in particular internal representations; the filters that define these representations are then used as the first argument, and one wants that either the unique method that belongs to this filter or a default method is called.</p>
<p>Currently it is possible to declare an operation as tag based only for <em>one</em> list of requirements.</p>
<p>Installing methods with <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) for a tag based operation is possible. However, installing such methods with the same requirements as the ones for the tag based methods will have no effect because the handling of tag based methods gets installed with <code class="func">InstallEarlyMethod</code> (<a href="chap78.html#X7D54FB8A80C0AC3C"><span class="RefLink">78.3-3</span></a>) and thus has higher priority.</p>
<p><a id="X86EC0F0A78ECBC10" name="X86EC0F0A78ECBC10"></a></p>
<h4>78.2 <span class="Heading">Constructors</span></h4>
<p>Constructors are a special type of operation used to make new objects. The key difference compared to regular operations is that method selection works slightly differently for them: The first argument in a call to a constructor must always be a filter <a href="chap13.html#X84EFA4C07D4277BB"><span class="RefLink">13.2</span></a>. The result of a method is expected to lie in that filter. Moreover, while normally method selection matches on the type of each argument, for a constructor the first argument is treated differently: instead of matching its type, the argument itself (which is a filter) must be a subset of the filter specified by the method which is being tested for match. In other words, the argument filter must imply the method filter.</p>
<p>Also, method ranking works differently: instead of the sum of the ranks of the types of all arguments, only the rank of the filter given as first argument is considered; and for it, the normal ranking order is reversed. This ensures that if multiple constructor methods match, the <q>most general</q> method is selected.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">DeclareConstructor("XCons",[IsMagma,IsInt]);</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">InstallMethod(XCons, [IsGroup, IsInt], function(t,x) return CyclicGroup(x); end);</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">InstallMethod(XCons, [IsPermGroup, IsInt], function(t,x) return SymmetricGroup(x); end);</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">InstallMethod(XCons, [IsSemigroup, IsInt], function(t,x) return FullTransformationMonoid(x); end);</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsGroup,3);</span>
<pc group of size 3 with 1 generator>
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsPermGroup,3);</span>
Sym( [ 1 .. 3 ] )
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsSemigroup,4);</span>
<full transformation monoid of degree 4>
<span class="GAPprompt">gap></span> <span class="GAPinput"># if multiple methods match, the most general is selected:</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsMagma,3);</span>
<full transformation monoid of degree 3>
</pre></div>
<p>The example above shows some basic examples (usually a constructor will produce isomorphic objects in different representations, not different objects as in this case).</p>
<p>If no method has been installed which guarantees to produce a suitable objecty, a "No Method Found" error will be returned.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsFullTransformationMonoid,4);</span>
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `XCons' on 2 arguments called from
<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
called from read-eval loop at line 8 of *stdin*
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">XCons(IsNilpotentGroup,4);</span>
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `XCons' on 2 arguments called from
<function "HANDLE_METHOD_NOT_FOUND">( <arguments> )
called from read-eval loop at line 9 of *stdin*
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span>
</pre></div>
<p>Note that in both these cases there are methods that actually produce results of the required types, but they have not been installed with this information, so are not selected.</p>
<p><a id="X783FA45E7858A8CF" name="X783FA45E7858A8CF"></a></p>
<h5>78.2-1 NewConstructor</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ NewConstructor</code>( <var class="Arg">name</var>, <var class="Arg">args-filts</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">NewConstructor</code> returns a constructor <var class="Arg">cons</var> with name <var class="Arg">name</var>. The list <var class="Arg">args-filts</var> describes requirements about the arguments of <var class="Arg">cons</var>. Namely the number of arguments must be equal to the length of <var class="Arg">args-filts</var>, and the <span class="SimpleMath">i</span>-th argument must lie in the filter <var class="Arg">args-filts</var><span class="SimpleMath">[i]</span> for <span class="SimpleMath">i ≠ 1</span>. A constructor expects the first argument to be a <em>filter</em> instead of an object and it must be a subset of the filter <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span>.</p>
<p>Each method that is installed for <var class="Arg">cons</var> via <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) must require that the <span class="SimpleMath">i</span>-th argument lies in the filter <var class="Arg">args-filts</var><span class="SimpleMath">[i]</span> for <span class="SimpleMath">i ≠ 1</span>. Its first argument is a filter and must be a subset of the filter <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span>.</p>
<p>One can install methods for other argument tuples via <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>), this way it is also possible to install methods for a different number of arguments than the length of <var class="Arg">args-filts</var>.</p>
<p>Note that the method selection for constructors works slightly differently than for usual operations. As stated above, applicabilty to the first argument in an argument tuple is tested by determining whether the argument-filter is a <em>subset</em> of <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span>.</p>
<p>The rank of a method installed for a constructor is determined solely by <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span> of the method. Instead of taking the sum of the ranks of filters involved in its <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span>, the sum of <span class="SimpleMath">-1</span> times these values is taken. The result is added to the number <var class="Arg">val</var> used in the call of <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>).</p>
<p>This has the following effects on the method selection for constructors. If <var class="Arg">cons</var> is called with an argument tuple whose first argument is the filter <var class="Arg">filt</var>, any method whose first argument is <em>more</em> specific than <var class="Arg">filt</var> is applicable (if its other <var class="Arg">args-filts</var> also match). Then the method with the <q>most general</q> filter <var class="Arg">args-filts</var><span class="SimpleMath">[1]</span> is chosen, since the rank is computed by taking <span class="SimpleMath">-1</span> times the ranks of the involved filters. Thus, a constructor is chosen which returns an object in <var class="Arg">filt</var> using as few extra filters as possible, which presumably is both more flexible to use and easier to construct.</p>
<p>The following example showcases this behaviour. Note that the argument <var class="Arg">filter</var> is only used for method dispatch.</p>
<div class="example"><pre>
DeclareFilter( "IsMyObj" );
DeclareFilter( "IsMyFilter" );
DeclareFilter( "IsMyOtherFilter" );
BindGlobal( "MyFamily", NewFamily( "MyFamily" ) );
DeclareConstructor( "NewMyObj", [ IsMyObj ] );
InstallMethod( NewMyObj,
[ IsMyObj ],
function( filter )
local type;
Print("General constructor\n");
type := NewType( MyFamily, IsMyObj );
return Objectify( type, [] );
end );
InstallMethod( NewMyObj,
[ IsMyObj and IsMyFilter and IsMyOtherFilter ],
function( filter )
local type;
Print("Special constructor\n");
type := NewType( MyFamily, IsMyObj and IsMyFilter and IsMyOtherFilter );
return Objectify( type, [] );
end );
</pre></div>
<p>If only IsMyObj is given, both methods are applicable and the general constructor is called. If also IsMyFilter is given, only the special constructor is applicable.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">a := NewMyObj( IsMyObj );;</span>
General constructor
<span class="GAPprompt">gap></span> <span class="GAPinput">IsMyOtherFilter(a);</span>
false
<span class="GAPprompt">gap></span> <span class="GAPinput">b := NewMyObj( IsMyObj and IsMyFilter );;</span>
Special constructor
<span class="GAPprompt">gap></span> <span class="GAPinput">IsMyOtherFilter(b);</span>
true
<span class="GAPprompt">gap></span> <span class="GAPinput">c := NewMyObj( IsMyObj and IsMyFilter and IsMyOtherFilter );;</span>
Special constructor
<span class="GAPprompt">gap></span> <span class="GAPinput">IsMyOtherFilter(c);</span>
true
</pre></div>
<p><a id="X7EB6830886F62CC0" name="X7EB6830886F62CC0"></a></p>
<h5>78.2-2 DeclareConstructor</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DeclareConstructor</code>( <var class="Arg">name</var>, <var class="Arg">filters</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>does the same as <code class="func">NewConstructor</code> (<a href="chap78.html#X783FA45E7858A8CF"><span class="RefLink">78.2-1</span></a>) and then binds the result to the global variable <var class="Arg">name</var>. The variable must previously be writable, and is made read-only by this function.</p>
<p>Note that for operations which are constructors special rules with respect to applicability and rank of the corresponding methods apply (see section <code class="func">NewConstructor</code> (<a href="chap78.html#X783FA45E7858A8CF"><span class="RefLink">78.2-1</span></a>)).</p>
<p><a id="X795EE8257848B438" name="X795EE8257848B438"></a></p>
<h4>78.3 <span class="Heading">Method Installation</span></h4>
<p>In order to describe what it means to select a method of an operation, we must describe how the methods are connected to their operations.</p>
<p>For attributes and properties there is <code class="func">InstallImmediateMethod</code> (<a href="chap78.html#X87B47AC0849611F8"><span class="RefLink">78.7-1</span></a>).</p>
<p>For declaring that a filter is implied by other filters there is <code class="func">InstallTrueMethod</code> (<a href="chap78.html#X860B8B707995CFE3"><span class="RefLink">78.8-1</span></a>).</p>
<p><a id="X837EFDAB7BEF290B" name="X837EFDAB7BEF290B"></a></p>
<h5>78.3-1 InstallMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallMethod</code>( <var class="Arg">opr</var>[, <var class="Arg">info</var>][, <var class="Arg">famp</var>], <var class="Arg">args-filts</var>[, <var class="Arg">val</var>], <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>installs a function method <var class="Arg">method</var> for the operation <var class="Arg">opr</var>; <var class="Arg">args-filts</var> should be a list of requirements for the arguments, each entry being a filter; if supplied <var class="Arg">info</var> should be a short but informative string that describes for what situation the method is installed, <var class="Arg">famp</var> should be a function to be applied to the families of the arguments. <var class="Arg">val</var> should be an integer that measures the priority of the method, or a function of no arguments which should return such an integer and will be called each time method order is being recalculated (see <code class="func">InstallTrueMethod</code> (<a href="chap78.html#X860B8B707995CFE3"><span class="RefLink">78.8-1</span></a>)).</p>
<p>The default values for <var class="Arg">info</var>, <var class="Arg">famp</var>, and <var class="Arg">val</var> are the empty string, the function <code class="func">ReturnTrue</code> (<a href="chap5.html#X7DB422A2876CCC4D"><span class="RefLink">5.4-1</span></a>), and the integer zero, respectively.</p>
<p>The exact meaning of the arguments <var class="Arg">famp</var>, <var class="Arg">args-filts</var>, and <var class="Arg">val</var> is explained in Section <a href="chap78.html#X851FC6387CA2B241"><span class="RefLink">78.4</span></a>.</p>
<p><var class="Arg">opr</var> expects its methods to require certain filters for their arguments. For example, the argument of a method for the operation <code class="func">Zero</code> (<a href="chap31.html#X8040AC7A79FFC442"><span class="RefLink">31.10-3</span></a>) must be in the category <code class="func">IsAdditiveElementWithZero</code> (<a href="chap31.html#X87F3552A789C572D"><span class="RefLink">31.14-5</span></a>). It is not possible to use <code class="func">InstallMethod</code> to install a method for which the entries of <var class="Arg">args-filts</var> do not imply the respective requirements of the operation <var class="Arg">opr</var>. If one wants to override this restriction, one has to use <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>) instead.</p>
<p><a id="X7D2C12DB841CE539" name="X7D2C12DB841CE539"></a></p>
<h5>78.3-2 InstallOtherMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallOtherMethod</code>( <var class="Arg">opr</var>[, <var class="Arg">info</var>][, <var class="Arg">famp</var>], <var class="Arg">args-filts</var>[, <var class="Arg">val</var>], <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>installs a function method <var class="Arg">method</var> for the operation <var class="Arg">opr</var>, in the same way as for <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>), but without the restriction that the number of arguments must match a declaration of <var class="Arg">opr</var> and without the restriction that <var class="Arg">args-filts</var> imply the respective requirements of the operation <var class="Arg">opr</var>.</p>
<p><a id="X7D54FB8A80C0AC3C" name="X7D54FB8A80C0AC3C"></a></p>
<h5>78.3-3 InstallEarlyMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallEarlyMethod</code>( <var class="Arg">opr</var>, <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>installs a special "early" function method <var class="Arg">method</var> for the operation <var class="Arg">opr</var>. An early method is special in that it bypasses method dispatch, and is always the first method to be called when invoking the operation.</p>
<p>This can be used to avoid method selection overhead for certain special cases, i.e., as an optimization. Overall, we recommend to use this feature very sparingly, as it is tool with sharp edges: for example, any inputs that are handled by an early method can not be intercepted by a regular method, no matter how high its rank is; this can preclude other kinds of optimizations.</p>
<p>Also, unlike regular methods, no checks are performed on the arguments. Not even the required filters for the operation are tested, so early methods must be careful in validating their inputs. This also means that any operation can have at most one such early method for each arity (i.e., one early method taking 1 argument, one early method taking 2 arguments, etc.).</p>
<p>If an early method determines that it is not applicable, it can resume regular method dispatch by invoking <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>).</p>
<p>For an example application of early methods, they are used by <code class="func">First</code> (<a href="chap21.html#X82801DFA84E11272"><span class="RefLink">21.20-21</span></a>) to deal with internal lists, for which computing the exact type (needed for method selection) can be very expensive.</p>
<p><a id="X78CA646678B0539F" name="X78CA646678B0539F"></a></p>
<h5>78.3-4 InstallMethodWithRandomSource</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallMethodWithRandomSource</code>( <var class="Arg">opr</var>, <var class="Arg">info</var>[, <var class="Arg">famp</var>], <var class="Arg">args-filts</var>[, <var class="Arg">val</var>], <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallOtherMethodWithRandomSource</code>( <var class="Arg">opr</var>, <var class="Arg">info</var>[, <var class="Arg">famp</var>], <var class="Arg">args-filts</var>[, <var class="Arg">val</var>], <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>These functions are designed to simplify adding new methods for <code class="func">Random</code> (<a href="chap30.html#X7FF906E57D6936F8"><span class="RefLink">30.7-1</span></a>), <code class="func">PseudoRandom</code> (<a href="chap30.html#X811B5BD47DC5356B"><span class="RefLink">30.7-2</span></a>), and <code class="func">Randomize</code> (<a href="chap26.html#X83DD8B39864A2C94"><span class="RefLink">26.6-4</span></a>) to <strong class="pkg">GAP</strong> which can be called both with, and without, a random source.</p>
<p>They accept the same arguments as <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) and <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>), with the extra requirement that the first member of <var class="Arg">args-filts</var> must be <code class="func">IsRandomSource</code> (<a href="chap14.html#X82E31A697E389F1D"><span class="RefLink">14.7-1</span></a>), and the <var class="Arg">info</var> argument is compulsory and must begin 'for a random source and'.</p>
<p>This function then installs two methods: first it calls <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) (or <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>)) with unchanged arguments. Then it calls <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) (or <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.3-2</span></a>)) a second time to install another method which lacks the initial random source argument; this additional method simply invokes the original method, with <code class="func">GlobalMersenneTwister</code> (<a href="chap14.html#X7AC96008820FAF1F"><span class="RefLink">14.7-4</span></a>) added as first argument.</p>
<p><a id="X851FC6387CA2B241" name="X851FC6387CA2B241"></a></p>
<h4>78.4 <span class="Heading">Applicable Methods and Method Selection</span></h4>
<p>A method installed as above is <em>applicable</em> for an arguments tuple if the following conditions are satisfied.</p>
<p>The number of arguments equals the length of the list <var class="Arg">args-filts</var>, the <span class="SimpleMath">i</span>-th argument lies in the filter <var class="Arg">args-filts</var><span class="SimpleMath">[i]</span>, and <var class="Arg">famp</var> returns <code class="keyw">true</code> when applied to the families of the arguments. The maximal number of arguments supported for methods is six, one gets an error message if one tries to install a method with at least seven arguments.</p>
<p>So <var class="Arg">args-filt</var> describes conditions for each argument, and <var class="Arg">famp</var> describes a relation between the arguments.</p>
<p>For unary operations such as attributes and properties, there is no such relation to postulate, <var class="Arg">famp</var> is <code class="func">ReturnTrue</code> (<a href="chap5.html#X7DB422A2876CCC4D"><span class="RefLink">5.4-1</span></a>) for these operations, a function that always returns <code class="keyw">true</code>. For binary operations, the usual value of <var class="Arg">famp</var> is <code class="func">IsIdenticalObj</code> (<a href="chap12.html#X7961183378DFB902"><span class="RefLink">12.5-1</span></a>), which means that both arguments must lie in the same family.</p>
<p>Note that any properties which occur among the filters in the filter list will <em>not</em> be tested by the method selection if they are not yet known. (More exact: if <var class="Arg">prop</var> is a property then the filter implicitly uses not <var class="Arg">prop</var> but <code class="code">Has<var class="Arg">prop</var> and <var class="Arg">prop</var></code>.) If this is desired you must explicitly enforce a test (see section <a href="chap78.html#X7B85DD797A907106"><span class="RefLink">78.6</span></a>) below.</p>
<p>If no method is applicable, the error message <q>no method found</q> is signaled.</p>
<p>Otherwise, the applicable method with highest <em>rank</em> is selected and then called. This rank is usually given by the sum of the ranks of the filters in the list <var class="Arg">args-filt</var>, <em>including involved filters</em>. This value can be modified by the optional <var class="Arg">val</var> argument used in the call of <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>), as follows.</p>
<ul>
<li><p>If <var class="Arg">val</var> is an integer then add this value to the rank computed from the filters.</p>
</li>
<li><p>If <var class="Arg">val</var> is a function with zero arguments then add the value returned by this function to the rank computed from the filters.</p>
</li>
<li><p>If <var class="Arg">val</var> is a list of the form <code class="code">[ filters ]</code> or <code class="code">[ filters, abs ]</code>, where <code class="code">filters</code> is a list of filters and <code class="code">abs</code>, if given, is an integer, then ignore the filters in <var class="Arg">args-filt</var> for the rank computation, and instead take the sum of the filters in <code class="code">filters</code> (including involved filters) plus <code class="code">abs</code>.</p>
</li>
</ul>
<p>So the argument <var class="Arg">val</var> can be used to raise or lower the priority of a method relative to other methods for <var class="Arg">opr</var>. The variant where <var class="Arg">val</var> is a function can be useful if one wants to shift the rank of the method by the rank of certain filters; note that such ranks need not be constant during a <strong class="pkg">GAP</strong> session, they can grow due to implications, see <code class="func">InstallTrueMethod</code> (<a href="chap78.html#X860B8B707995CFE3"><span class="RefLink">78.8-1</span></a>). The variant where <var class="Arg">val</var> is a list can be useful for example if one wants that certain filters that are involved in <var class="Arg">args-filt</var> are required but shall not count for the rank of the method.</p>
<p>Note that for operations which are constructors special rules with respect to applicability and rank of the corresponding methods apply (see <code class="func">NewConstructor</code> (<a href="chap78.html#X783FA45E7858A8CF"><span class="RefLink">78.2-1</span></a>)).</p>
<p>Note that from the applicable methods an efficient one shall be selected. This is a method that needs only little time and storage for the computations.</p>
<p>It seems to be impossible for <strong class="pkg">GAP</strong> to select an optimal method in all cases. The present ranking of methods is based on the assumption that a method installed for a special situation shall be preferred to a method installed for a more general situation.</p>
<p>For example, a method for computing a Sylow subgroup of a nilpotent group is expected to be more efficient than a method for arbitrary groups. So the more specific method will be selected if <strong class="pkg">GAP</strong> knows that the group given as argument is nilpotent.</p>
<p>Of course there is no obvious way to decide between the efficiency of incommensurable methods. For example, take an operation with one method for permutation groups, another method for nilpotent groups, but no method for nilpotent permutation groups, and call this operation with a permutation group known to be nilpotent.</p>
<p><a id="X846865A681D4A623" name="X846865A681D4A623"></a></p>
<h4>78.5 <span class="Heading">Partial Methods</span></h4>
<p><a id="X7EED949B83046A7F" name="X7EED949B83046A7F"></a></p>
<h5>78.5-1 TryNextMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ TryNextMethod</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>After a method has been selected and called, the method may recognize that it cannot compute the desired result, and give up by calling <code class="code">TryNextMethod()</code>.</p>
<p>In effect, the execution of the method is terminated, and the method selection calls the next method that is applicable w.r.t. the original arguments. In other words, the applicable method is called that is subsequent to the one that called <code class="func">TryNextMethod</code>, according to decreasing rank of the methods.</p>
<p>For example, since every finite group of odd order is solvable, one may install a method for the property <code class="func">IsSolvableGroup</code> (<a href="chap39.html#X809C78D5877D31DF"><span class="RefLink">39.15-6</span></a>) that checks whether the size of the argument is an odd integer, returns <code class="keyw">true</code> if so, and gives up otherwise.</p>
<p>Care is needed if a partial method might modify the type of one of its arguments, for example by computing an attribute or property. If this happens, and the type has really changed, then the method should not exit using <code class="code">TryNextMethod()</code> but should call the operation again, as the new information in the type may cause some methods previously judged inapplicable to be applicable. For example, if the above method for <code class="func">IsSolvableGroup</code> (<a href="chap39.html#X809C78D5877D31DF"><span class="RefLink">39.15-6</span></a>) actually computes the size, (rather than just examining a stored size), then it must take care to check whether the type of the group has changed.</p>
<p><a id="X7B85DD797A907106" name="X7B85DD797A907106"></a></p>
<h4>78.6 <span class="Heading">Redispatching</span></h4>
<p>As mentioned above the method selection will not test unknown properties. In situations, in which algorithms are only known (or implemented) under certain conditions, however such a test might be actually desired.</p>
<p>One way to achieve this would be to install the method under weaker conditions and explicitly test the properties first, exiting via <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>) if some of them are not fulfilled. A problem of this approach however is that such methods then automatically are ranked lower and that the code does not look nice.</p>
<p>A much better way is to use redispatching: Before deciding that no method has been found one tests these properties and if they turn out to be true the method selection is started anew (and will then find a method).</p>
<p>This can be achieved via the following function:</p>
<p><a id="X7D4A46CE7BCFCCF5" name="X7D4A46CE7BCFCCF5"></a></p>
<h5>78.6-1 RedispatchOnCondition</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ RedispatchOnCondition</code>( <var class="Arg">oper</var>[, <var class="Arg">info</var>], <var class="Arg">fampred</var>, <var class="Arg">reqs</var>, <var class="Arg">cond</var>, <var class="Arg">val</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function installs a method for the operation <var class="Arg">oper</var> under the conditions <var class="Arg">fampred</var> and <var class="Arg">reqs</var> which has absolute value <var class="Arg">val</var>; that is, the value of the filters <var class="Arg">reqs</var> is disregarded. <var class="Arg">cond</var> is a list of filters. If not all the values of properties involved in these filters are already known for actual arguments of the method, they are explicitly tested and if they are fulfilled <em>and</em> stored after this test, the operation is dispatched again. Otherwise the method exits with <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>). If supplied, <var class="Arg">info</var> should be a short but informative string that describes these conditions. This can be used to enforce tests like <code class="func">IsFinite</code> (<a href="chap30.html#X808A4061809A6E67"><span class="RefLink">30.4-2</span></a>) in situations when all existing methods require this property. The list <var class="Arg">cond</var> may have unbound entries in which case the corresponding argument is ignored for further tests.</p>
<p><a id="X87D38D2584D0A8AF" name="X87D38D2584D0A8AF"></a></p>
<h4>78.7 <span class="Heading">Immediate Methods</span></h4>
<p>Usually a method is called only if its operation has been called and if this method has been selected, see <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>).</p>
<p>For attributes and properties, one can install also <em>immediate methods</em>.</p>
<p><a id="X87B47AC0849611F8" name="X87B47AC0849611F8"></a></p>
<h5>78.7-1 InstallImmediateMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallImmediateMethod</code>( <var class="Arg">opr</var>[, <var class="Arg">info</var>], <var class="Arg">filter</var>, <var class="Arg">rank</var>, <var class="Arg">method</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">InstallImmediateMethod</code> installs <var class="Arg">method</var> as an immediate method for <var class="Arg">opr</var>, which must be an attribute or a property, with requirement <var class="Arg">filter</var> and rank <var class="Arg">rank</var> (the rank can be omitted, in which case 0 is used as rank). The rank must be an integer value that measures the priority of <var class="Arg">method</var> among the immediate methods for <var class="Arg">opr</var>. If supplied, <var class="Arg">info</var> should be a short but informative string that describes the situation in which the method is called.</p>
<p>An immediate method is called automatically as soon as the object lies in <var class="Arg">filter</var>, provided that the value is not yet known. Afterwards the attribute setter is called in order to store the value, unless the method exits via <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>).</p>
<p>Note the difference to <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.3-1</span></a>) that no family predicate occurs because <var class="Arg">opr</var> expects only one argument, and that <var class="Arg">filter</var> is not a list of requirements but the argument requirement itself.</p>
<p>Immediate methods are thought of as a possibility for objects to gain useful knowledge. They must not be used to force the storing of <q>defining information</q> in an object. In other words, <strong class="pkg">GAP</strong> should work even if all immediate methods are completely disabled. Therefore, the call to <code class="func">InstallImmediateMethod</code> installs <var class="Arg">method</var> also as an ordinary method for <var class="Arg">opr</var> with requirement <var class="Arg">filter</var>.</p>
<p>Note that in such a case <strong class="pkg">GAP</strong> executes a computation for which it was not explicitly asked by the user. So one should install only those methods as immediate methods that are <em>extremely cheap</em>. To emphasize this, immediate methods are also called <em>zero cost methods</em>. The time for their execution should really be approximately zero.</p>
<p>For example, the size of a permutation group can be computed very cheaply if a stabilizer chain of the group is known. So it is reasonable to install an immediate method for <code class="func">Size</code> (<a href="chap30.html#X858ADA3B7A684421"><span class="RefLink">30.4-6</span></a>) with requirement <code class="code">IsGroup and Tester( <var class="Arg">stab</var> )</code>, where <var class="Arg">stab</var> is the attribute corresponding to the stabilizer chain.</p>
<p>Another example would be the implementation of the conclusion that every finite group of prime power order is nilpotent. This could be done by installing an immediate method for the attribute <code class="func">IsNilpotentGroup</code> (<a href="chap39.html#X87D062608719F2CD"><span class="RefLink">39.15-3</span></a>) with requirement <code class="code">IsGroup and Tester( Size )</code>. This method would then check whether the size is a finite prime power, return <code class="keyw">true</code> in this case and otherwise call <code class="func">TryNextMethod</code> (<a href="chap78.html#X7EED949B83046A7F"><span class="RefLink">78.5-1</span></a>). But this requires factoring of an integer, which cannot be guaranteed to be very cheap, so one should not install this method as an immediate method.</p>
<p><a id="X80C3A19E7B99BB41" name="X80C3A19E7B99BB41"></a></p>
<h5>78.7-2 IsNoImmediateMethodsObject</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ IsNoImmediateMethodsObject</code>( <var class="Arg">obj</var> )</td><td class="tdright">( filter )</td></tr></table></div>
<p>If this filter is set immediate methods will be ignored for <var class="Arg">obj</var>. This can be crucial for performance for objects like pcgs (see Section <a href="chap45.html#X7F18A01785DBAC4E"><span class="RefLink">45.1</span></a>), of which many are created, which are collections, but for which all those immediate methods for <code class="func">IsTrivial</code> (<a href="chap30.html#X7E3402D6799D3C24"><span class="RefLink">30.4-3</span></a>) et cetera do not really make sense. Other examples of objects in <code class="func">IsNoImmediateMethodsObject</code> are compressed vectors and matrices over small finite fields, see the sections <a href="chap23.html#X8679F7DD7DFCBD9C"><span class="RefLink">23.3</span></a> and <a href="chap24.html#X873822B6830CE367"><span class="RefLink">24.14</span></a>.</p>
<p><a id="X7FB5016E83DB4349" name="X7FB5016E83DB4349"></a></p>
<h4>78.8 <span class="Heading">Logical Implications</span></h4>
<p><a id="X860B8B707995CFE3" name="X860B8B707995CFE3"></a></p>
<h5>78.8-1 InstallTrueMethod</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ InstallTrueMethod</code>( <var class="Arg">newfil</var>, <var class="Arg">filt</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>It may happen that a filter <var class="Arg">newfil</var> shall be implied by another filter <var class="Arg">filt</var>, which is usually a meet of other properties, or the meet of some properties and some categories. Such a logical implication can be installed as an <q>immediate method</q> for <var class="Arg">newfil</var> that requires <var class="Arg">filt</var> and that always returns <code class="keyw">true</code>. (This should not be mixed up with the methods installed via <code class="func">InstallImmediateMethod</code> (<a href="chap78.html#X87B47AC0849611F8"><span class="RefLink">78.7-1</span></a>), which have to be called at runtime for the actual objects.)</p>
<p><code class="func">InstallTrueMethod</code> has the effect that <var class="Arg">newfil</var> becomes an implied filter of <var class="Arg">filt</var>, see <a href="chap13.html#X84EFA4C07D4277BB"><span class="RefLink">13.2</span></a>.</p>
<p>For example, each cyclic group is abelian, each finite vector space is finite dimensional, and each division ring is integral. The first of these implications is installed as follows.</p>
<div class="example"><pre>
InstallTrueMethod( IsCommutative, IsGroup and IsCyclic );
</pre></div>
<p>Contrary to the immediate methods installed with <code class="func">InstallImmediateMethod</code> (<a href="chap78.html#X87B47AC0849611F8"><span class="RefLink">78.7-1</span></a>), logical implications cannot be switched off. This means that after the above implication has been installed, one can rely on the fact that every object in the filter <code class="code">IsGroup and IsCyclic</code> whose type gets created after the installation of the implication will also be in the filter <code class="func">IsCommutative</code> (<a href="chap35.html#X830A4A4C795FBC2D"><span class="RefLink">35.4-9</span></a>). In particular, it may happen that an object which existed already before the installation of the implication lies in <code class="code">IsGroup and IsCyclic</code> but not in <code class="func">IsCommutative</code> (<a href="chap35.html#X830A4A4C795FBC2D"><span class="RefLink">35.4-9</span></a>). Thus it is advisable to install all implications between filters before one starts creating (types of) objects lying in these filters.</p>
<p>Adding logical implications can change the rank of filters (see <code class="func">RankFilter</code> (<a href="chap13.html#X82E62B997C05E05E"><span class="RefLink">13.2-1</span></a>)) and consequently the rank, and so choice of methods for operations (see <a href="chap78.html#X851FC6387CA2B241"><span class="RefLink">78.4</span></a>). By default <code class="func">InstallTrueMethod</code> adjusts the method selection data structures to take care of this, but this process can be time-consuming, so functions <code class="func">SuspendMethodReordering</code> (<a href="chap78.html#X7B26BDF68754DF7A"><span class="RefLink">78.8-2</span></a>) and <code class="func">ResumeMethodReordering</code> (<a href="chap78.html#X7B26BDF68754DF7A"><span class="RefLink">78.8-2</span></a>) are provided to allow control of this process.</p>
<p><a id="X7B26BDF68754DF7A" name="X7B26BDF68754DF7A"></a></p>
<h5>78.8-2 SuspendMethodReordering</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ SuspendMethodReordering</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ResumeMethodReordering</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ResetMethodReordering</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>These functions control whether the method reordering process described in <code class="func">InstallTrueMethod</code> (<a href="chap78.html#X860B8B707995CFE3"><span class="RefLink">78.8-1</span></a>) is invoked or not. Since this process can be comparatively time-consuming, it is usually suspended when a lot of implications are due to be installed, for instance when loading the library, or a package. This is done by calling <code class="func">SuspendMethodReordering</code> once the installations are done, <code class="func">ResumeMethodReordering</code> should be called. These pairs of calls can be nested. When the outermost pair is complete, method reordering takes place and is enabled in <code class="func">InstallTrueMethod</code> (<a href="chap78.html#X860B8B707995CFE3"><span class="RefLink">78.8-1</span></a>) thereafter. <code class="func">ResetMethodReordering</code> effectively exits all nested suspensions, resuming reordering immediately. This function is mainly provided for error recovery and similar purposes and is called on quitting from a break loop.</p>
<p><a id="X855FE25783FB0D4E" name="X855FE25783FB0D4E"></a></p>
<h4>78.9 <span class="Heading">Operations and Mathematical Terms</span></h4>
<p>Usually an operation stands for a mathematical concept, and the name of the operation describes this uniquely. Examples are the property <code class="func">IsFinite</code> (<a href="chap30.html#X808A4061809A6E67"><span class="RefLink">30.4-2</span></a>) and the attribute <code class="func">Size</code> (<a href="chap30.html#X858ADA3B7A684421"><span class="RefLink">30.4-6</span></a>). But there are cases where the same mathematical term is used to denote different concepts, for example <code class="code">Degree</code> is defined for polynomials, group characters, and permutation actions, and <code class="code">Rank</code> is defined for matrices, free modules, <span class="SimpleMath">p</span>-groups, and transitive permutation actions.</p>
<p>It is in principle possible to install methods for the operation <code class="code">Rank</code> that are applicable to the different types of arguments, corresponding to the different contexts. But this is not the approach taken in the <strong class="pkg">GAP</strong> library. Instead there are operations such as <code class="func">RankMat</code> (<a href="chap24.html#X7A995A74838950E6"><span class="RefLink">24.7-1</span></a>) for matrices and <code class="func">DegreeOfCharacter</code> (<a href="chap72.html#X7802BC157C69DD75"><span class="RefLink">72.8-4</span></a>) (in fact these are attributes) which are installed as methods of the <q>ambiguous</q> operations <code class="code">Rank</code> and <code class="code">Degree</code>.</p>
<p>The idea is to distinguish between on the one hand different ways to compute the same thing (e.g. different methods for <code class="func">\=</code> (<a href="chap31.html#X7EF67D047F03CA6F"><span class="RefLink">31.11-1</span></a>), <code class="func">Size</code> (<a href="chap30.html#X858ADA3B7A684421"><span class="RefLink">30.4-6</span></a>), etc.), and on the other hand genuinely different things (such as the degree of a polynomial and a permutation action).</p>
<p>The former is the basic purpose of operations and attributes. The latter is provided as a user convenience where mathematical usage forces it on us <em>and</em> where no conflicts arise. In programming the library, we use the underlying mathematically precise operations or attributes, such as <code class="func">RankMat</code> (<a href="chap24.html#X7A995A74838950E6"><span class="RefLink">24.7-1</span></a>) and <code class="func">RankAction</code> (<a href="chap41.html#X8166A6A17C8D6E73"><span class="RefLink">41.10-3</span></a>). These should be attributes if appropriate, and the only role of the operation <code class="code">Rank</code> is to decide which attribute the user meant. That way, stored information is stored with <q>full mathematical precision</q> and is less likely to be retrieved for a wrong purpose later.</p>
<p>One word about possible conflicts. A typical example is the mathematical term <q>centre</q>, which is defined as <span class="SimpleMath">{ x ∈ M | a * x = x * a ∀ a ∈ M }</span> for a magma <span class="SimpleMath">M</span>, and as <span class="SimpleMath">{ x ∈ L | l * x = 0 ∀ l ∈ L }</span> for a Lie algebra <span class="SimpleMath">L</span>. Here it is <em>not</em> possible to introduce an operation <code class="func">Centre</code> (<a href="chap35.html#X847ABE6F781C7FE8"><span class="RefLink">35.4-5</span></a>) that delegates to attributes <code class="code">CentreOfMagma</code> and <code class="code">CentreOfLieAlgebra</code>, depending on the type of the argument. This is because any Lie algebra in <strong class="pkg">GAP</strong> is also a magma, so both <code class="code">CentreOfMagma</code> and <code class="code">CentreOfLieAlgebra</code> would be defined for a Lie algebra, with different meaning if the characteristic is two. So we cannot achieve that one operation in <strong class="pkg">GAP</strong> corresponds to the mathematical term <q>centre</q>.</p>
<p><q>Ambiguous</q> operations such as <code class="code">Rank</code> are declared in the library file <code class="file">lib/overload.g</code>.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap77.html">[Previous Chapter]</a> <a href="chap79.html">[Next Chapter]</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</a> <a href="chap11.html">11</a> <a href="chap12.html">12</a> <a href="chap13.html">13</a> <a href="chap14.html">14</a> <a href="chap15.html">15</a> <a href="chap16.html">16</a> <a href="chap17.html">17</a> <a href="chap18.html">18</a> <a href="chap19.html">19</a> <a href="chap20.html">20</a> <a href="chap21.html">21</a> <a href="chap22.html">22</a> <a href="chap23.html">23</a> <a href="chap24.html">24</a> <a href="chap25.html">25</a> <a href="chap26.html">26</a> <a href="chap27.html">27</a> <a href="chap28.html">28</a> <a href="chap29.html">29</a> <a href="chap30.html">30</a> <a href="chap31.html">31</a> <a href="chap32.html">32</a> <a href="chap33.html">33</a> <a href="chap34.html">34</a> <a href="chap35.html">35</a> <a href="chap36.html">36</a> <a href="chap37.html">37</a> <a href="chap38.html">38</a> <a href="chap39.html">39</a> <a href="chap40.html">40</a> <a href="chap41.html">41</a> <a href="chap42.html">42</a> <a href="chap43.html">43</a> <a href="chap44.html">44</a> <a href="chap45.html">45</a> <a href="chap46.html">46</a> <a href="chap47.html">47</a> <a href="chap48.html">48</a> <a href="chap49.html">49</a> <a href="chap50.html">50</a> <a href="chap51.html">51</a> <a href="chap52.html">52</a> <a href="chap53.html">53</a> <a href="chap54.html">54</a> <a href="chap55.html">55</a> <a href="chap56.html">56</a> <a href="chap57.html">57</a> <a href="chap58.html">58</a> <a href="chap59.html">59</a> <a href="chap60.html">60</a> <a href="chap61.html">61</a> <a href="chap62.html">62</a> <a href="chap63.html">63</a> <a href="chap64.html">64</a> <a href="chap65.html">65</a> <a href="chap66.html">66</a> <a href="chap67.html">67</a> <a href="chap68.html">68</a> <a href="chap69.html">69</a> <a href="chap70.html">70</a> <a href="chap71.html">71</a> <a href="chap72.html">72</a> <a href="chap73.html">73</a> <a href="chap74.html">74</a> <a href="chap75.html">75</a> <a href="chap76.html">76</a> <a href="chap77.html">77</a> <a href="chap78.html">78</a> <a href="chap79.html">79</a> <a href="chap80.html">80</a> <a href="chap81.html">81</a> <a href="chap82.html">82</a> <a href="chap83.html">83</a> <a href="chap84.html">84</a> <a href="chap85.html">85</a> <a href="chap86.html">86</a> <a href="chap87.html">87</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
