new_generic: Define a new generic

Description

A generic function uses different implementations (methods) depending on the class of one or more arguments (the signature). Create a new generic with new_generic() then use method<- to add methods to it.

Method dispatch is performed by S7_dispatch(), which must always be included in the body of the generic, but in most cases new_generic() will generate this for you.

Learn more in vignette("generics-methods")

Usage

new_generic(name, dispatch_args, fun = NULL)
S7_dispatch()

Value

An S7 generic, i.e. a function with class S7_generic.

Arguments

name

The name of the generic. This should be the same as the object that you assign it to.

dispatch_args

A character vector giving the names of one or more arguments used to find the method.

fun

An optional specification of the generic, which must call S7_dispatch() to dispatch to methods. This is usually generated automatically from the dispatch_args, but you may want to supply it if you want to add additional required arguments, omit ..., or perform some standardised computation in the generic.

The dispatch_args must be the first arguments to fun, and, if present, ... must immediately follow them.

Dispatch arguments

The arguments that are used to pick the method are called the dispatch arguments. In most cases, this will be one argument, in which case the generic is said to use single dispatch. If it consists of more than one argument, it's said to use multiple dispatch.

There are two restrictions on the dispatch arguments: they must be the first arguments to the generic and if the generic uses ..., it must occur immediately after the dispatch arguments.

Examples

Run this code

# A simple generic with methods for some base types and S3 classes
type_of <- new_generic("type_of", dispatch_args = "x")
method(type_of, class_character) <- function(x, ...) "A character vector"
method(type_of, new_S3_class("data.frame")) <- function(x, ...) "A data frame"
method(type_of, class_function) <- function(x, ...) "A function"

type_of(mtcars)
type_of(letters)
type_of(mean)

# If you want to require that methods implement additional arguments,
# you can use a custom function:
mean2 <- new_generic("mean2", "x", function(x, ..., na.rm = FALSE) {
   S7_dispatch()
})

method(mean2, class_numeric) <- function(x, ..., na.rm = FALSE) {
  if (na.rm) {
    x <- x[!is.na(x)]
  }
  sum(x) / length(x)
}

# You'll be warned if you forget the argument:
method(mean2, class_character) <- function(x, ...) {
  stop("Not supported")
}