-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmethods.html
14034 lines (11858 loc) · 714 KB
/
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
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
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Package 'methods' reference manual</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<!-- styling for math. katex.min.css expects fonts in same dir so use CDN -->
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css">
<link rel="stylesheet" type="text/css" href="https://r-universe.dev/static/R.css">
<link rel="stylesheet" type="text/css" href="https://r-universe.dev/static/prism.css">
<!-- for (future) customizations -->
<script src="https://r-universe.dev/static/manual.js"></script>
<link rel="stylesheet" type="text/css" href="https://r-universe.dev/static/manual.css?nocache=1">
</head>
<body class="postdoc macintosh">
<h1 class="manual-title">Package 'methods'</h1>
<table class="description-table">
<tr>
<th>Title:</th>
<td class="description-title">Formal Methods and Classes</td>
</tr>
<tr>
<th>Description:</th>
<td class="description-description">Formally defined methods and classes for R objects,
plus other programming tools, as described in the reference.</td>
</tr>
<tr>
<th>Authors:</th>
<td class="description-author"><span>R Core Team</span></td>
</tr>
<tr>
<th>Maintainer:</th>
<td class="description-maintainer">R Core Team <[email protected]></td>
</tr>
<tr>
<th>License:</th>
<td class="description-license">Part of R 4.4.1</td>
</tr>
<tr>
<th>Version:</th>
<td class="description-version">4.4.1</td>
</tr>
<tr>
<th>Built:</th>
<td class="description-date">2024-06-15 17:27:36 UTC</td>
</tr>
<tr>
<th>Source:</th>
<td class="description-source">base</td>
</tr>
</table>
<a href="#help-index" style="color:black;"><h2 id="help-index">Help Index</h2></a>
<ul id="help-index-list">
<li class="help-index-item"><a href="#methods-package">
Formal Methods and Classes
</a></li>
<li class="help-index-item"><a href="#zBasicFunsList">List of Builtin and Special Functions</a></li>
<li class="help-index-item"><a href="#as">Force an Object to Belong to a Class</a></li>
<li class="help-index-item"><a href="#BasicClasses">Classes Corresponding to Basic Data Types </a></li>
<li class="help-index-item"><a href="#callGeneric">Call the Current Generic Function from a Method</a></li>
<li class="help-index-item"><a href="#NextMethod">Call an Inherited Method</a></li>
<li class="help-index-item"><a href="#canCoerce">Can an Object be Coerced to a Certain S4 Class?</a></li>
<li class="help-index-item"><a href="#cbind2">Combine two Objects by Columns or Rows</a></li>
<li class="help-index-item"><a href="#Classes">S4 Class Documentation</a></li>
<li class="help-index-item"><a href="#Classes_Details">Class Definitions</a></li>
<li class="help-index-item"><a href="#classesToAM">
Compute an Adjacency Matrix for Superclasses of Class Definitions
</a></li>
<li class="help-index-item"><a href="#className">
Class names including the corresponding package
</a></li>
<li class="help-index-item"><a href="#classRepresentation-class">Class Objects </a></li>
<li class="help-index-item"><a href="#Documentation">Using and Creating On-line Documentation for Classes and
Methods</a></li>
<li class="help-index-item"><a href="#dotsMethods">The Use of ... in Method Signatures</a></li>
<li class="help-index-item"><a href="#EnvironmentClass">Class "environment"</a></li>
<li class="help-index-item"><a href="#stdRefClass">Class "envRefClass"</a></li>
<li class="help-index-item"><a href="#evalSource">
Use Function Definitions from a Source File without Reinstalling a Package
</a></li>
<li class="help-index-item"><a href="#findClass">Find Class Definitions</a></li>
<li class="help-index-item"><a href="#findMethods">Description of the Methods Defined for a Generic Function</a></li>
<li class="help-index-item"><a href="#fixPrevious">Fix Objects Saved from R Versions Previous to 1.8</a></li>
<li class="help-index-item"><a href="#genericFunction-class">Generic Function Objects </a></li>
<li class="help-index-item"><a href="#GenericFunctions">Tools for Managing Generic Functions</a></li>
<li class="help-index-item"><a href="#getClass">Get Class Definition </a></li>
<li class="help-index-item"><a href="#getMethod">Get or Test for the Definition of a Method</a></li>
<li class="help-index-item"><a href="#getPackageName">The Name associated with a Given Package</a></li>
<li class="help-index-item"><a href="#hasArg">Look for an Argument in the Call</a></li>
<li class="help-index-item"><a href="#implicitGeneric">Manage Implicit Versions of Generic Functions</a></li>
<li class="help-index-item"><a href="#inheritedSlotNames">Names of Slots Inherited From a Super Class</a></li>
<li class="help-index-item"><a href="#initialize-methods">Methods to Initialize New Objects from a Class</a></li>
<li class="help-index-item"><a href="#Introduction">Basic use of S4 Methods and Classes</a></li>
<li class="help-index-item"><a href="#is">Is an Object from a Class?</a></li>
<li class="help-index-item"><a href="#isSealedMethod"> Check for a Sealed Method or Class </a></li>
<li class="help-index-item"><a href="#LanguageClasses">Classes to Represent Unevaluated Language Objects</a></li>
<li class="help-index-item"><a href="#LinearMethodsList-class">Class "LinearMethodsList"</a></li>
<li class="help-index-item"><a href="#localRefClass">Localized Objects based on Reference Classes</a></li>
<li class="help-index-item"><a href="#setSClass">Create a Class Definition</a></li>
<li class="help-index-item"><a href="#method.skeleton">Create a Skeleton File for a New Method</a></li>
<li class="help-index-item"><a href="#MethodDefinition-class">Classes to Represent Method Definitions</a></li>
<li class="help-index-item"><a href="#Methods">S4 Class Documentation</a></li>
<li class="help-index-item"><a href="#Methods_Details">General Information on Methods</a></li>
<li class="help-index-item"><a href="#Methods_for_Nongenerics">Methods for Non-Generic Functions in Other Packages</a></li>
<li class="help-index-item"><a href="#Methods_for_S3">Methods For S3 and S4 Dispatch</a></li>
<li class="help-index-item"><a href="#MethodsList-class">Class "MethodsList", Defunct Representation of Methods </a></li>
<li class="help-index-item"><a href="#MethodWithNext-class">Class "MethodWithNext" </a></li>
<li class="help-index-item"><a href="#new"> Generate an Object from a Class </a></li>
<li class="help-index-item"><a href="#nonStructure-class">A non-structure S4 Class for basic types </a></li>
<li class="help-index-item"><a href="#ObjectsWithPackage-class">A Vector of Object Names, with associated Package Names </a></li>
<li class="help-index-item"><a href="#promptClass">Generate a Shell for Documentation of a Formal Class</a></li>
<li class="help-index-item"><a href="#promptMethods"> Generate a Shell for Documentation of Formal Methods </a></li>
<li class="help-index-item"><a href="#refClass">Objects With Fields Treated by Reference (OOP-style)</a></li>
<li class="help-index-item"><a href="#removeMethod"> Remove a Method </a></li>
<li class="help-index-item"><a href="#representation"> Construct a Representation or a Prototype for a Class Definition</a></li>
<li class="help-index-item"><a href="#S3Part"> S4 Classes that Contain S3 Classes</a></li>
<li class="help-index-item"><a href="#S4groupGeneric">S4 Group Generic Functions</a></li>
<li class="help-index-item"><a href="#SClassExtension-class">Class to Represent Inheritance (Extension) Relations </a></li>
<li class="help-index-item"><a href="#selectSuperClasses">Super Classes (of Specific Kinds) of a Class</a></li>
<li class="help-index-item"><a href="#setAs">Methods for Coercing an Object to a Class</a></li>
<li class="help-index-item"><a href="#setClass">Create a Class Definition</a></li>
<li class="help-index-item"><a href="#setClassUnion">Classes Defined as the Union of Other Classes</a></li>
<li class="help-index-item"><a href="#setGeneric">Create a Generic Version of a Function</a></li>
<li class="help-index-item"><a href="#setGroupGeneric">Create a Group Generic Version of a Function</a></li>
<li class="help-index-item"><a href="#setIs">Specify a Superclass Explicitly</a></li>
<li class="help-index-item"><a href="#setLoadActions">
Set Actions For Package Loading
</a></li>
<li class="help-index-item"><a href="#setMethod"> Create and Save a Method </a></li>
<li class="help-index-item"><a href="#setOldClass">Register Old-Style (S3) Classes and Inheritance</a></li>
<li class="help-index-item"><a href="#show">Show an Object</a></li>
<li class="help-index-item"><a href="#showMethods">Show all the methods for the specified function(s) or class</a></li>
<li class="help-index-item"><a href="#signature-class">Class "signature" For Method Definitions</a></li>
<li class="help-index-item"><a href="#slot">The Slots in an Object from a Formal Class</a></li>
<li class="help-index-item"><a href="#StructureClasses">Classes Corresponding to Basic Structures</a></li>
<li class="help-index-item"><a href="#testInheritedMethods">
Test for and Report about Selection of Inherited Methods
</a></li>
<li class="help-index-item"><a href="#TraceClasses">Classes Used Internally to Control Tracing </a></li>
<li class="help-index-item"><a href="#validObject"> Test the Validity of an Object </a></li>
</ul>
<hr>
<div class="manual-pages-content">
<div class="container manual-page" id="methods-package"><div class="page-main">
<a href="#methods-package" class="help-page-title"><h2>
Formal Methods and Classes
</h2></a>
<h3>Description</h3>
<p>Formally defined methods and classes for R objects, plus
other programming tools, as described in the references.
</p>
<h3>Details</h3>
<p>This package provides the “S4” or “S version 4”
approach to methods and classes in a functional language.
</p>
<p>For basic use of the techniques, start with <a href="#Introduction">Introduction</a> and
follow the links there to the key functions for programming, notably
<code><a href="#setClass">setClass</a></code> and <code><a href="#setMethod">setMethod</a></code>.
</p>
<p>Some specific topics:
</p>
<dl>
<dt>Classes:</dt>
<dd>
<p> Creating one, see <code><a href="#setClass">setClass</a></code>;
examining definitions, see <code><a href="#getClass">getClassDef</a></code> and
<a href="#classRepresentation-class">classRepresentation</a>; inheritance and coercing,
see <code><a href="#is">is</a></code> and <code><a href="#as">as</a></code>
</p>
</dd>
<dt>Generic functions:</dt>
<dd>
<p> Basic programming, see
<code><a href="#setGeneric">setGeneric</a></code>; the class of objects, see
<a href="#genericFunction-class">genericFunction</a>; other functions to examine or
manipulate them, see <a href="#GenericFunctions">GenericFunctions</a>.
</p>
</dd>
<dt>S3:</dt>
<dd>
<p>Using classes, see <code><a href="#setOldClass">setOldClass</a></code>; methods,
see <a href="#Methods_for_S3">Methods_for_S3</a>.
</p>
</dd>
<dt>Reference classes:</dt>
<dd>
<p>See <a href="#refClass">ReferenceClasses</a>.
</p>
</dd>
<dt>Class unions; virtual classes</dt>
<dd>
<p>See <code><a href="#setClassUnion">setClassUnion</a></code>.
</p>
</dd>
</dl>
<p>These pages will have additional links to related topics.
</p>
<p>For a complete
list of functions and classes, use <code>library(help="methods")</code>.
</p>
<h3>Author(s)</h3>
<p>R Core Team
</p>
<p>Maintainer: R Core Team <a href="mailto:[email protected]">[email protected]</a>
</p>
<h3>References</h3>
<p>Chambers, John M. (2016)
<em>Extending R</em>,
Chapman & Hall.
(Chapters 9 and 10.)
</p>
<p>Chambers, John M. (2008)
<em>Software for Data Analysis: Programming with R</em>
Springer. (Chapter 10 has some additional details.)
</p>
<hr>
</div></div>
<div class="container manual-page" id="zBasicFunsList"><div class="page-main">
<a href="#zBasicFunsList" class="help-page-title"><h2>List of Builtin and Special Functions</h2></a>
<h3>Description</h3>
<p>A named list providing instructions for turning builtin and special
functions into generic functions.
</p>
<p>Functions in R that are defined as <code>.Primitive(<name>)</code> are not
suitable for formal methods, because they lack the basic reflectance
property. You can't find the argument list for these functions by
examining the function object itself.
</p>
<p>Future versions of R may fix this by attaching a formal argument list
to the corresponding function. While generally the names of arguments
are not checked by the internal code implementing the function, the
number of arguments frequently is.
</p>
<p>In any case, some definition of a formal argument list is needed if
users are to define methods for these functions. In particular, if
methods are to be merged from multiple packages, the different sets
of methods need to agree on the formal arguments.
</p>
<p>In the absence of reflectance, this list provides the relevant
information via a dummy function associated with each of the known
specials for which methods are allowed.
</p>
<p>At the same, the list flags those specials for which methods are
meaningless (e.g., <code>for</code>) or just a very bad idea (e.g.,
<code>.Primitive</code>).
</p>
<p>A generic function created via <code><a href="#setMethod">setMethod</a></code>, for
example, for one of these special functions will have the argument
list from <code>.BasicFunsList</code>. If no entry exists, the argument
list <code>(x, ...)</code> is assumed.
</p>
<hr>
</div></div>
<div class="container manual-page" id="as"><div class="page-main">
<a href="#as" class="help-page-title"><h2>Force an Object to Belong to a Class</h2></a>
<h3>Description</h3>
<p>Coerce an object to a given class.
</p>
<h3>Usage</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">as(object, Class, strict=TRUE, ext)
as(object, Class) <- value
</code><code class="language-r">as<span class="token punctuation">(</span>object<span class="token punctuation">,</span> Class<span class="token punctuation">,</span> strict<span class="token operator">=</span><span class="token boolean">TRUE</span><span class="token punctuation">,</span> ext<span class="token punctuation">)</span>
as<span class="token punctuation">(</span>object<span class="token punctuation">,</span> Class<span class="token punctuation">)</span> <span class="token operator"><-</span> value</code></pre>
<h3 class="r-arguments-title">Arguments</h3>
<table>
<tr>
<td><code id="object">object</code></td>
<td>
<p>any <span class="rlang"><b>R</b></span> object.</p>
</td>
</tr>
<tr>
<td><code id="Class">Class</code></td>
<td>
<p>the name of the class to which <code>object</code> should be
coerced. </p>
</td>
</tr>
<tr>
<td><code id="strict">strict</code></td>
<td>
<p>logical flag. If <code>TRUE</code>, the returned object
must be strictly from the target class (unless that class is a
virtual class, in which case the object will be from the closest
actual class, in particular the original object, if that class extends the
virtual class directly).
</p>
<p>If <code>strict = FALSE</code>, any simple extension of the target class
will be returned, without further change. A simple extension is,
roughly, one that just adds slots to an existing class.</p>
</td>
</tr>
<tr>
<td><code id="value">value</code></td>
<td>
<p>The value to use to modify <code>object</code> (see the
discussion below). You should supply an object with class
<code>Class</code>; some coercion is done, but you're unwise to rely on
it.</p>
</td>
</tr>
<tr>
<td><code id="ext">ext</code></td>
<td>
<p>an optional object
defining how <code>Class</code> is extended by the class of the
object (as returned by <code><a href="#RClassUtils">possibleExtends</a></code>).
This argument is used internally;
do not use it directly.
</p>
</td>
</tr>
</table>
<h3>Description</h3>
<p><code>as(object)</code>
returns the version of this object coerced to be the given
<code>Class</code>. When used in the replacement form on the left of
an assignment, the portion of the object corresponding to
<code>Class</code> is replaced by <code>value</code>.
</p>
<p>The operation of <code>as()</code> in either form depends on the
definition of coerce methods. Methods are defined automatically
when the two classes are related by inheritance; that is, when
one of the classes is a subclass of the other.
</p>
<p>Coerce methods are also predefined for basic classes (including all
the types of vectors, functions and a few others).
</p>
<p>Beyond these two sources of methods, further methods are defined
by calls to the <code><a href="#setAs">setAs</a></code> function. See that
documentation also for details of how coerce methods work. Use
<code>showMethods(coerce)</code> for a list of all currently defined methods, as in the
example below.
</p>
<h3>Basic Coercion Methods</h3>
<p>Methods are pre-defined for coercing any object to one of the basic
datatypes. For example, <code>as(x, "numeric")</code> uses the existing
<code>as.numeric</code> function. These and all other existing methods
can be listed as shown in the example.
</p>
<h3>References</h3>
<p>Chambers, John M. (2016)
<em>Extending R</em>,
Chapman & Hall.
(Chapters 9 and 10.)
</p>
<h3>See Also</h3>
<p>If you think of using <code>try(as(x, cl))</code>, consider
<code><a href="#canCoerce">canCoerce</a>(x, cl)</code> instead.
</p>
<h3>Examples</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">
## Show all the existing methods for as()
showMethods("coerce")
</code><code class="language-r"><span class="token comment">## Show all the existing methods for as()</span>
showMethods<span class="token punctuation">(</span><span class="token string">"coerce"</span><span class="token punctuation">)</span></code></pre>
<hr>
</div></div>
<div class="container manual-page" id="BasicClasses"><div class="page-main">
<a href="#BasicClasses" class="help-page-title"><h2>Classes Corresponding to Basic Data Types </h2></a>
<h3>Description</h3>
<p>Formal classes exist corresponding to the basic R object types, allowing
these types to be used in method signatures, as slots in class
definitions, and to be extended by new classes.</p>
<h3>Usage</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">### The following are all basic vector classes.
### They can appear as class names in method signatures,
### in calls to as(), is(), and new().
"character"
"complex"
"double"
"expression"
"integer"
"list"
"logical"
"numeric"
"single"
"raw"
### the class
"vector"
### is a virtual class, extended by all the above
### the class
"S4"
### is an object type for S4 objects that do not extend
### any of the basic vector classes. It is a virtual class.
### The following are additional basic classes
"NULL" # NULL objects
"function" # function objects, including primitives
"externalptr" # raw external pointers for use in C code
"ANY" # virtual classes used by the methods package itself
"VIRTUAL"
"missing"
"namedList" # the alternative to "list" that preserves
# the names attribute
</code><code class="language-r"><span class="token comment">### The following are all basic vector classes.</span>
<span class="token comment">### They can appear as class names in method signatures,</span>
<span class="token comment">### in calls to as(), is(), and new().</span>
<span class="token string">"character"</span>
<span class="token string">"complex"</span>
<span class="token string">"double"</span>
<span class="token string">"expression"</span>
<span class="token string">"integer"</span>
<span class="token string">"list"</span>
<span class="token string">"logical"</span>
<span class="token string">"numeric"</span>
<span class="token string">"single"</span>
<span class="token string">"raw"</span>
<span class="token comment">### the class</span>
<span class="token string">"vector"</span>
<span class="token comment">### is a virtual class, extended by all the above</span>
<span class="token comment">### the class</span>
<span class="token string">"S4"</span>
<span class="token comment">### is an object type for S4 objects that do not extend</span>
<span class="token comment">### any of the basic vector classes. It is a virtual class.</span>
<span class="token comment">### The following are additional basic classes</span>
<span class="token string">"NULL"</span> <span class="token comment"># NULL objects</span>
<span class="token string">"function"</span> <span class="token comment"># function objects, including primitives</span>
<span class="token string">"externalptr"</span> <span class="token comment"># raw external pointers for use in C code</span>
<span class="token string">"ANY"</span> <span class="token comment"># virtual classes used by the methods package itself</span>
<span class="token string">"VIRTUAL"</span>
<span class="token string">"missing"</span>
<span class="token string">"namedList"</span> <span class="token comment"># the alternative to "list" that preserves</span>
<span class="token comment"># the names attribute</span></code></pre>
<h3>Objects from the Classes</h3>
<p>If a class is not virtual (see section in <code><a href="#Classes_Details">Classes_Details</a></code>),
objects can be created by calls of the form <code>new(Class, ...)</code>,
where <code>Class</code> is the quoted class name, and the remaining
arguments if any are objects to be interpreted as vectors of this
class. Multiple arguments will be concatenated.
</p>
<p>The class <code>"expression"</code> is slightly odd, in that the ...
arguments will <em>not</em> be evaluated; therefore, don't enclose them
in a call to <code>quote()</code>.
</p>
<p>Note that class <code>"list"</code> is a pure vector. Although lists with
names go back to the earliest versions of S, they are an extension
of the vector concept in that they have an attribute (which can now
be a slot) and which is either <code>NULL</code> or a character vector of
the same length as the vector. If you want to guarantee that list
names are preserved, use class <code>"namedList"</code>, rather than
<code>"list"</code>. Objects from this class must have a names attribute,
corresponding to slot <code>"names"</code>,
of type <code>"character"</code>. Internally, R treats names for
lists specially, which makes it impractical to have the corresponding slot in
class <code>"namedList"</code> be a union of character names and <code>NULL</code>.
</p>
<h3>Classes and Types</h3>
<p>The basic classes include classes for the basic R types. Note that
objects of these types will not usually be S4 objects
(<code><a href="https://r-universe.dev/manuals/base.html#isS4">isS4</a></code> will return <code>FALSE</code>), although objects from
classes that contain the basic class will be S4 objects, still with
the same type. The type as
returned by <code><a href="https://r-universe.dev/manuals/base.html#typeof">typeof</a></code> will sometimes differ from the class,
either just from a choice of terminology (type <code>"symbol"</code> and
class <code>"name"</code>, for example) or because there is not a one-to-one
correspondence between class and type (most of the classes that
inherit from class <code>"language"</code> have type <code>"language"</code>, for example).
</p>
<h3>Extends</h3>
<p>The vector classes extend <code>"vector"</code>, directly.
</p>
<h3>Methods</h3>
<dl>
<dt>coerce</dt>
<dd>
<p>Methods are defined to coerce arbitrary objects to
the vector classes, by calling the corresponding basic function, for
example, <code>as(x, "numeric")</code> calls <code>as.numeric(x)</code>. </p>
</dd>
</dl>
<hr>
</div></div>
<div class="container manual-page" id="callGeneric"><div class="page-main">
<a href="#callGeneric" class="help-page-title"><h2>Call the Current Generic Function from a Method</h2></a>
<h3>Description</h3>
<p>A call to <code>callGeneric</code> can only appear inside a method
definition. It then results in a call to the current generic
function. The value of that call is the value of <code>callGeneric</code>.
While it can be called from any method, it is useful and typically
used in methods for group generic functions.
</p>
<h3>Usage</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">callGeneric(...)
</code><code class="language-r">callGeneric<span class="token punctuation">(</span><span class="token ellipsis">...</span><span class="token punctuation">)</span></code></pre>
<h3 class="r-arguments-title">Arguments</h3>
<table><tr>
<td><code id="...">...</code></td>
<td>
<p>Optionally, the arguments to the function in its next call.
</p>
<p>If no arguments are included in the call to <code>callGeneric</code>, the
effect is to call the function with the current arguments.
See the detailed description for what this really means.
</p>
</td>
</tr></table>
<h3>Details</h3>
<p>The name and package of the current generic function is stored in the
environment of the method definition object. This name is looked up
and the corresponding function called.
</p>
<p>The statement that passing no arguments to <code>callGeneric</code> causes
the generic function to be called with the current arguments is
more precisely as follows. Arguments that were missing in the current
call are still missing (remember that <code>"missing"</code> is a valid
class in a method signature). For a formal argument, say <code>x</code>, that
appears in the original call, there is a corresponding argument in the
generated call equivalent to <code>x = x</code>. In effect, this
means that the generic function sees the same actual arguments, but
arguments are evaluated only once.
</p>
<p>Using <code>callGeneric</code> with no arguments is prone to creating
infinite recursion, unless one of the arguments in the signature has
been modified in the current method so that a different method is selected.
</p>
<h3>Value</h3>
<p>The value returned by the new call.
</p>
<h3>References</h3>
<p>Chambers, John M. (2016)
<em>Extending R</em>,
Chapman & Hall.
(Chapters 9 and 10.)
</p>
<p>Chambers, John M. (2008)
<em>Software for Data Analysis: Programming with R</em>
Springer. (Section 10.4 for some details.)
</p>
<h3>See Also</h3>
<p><code><a href="#S4groupGeneric">GroupGenericFunctions</a></code> for other information
about group generic functions; <a href="#Methods_Details">Methods_Details</a> for the general behavior
of method dispatch
</p>
<h3>Examples</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">## the method for group generic function Ops
## for signature( e1="structure", e2="vector")
function (e1, e2)
{
value <- callGeneric([email protected], e2)
if (length(value) == length(e1)) {
[email protected] <- value
e1
}
else value
}
## For more examples
## Not run:
showMethods("Ops", includeDefs = TRUE)
## End(Not run)
</code><code class="language-r"><span class="token comment">## the method for group generic function Ops</span>
<span class="token comment">## for signature( e1="structure", e2="vector")</span>
<span class="token keyword">function</span> <span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
<span class="token punctuation">{</span>
value <span class="token operator"><-</span> callGeneric<span class="token punctuation">(</span>e1<span class="token operator">@</span>.Data<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
<span class="token keyword">if</span> <span class="token punctuation">(</span>length<span class="token punctuation">(</span>value<span class="token punctuation">)</span> <span class="token operator">==</span> length<span class="token punctuation">(</span>e1<span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
e1<span class="token operator">@</span>.Data <span class="token operator"><-</span> value
e1
<span class="token punctuation">}</span>
<span class="token keyword">else</span> value
<span class="token punctuation">}</span>
<span class="token comment">## For more examples</span>
<span class="token comment">## Not run: </span>
showMethods<span class="token punctuation">(</span><span class="token string">"Ops"</span><span class="token punctuation">,</span> includeDefs <span class="token operator">=</span> <span class="token boolean">TRUE</span><span class="token punctuation">)</span>
<span class="token comment">## End(Not run)</span></code></pre>
<hr>
</div></div>
<div class="container manual-page" id="NextMethod"><div class="page-main">
<a href="#NextMethod" class="help-page-title"><h2>Call an Inherited Method</h2></a>
<h3>Description</h3>
<p>A call to <code>callNextMethod</code> can only appear inside a method
definition. It then results in a call to the first inherited method
after the current method, with the arguments to the current method
passed down to the next method. The value of that method call is the
value of <code>callNextMethod</code>.
</p>
<h3>Usage</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">callNextMethod(...)
</code><code class="language-r">callNextMethod<span class="token punctuation">(</span><span class="token ellipsis">...</span><span class="token punctuation">)</span></code></pre>
<h3 class="r-arguments-title">Arguments</h3>
<table><tr>
<td><code id="...">...</code></td>
<td>
<p>Optionally, the arguments to the function in its next call
(but note that the dispatch is as in the detailed description below;
the arguments have no effect on selecting the next method.)
</p>
<p>If no arguments are included in the call to <code>callNextMethod</code>, the
effect is to call the method with the current arguments.
See the detailed description for what this really means.
</p>
<p>Calling with no arguments is often the natural way to use
<code>callNextMethod</code>; see the examples.
</p>
</td>
</tr></table>
<h3>Details</h3>
<p>The ‘next’ method (i.e., the first inherited method) is defined
to be that method which <em>would</em> have been called if the current
method did not exist. This is more-or-less literally what happens: The
current method (to be precise, the method with signature given by the
<code>defined</code> slot of the method from which <code>callNextMethod</code> is
called) is deleted from a copy of the methods for the current generic,
and <code><a href="#getMethod">selectMethod</a></code> is called to find the next method (the
result is cached in the method object where the call occurred, so the search typically
happens only once per session per combination of argument classes).
</p>
<p>The next method is defined from the <em>signature</em> of the current
method, not from the actual classes of the arguments.
In particular, modifying any of the arguments has no effect on the
selection.
As a result, the selected next method can be called with invalid
arguments if the calling function assigns objects of a different
class before the <code>callNextMethod()</code> call.
Be careful of any assignments to such arguments.
</p>
<p>It is possible for the selection of the next method to be ambiguous,
even though the original set of methods was consistent.
See the section “Ambiguous Selection”.
</p>
<p>The statement that the method is called with the current arguments is
more precisely as follows. Arguments that were missing in the current
call are still missing (remember that <code>"missing"</code> is a valid
class in a method signature). For a formal argument, say <code>x</code>, that
appears in the original call, there is a corresponding argument in the
next method call equivalent to <code>x = x</code>. In effect, this
means that the next method sees the same actual arguments, but
arguments are evaluated only once.
</p>
<h3>Value</h3>
<p>The value returned by the selected method.
</p>
<h3>Ambiguous Selection</h3>
<p>There are two fairly common situations in which the choice of a next
method is ambiguous, even when the original set of methods uniquely
defines all method selection unambiguously.
In these situations, <code>callNextMethod()</code> should be replaced,
either by a call to a specific function or by recalling the generic
with different arguments.
</p>
<p>The most likely situation arises with methods for binary operators,
typically through one of the group generic functions.
See the example for class <code>"rnum"</code> below.
Examples of this sort usually require three methods: two for the case
that the first or the second argument comes from the class, and a
third for the case that both arguments come from the class.
If that last method uses <code>callNextMethod</code>, the other two methods
are equally valid. The ambiguity is exactly the same that required
defining the two-argument method in the first place.
</p>
<p>In fact, the two possibilities are equally valid conceptually as well
as formally.
As in the example below, the logic of the application usually requires
selecting a computation explicitly or else calling the generic
function with modified arguments to select an appropriate method.
</p>
<p>The other likely source of ambiguity arises from a class that inherits
directly from more than one other class (a “mixin” in standard
terminology).
If the generic has methods corresponding to both superclasses, a
method for the current class is again needed to resolve ambiguity.
Using <code>callNextMethod</code> will again reimpose the ambiguity.
Again, some explicit choice has to be made in the calling method
instead.
</p>
<p>These ambiguities are not the result of bad design, but they do
require workarounds.
Other ambiguities usually reflect inconsistencies in the tree of
inheritances, such as a class appearing in more than one place among
the superclasses.
Such cases should be rare, but with the independent definition of
classes in multiple packages, they can't be ruled out.
</p>
<h3>References</h3>
<p>Chambers, John M. (2016)
<em>Extending R</em>,
Chapman & Hall.
(Chapters 9 and 10.)
</p>
<h3>See Also</h3>
<p><code><a href="#callGeneric">callGeneric</a></code> to call the generic function with the
current dispatch rules (typically for a group generic function);
<a href="#Methods_Details">Methods_Details</a> for the general behavior of method dispatch.
</p>
<h3>Examples</h3>
<pre class="language-r"><code class="language-r-input" hidden="hidden">## callNextMethod() used for the Math, Math2 group generic functions
## A class to automatically round numeric results to "d" digits
rnum <- setClass("rnum", slots = c(d = "integer"), contains = "numeric")
## Math functions operate on the rounded numbers, return a plain
## vector. The next method will always be the default, usually a primitive.
setMethod("Math", "rnum",
function(x)
callNextMethod(round(as.numeric(x), x@d)))
setMethod("Math2", "rnum",
function(x, digits)
callNextMethod(round(as.numeric(x), x@d), digits))
## Examples of callNextMethod with two arguments in the signature.
## For arithmetic and one rnum with anything, callNextMethod with no arguments
## round the full accuracy result, and return as plain vector
setMethod("Arith", c(e1 ="rnum"),
function(e1, e2)
as.numeric(round(callNextMethod(), e1@d)))
setMethod("Arith", c(e2 ="rnum"),
function(e1, e2)
as.numeric(round(callNextMethod(), e2@d)))
## A method for BOTH arguments from "rnum" would be ambiguous
## for callNextMethod(): the two methods above are equally valid.
## The method chooses the smaller number of digits,
## and then calls the generic function, postponing the method selection
## until it's not ambiguous.
setMethod("Arith", c(e1 ="rnum", e2 = "rnum"),
function(e1, e2) {
if(e1@d <= e2@d)
callGeneric(e1, as.numeric(e2))
else
callGeneric(as.numeric(e1), e2)
})
## For comparisons, callNextMethod with the rounded arguments
setMethod("Compare", c(e1 = "rnum"),
function(e1, e2)
callNextMethod(round(e1, e1@d), round(e2, e1@d)))
setMethod("Compare", c(e2 = "rnum"),
function(e1, e2)
callNextMethod(round(e1, e2@d), round(e2, e2@d)))
## similarly to the Arith case, the method for two "rnum" objects
## can not unambiguously use callNextMethod(). Instead, we rely on
## The rnum() method inhertited from Math2 to return plain vectors.
setMethod("Compare", c(e1 ="rnum", e2 = "rnum"),
function(e1, e2) {
d <- min(e1@d, e2@d)
callGeneric(round(e1, d), round(e2, d))
})
set.seed(867)
x1 <- rnum(10*runif(5), d=1L)
x2 <- rnum(10*runif(5), d=2L)
x1+1
x2*2
x1-x2
## Simple examples to illustrate callNextMethod with and without arguments
B0 <- setClass("B0", slots = c(s0 = "numeric"))
## and a function to illustrate callNextMethod
f <- function(x, text = "default") {
str(x) # print a summary
paste(text, ":", class(x))
}
setGeneric("f")
setMethod("f", "B0", function(x, text = "B0") {
cat("B0 method called with s0 =", x@s0, "\n")
callNextMethod()
})
b0 <- B0(s0 = 1)
## call f() with 2 arguments: callNextMethod passes both to the default method
f(b0, "first test")
## call f() with 1 argument: the default "B0" is not passed by callNextMethod
f(b0)
## Now, a class that extends B0, with no methods for f()
B1 <- setClass("B1", slots = c(s1 = "character"), contains = "B0")
b1 <- B1(s0 = 2, s1 = "Testing B1")
## the two cases work as before, by inheriting the "B0" method
f(b1, b1@s1)
f(b1)
B2 <- setClass("B2", contains = "B1")
## And, a method for "B2" that calls with explicit arguments.
## Note that the method selection in callNextMethod
## uses the class of the *argument* to consistently select the "B0" method
setMethod("f", "B2", function(x, text = "B1 method") {
y <- B1(s0 = -x@s0, s1 ="Modified x")
callNextMethod(y, text)
})
b2 <- B2(s1 = "Testing B2", s0 = 10)
f(b2, b2@s1)
f(b2)
## Be careful: the argument passed must be legal for the method selected
## Although the argument here is numeric, it's still the "B0" method that's called
setMethod("f", "B2", function(x, text = "B1 method") {
callNextMethod(x@s0, text)
})
## Now the call will cause an error:
tryCatch(f(b2), error = function(e) cat(e$message,"\n"))
</code><code class="language-r"><span class="token comment">## callNextMethod() used for the Math, Math2 group generic functions</span>
<span class="token comment">## A class to automatically round numeric results to "d" digits</span>
rnum <span class="token operator"><-</span> setClass<span class="token punctuation">(</span><span class="token string">"rnum"</span><span class="token punctuation">,</span> slots <span class="token operator">=</span> c<span class="token punctuation">(</span>d <span class="token operator">=</span> <span class="token string">"integer"</span><span class="token punctuation">)</span><span class="token punctuation">,</span> contains <span class="token operator">=</span> <span class="token string">"numeric"</span><span class="token punctuation">)</span>
<span class="token comment">## Math functions operate on the rounded numbers, return a plain</span>
<span class="token comment">## vector. The next method will always be the default, usually a primitive.</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Math"</span><span class="token punctuation">,</span> <span class="token string">"rnum"</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>x<span class="token punctuation">)</span>
callNextMethod<span class="token punctuation">(</span>round<span class="token punctuation">(</span>as.numeric<span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">,</span> x<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Math2"</span><span class="token punctuation">,</span> <span class="token string">"rnum"</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>x<span class="token punctuation">,</span> digits<span class="token punctuation">)</span>
callNextMethod<span class="token punctuation">(</span>round<span class="token punctuation">(</span>as.numeric<span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">,</span> x<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">,</span> digits<span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token comment">## Examples of callNextMethod with two arguments in the signature.</span>
<span class="token comment">## For arithmetic and one rnum with anything, callNextMethod with no arguments</span>
<span class="token comment">## round the full accuracy result, and return as plain vector</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Arith"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e1 <span class="token operator">=</span><span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
as.numeric<span class="token punctuation">(</span>round<span class="token punctuation">(</span>callNextMethod<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> e1<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Arith"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e2 <span class="token operator">=</span><span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
as.numeric<span class="token punctuation">(</span>round<span class="token punctuation">(</span>callNextMethod<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> e2<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token comment">## A method for BOTH arguments from "rnum" would be ambiguous</span>
<span class="token comment">## for callNextMethod(): the two methods above are equally valid.</span>
<span class="token comment">## The method chooses the smaller number of digits,</span>
<span class="token comment">## and then calls the generic function, postponing the method selection</span>
<span class="token comment">## until it's not ambiguous.</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Arith"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e1 <span class="token operator">=</span><span class="token string">"rnum"</span><span class="token punctuation">,</span> e2 <span class="token operator">=</span> <span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">if</span><span class="token punctuation">(</span>e1<span class="token operator">@</span>d <span class="token operator"><=</span> e2<span class="token operator">@</span>d<span class="token punctuation">)</span>
callGeneric<span class="token punctuation">(</span>e1<span class="token punctuation">,</span> as.numeric<span class="token punctuation">(</span>e2<span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token keyword">else</span>
callGeneric<span class="token punctuation">(</span>as.numeric<span class="token punctuation">(</span>e1<span class="token punctuation">)</span><span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span>
<span class="token comment">## For comparisons, callNextMethod with the rounded arguments</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Compare"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e1 <span class="token operator">=</span> <span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
callNextMethod<span class="token punctuation">(</span>round<span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e1<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">,</span> round<span class="token punctuation">(</span>e2<span class="token punctuation">,</span> e1<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Compare"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e2 <span class="token operator">=</span> <span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span>
callNextMethod<span class="token punctuation">(</span>round<span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">,</span> round<span class="token punctuation">(</span>e2<span class="token punctuation">,</span> e2<span class="token operator">@</span>d<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token comment">## similarly to the Arith case, the method for two "rnum" objects</span>
<span class="token comment">## can not unambiguously use callNextMethod(). Instead, we rely on</span>
<span class="token comment">## The rnum() method inhertited from Math2 to return plain vectors.</span>
setMethod<span class="token punctuation">(</span><span class="token string">"Compare"</span><span class="token punctuation">,</span> c<span class="token punctuation">(</span>e1 <span class="token operator">=</span><span class="token string">"rnum"</span><span class="token punctuation">,</span> e2 <span class="token operator">=</span> <span class="token string">"rnum"</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token keyword">function</span><span class="token punctuation">(</span>e1<span class="token punctuation">,</span> e2<span class="token punctuation">)</span> <span class="token punctuation">{</span>
d <span class="token operator"><-</span> min<span class="token punctuation">(</span>e1<span class="token operator">@</span>d<span class="token punctuation">,</span> e2<span class="token operator">@</span>d<span class="token punctuation">)</span>
callGeneric<span class="token punctuation">(</span>round<span class="token punctuation">(</span>e1<span class="token punctuation">,</span> d<span class="token punctuation">)</span><span class="token punctuation">,</span> round<span class="token punctuation">(</span>e2<span class="token punctuation">,</span> d<span class="token punctuation">)</span><span class="token punctuation">)</span>