Generics and methods

Generic with dots; method without dots

The default generic includes … but generally the methods should not. That ensures that misspelled arguments won’t be silently swallowed by the method. This is an important difference from S3. Take a very simple implementation of mean():

mean <- new_generic("mean", "x")
method(mean, class_numeric) <- function(x) sum(x) / length(x)

If we pass an additional argument in, we’ll get an error:

mean(100, na.rm = TRUE)

But we can still add additional arguments if we desired:

method(mean, class_numeric) <- function(x, na.rm = TRUE) {
  if (na.rm) {
    x <- x[!is.na(x)]
  }

  sum(x) / length(x)
}
#> Overwriting method mean(<integer>)
#> Overwriting method mean(<double>)
mean(c(100, NA), na.rm = TRUE)
#> [1] 100

(We’ll come back to the case of requiring that all methods implement a na.rm = TRUE argument shortly.)

Generic and method with dots

There are cases where you do need to take … in a method, which is particularly problematic if you need to re-call the generic recursively. For example, imagine a simple print method like this:

simple_print <- new_generic("simple_print", "x")
method(simple_print, class_double) <- function(x, digits = 3) {}
method(simple_print, class_character) <- function(x, max_length = 100) {}

What if you want to print a list?

method(simple_print, class_list) <- function(x, ...) {
  for (el in x) {
    simple_print(el, ...)
  }
}

It’s fine as long as all the elements of the list are numbers, but as soon as we add a character vector, we get an error:

simple_print(list(1, 2, 3), digits = 3)
simple_print(list(1, 2, "x"), digits = 3)

To solve this situation, methods generally need to ignore arguments that they haven’t been specifically designed to handle, i.e. they need to use …:

method(simple_print, class_double) <- function(x, ..., digits = 3) {}
#> Overwriting method simple_print(<double>)
method(simple_print, class_character) <- function(x, ..., max_length = 100) {}
#> Overwriting method simple_print(<character>)

simple_print(list(1, 2, "x"), digits = 3)

In this case we really do want to silently ignore unknown arguments because they might apply to other methods. There’s unfortunately no easy way to avoid this problem without relying on fairly esoteric technology (as done by rlang::check_dots_used()).

simple_print(list(1, 2, "x"), diggits = 3)

Generic and method without dots

Occasional it’s useful to create a generic without … because such functions have a useful property: if a call succeeds for one type of input, it will succeed for any type of input. To create such a generic, you’ll need to use the third argument to new_generic(): an optional function that powers the generic. This function has one key property: it must call call_method() to actually perform dispatch.

In general, this property is only needed for very low-level functions with precisely defined semantics. A good example of such a function is length():

length <- new_generic("length", "x", function(x) {
  S7_dispatch()
})

Omitting … from the generic signature is a strong restriction as it prevents methods from adding extra arguments. For this reason, it’s should only be used in special situations.

Add required arguments

To add required arguments that aren’t dispatched upon, you just need to add additional arguments that lack default values:

foo <- new_generic("foo", "x", function(x, y, ...) {
  S7_dispatch()
})

Now all methods will need to provide that y argument. If not, you’ll get a warning:

method(foo, class_integer) <- function(x, ...) {
  10
}
#> Warning: foo(<integer>) doesn't have argument `y`

This is a warning, not an error, because the generic might be defined in a different package and is in the process of changing interfaces. You’ll always want to address this warning when you see it.

Add optional arguments

Adding an optional argument is similar, but it should generally come after …. This ensures that the user must supply the full name of the argument when calling the function, which makes it easier to extend your function in the future.

mean <- new_generic("mean", "x", function(x, ..., na.rm = TRUE) {
  S7_dispatch()
})
method(mean, class_integer) <- function(x, na.rm = TRUE) {
  if (na.rm) {
    x <- x[!is.na(x)]
  }
  sum(x) / length(x)
}

Forgetting the argument or using a different default value will again generate a warning.

method(mean, class_double) <- function(x, na.rm = FALSE) {}
#> Warning: In mean(<double>), default value of `na.rm` is not the same as the generic
#> - Generic: TRUE
#> - Method:  FALSE
method(mean, class_logical) <- function(x) {}
#> Warning: mean(<logical>) doesn't have argument `na.rm`

Do some work

If your generic has additional arguments, you might want to do some additional work to verify that they’re of the expected type. For example, our mean() function could verify that na.rm was correctly specified:

mean <- new_generic("mean", "x", function(x, ..., na.rm = TRUE) {
  if (!identical(na.rm, TRUE) && !identical(na.rm = FALSE)) {
    stop("`na.rm` must be either TRUE or FALSE")
  }
  S7_dispatch()
})

The only downside to performing error checking is that you constraint the interface for all methods; if for some reason a method found it useful to allow na.rm to be a number or a string, it would have to provide an alternative argument.

A simple example

Let’s take our speak example from vignette("S7") and extend it to teach our pets how to speak multiple languages:

pet <- new_class("pet")
dog <- new_class("dog", pet)
cat <- new_class("cat", pet)

language <- new_class("language")
english <- new_class("english", language)
french <- new_class("french", language)

speak <- new_generic("speak", c("x", "y"))
method(speak, list(dog, english)) <- function(x, y) "Woof"
method(speak, list(cat, english)) <- function(x, y) "Meow"
method(speak, list(dog, french)) <- function(x, y) "Ouaf Ouaf"
method(speak, list(cat, french)) <- function(x, y) "Miaou"

speak(cat(), english())
#> [1] "Meow"
speak(dog(), french())
#> [1] "Ouaf Ouaf"

# This example was originally inspired by blog.klipse.tech/javascript/2021/10/03/multimethod.html
# which has unfortunately since disappeaed.

Special “classes”

There are two special classes that become particularly useful with multiple dispatch:

• class_any() will match any class
• class_missing() will match a missing argument (i.e. not NA, but an argument that was not supplied)