Package R.methodsS3

Description

Methods that simplify the setup of S3 generic functions and S3 methods. Major effort has been made in making definition of methods as simple as possible with a minimum of maintenance for package developers. For example, generic functions are created automatically, if missing, and naming conflict are automatically solved, if possible. The method setMethodS3() is a good start for those who in the future may want to migrate to S4. This is a cross-platform package implemented in pure R that generates standard S3 methods. This contents of this package originates from the R.oo package [1].

Installation and updates

To install this package do

install.packages("R.methodsS3")

To get the "devel" version, see https://github.com/HenrikBengtsson/R.methodsS3/.

Dependencies and other requirements

This package only requires a standard R installation.

To get started

To get started, see:

1. setMethodS3() - Simple and safe creation of S3 methods and, whenever needed, automatic creation of S3 generic function.

Further readings

For a detailed introduction to the package, see [1].

How to cite this package

Whenever using this package, please cite [1] as

Bengtsson, H. The R.oo package - Object-Oriented Programming with References Using
Standard R Code, Proceedings of the 3rd International Workshop on Distributed
Statistical Computing (DSC 2003), ISSN 1609-395X, Hornik, K.; Leisch, F. & Zeileis,
A. (ed.), 2003

License

The releases of this package is licensed under LGPL version 2.1 or newer.

Author(s)

Henrik Bengtsson

References

[1] H. Bengtsson, The R.oo package - Object-Oriented Programming with References Using Standard R Code, In Kurt Hornik, Friedrich Leisch and Achim Zeileis, editors, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. https://www.r-project.org/conferences/DSC-2003/Proceedings/

Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R CMD check detects in this package.

Almost all of them are generic functions that have specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to default methods. Neither of these two classes are non-documented in reality. The rest are deprecated methods.

Author(s)

Henrik Bengtsson

Reserved words in R not to be used for object names

Description

Reserved words in R not to be used for object names. R.KEYWORDS is a character vector of all reserved words in R according to [1].

Author(s)

Henrik Bengtsson

References

[1] Section "Reserved words", R Language Definition, version 2.6.0 (2007-09-14) DRAFT.

Finds the S3 methods that a generic function would call

Description

Finds the S3 methods that a generic function would call, ordered according to an S3 class() vector.

Usage

## Default S3 method:
findDispatchMethodsS3(methodName, classNames, firstOnly=FALSE, ...)

Arguments

Value

Returns a names list structure.

Author(s)

Henrik Bengtsson

See Also

getDispatchMethodS3().

Gets the S3 method that a generic function would call

Description

Gets the S3 method that a generic function would call according to an S3 class() vector.

Usage

## Default S3 method:
getDispatchMethodS3(methodName, classNames, ...)

Arguments

Value

Returns a function, or throws an exception if not found.

Author(s)

Henrik Bengtsson

See Also

findDispatchMethodsS3().

Gets an S3 generic function

Description

Gets an S3 generic function.

Usage

## Default S3 method:
getGenericS3(name, envir=parent.frame(), inherits=TRUE, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

setGenericS3(). getMethodS3(). isGenericS3().

Gets an S3 method

Description

Gets an S3 method.

Usage

## Default S3 method:
getMethodS3(name, class="default", envir=parent.frame(), ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

This is just a conveniency wrapper around getS3method that have arguments consistent with setMethodS3(). getGenericS3().

Checks if a function is a S3 generic function

Description

Checks if a function is a S3 generic function.

Usage

## Default S3 method:
isGenericS3(fcn, envir=parent.frame(), ...)

Arguments

Details

A function is considered to be a generic S3/UseMethod function if its name matches one of the known S3 generic functions, or if it calls UseMethod().

Value

Returns TRUE if a generic S3/UseMethod function, otherwise FALSE.

Author(s)

Henrik Bengtsson

Checks if a function is a S4 generic function

Description

Checks if a function is a S4 generic function.

Usage

## Default S3 method:
isGenericS4(fcn, envir=parent.frame(), ...)

Arguments

Details

A function is considered to be a generic S4 function if its body, that is the source code, contains the regular pattern "standardGeneric".

Value

Returns TRUE if a generic S4 function, otherwise FALSE.

Author(s)

Henrik Bengtsson

Generates a (package) startup message

Description

Generates a (package) startup message. Contrary to packageStartupMessage(), this method does not output a message when library()/require() is called with argument quietly=TRUE.

Usage

## Default S3 method:
pkgStartupMessage(..., quietly=NA)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

packageStartupMessage().

Creates an S3 generic function

Description

Note that this method is a internal method called by setMethodS3() and there is no reason for calling it directly!

Creates a generic function in S3 style, i.e. setting a function with name name that dispatches the method name via UseMethod. If there is already a function named name that function is renamed to name.default.

Usage

## Default S3 method:
setGenericS3(name, export=TRUE, envir=parent.frame(), dontWarn=getOption("dontWarnPkgs"),
  validators=getOption("R.methodsS3:validators:setGenericS3"), overwrite=FALSE, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

To define a method for a class see setMethodS3(). For more information about S3, see UseMethod().

Examples

myCat.matrix <- function(..., sep=", ") {
  cat("A matrix:\n")
  cat(..., sep=sep)
  cat("\n")
}

myCat.default <- function(..., sep=", ") {
  cat(..., sep=sep)
  cat("\n")
}

setGenericS3("myCat")

myCat(1:10)
mat <- matrix(1:10, ncol=5)
myCat(mat)

Creates an S3 method

Description

Creates an S3 method. A function with name <name>.<class> will be set to definition. The method will get the modifiers specified by modifiers. If there exists no generic function for this method, it will be created automatically.

Usage

## Default S3 method:
setMethodS3(name, class="default", definition, private=FALSE, protected=FALSE,
  export=FALSE, static=FALSE, abstract=FALSE, trial=FALSE, deprecated=FALSE,
  envir=parent.frame(), overwrite=TRUE, conflict=c("warning", "error", "quiet"),
  createGeneric=TRUE, exportGeneric=TRUE, appendVarArgs=TRUE,
  validators=getOption("R.methodsS3:validators:setMethodS3"), ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

For more information about S3, see UseMethod().

Examples

######################################################################
# Example 1
######################################################################
setMethodS3("foo", "default", function(x, ...) {
  cat("In default foo():\n");
  print(x, ...);
})


setMethodS3("foo", "character", function(s, ...) {
  cat("In foo() for class 'character':\n");
  print(s, ...);
})

# The generic function is automatically created!
print(foo)

foo(123)
foo("123")


######################################################################
# Example 2
#
# Assume that in a loaded package there is already a function bar(),
# but you also want to use the name 'bar' for the character string.
# It may even be the case that you do not know of the other package,
# but your users do!
######################################################################
# bar() in other package
bar <- function(x, y, ...) {
  cat("In bar() of 'other' package.\n");
}


# Your definition; will redefine bar() above to bar.default().
setMethodS3("bar", "character", function(object, ...) {
  cat("In bar() for class 'character':\n");
  print(object, ...);
})

bar(123)
bar("123")

Throws an exception

Description

Throws an exception by calling stop().

Note that throw() can be defined for specific classes, which can then be caught (or not) using tryCatch().

This default function will be overridden by ditto in the R.oo package, if that is loaded. The latter R.oo::throw() implementation is fully backward compatible with this one, but the error object thrown is of class R.oo::Exception.

WARNING: This function is deprecated in favor of R.oo::throw(), or alternatively, just stop().

Usage

## Default S3 method:
throw(...)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Examples

rbern <- function(n=1, prob=1/2) {
  if (prob < 0 || prob > 1)
    throw("Argument 'prob' is out of range: ", prob)
  rbinom(n=n, size=1, prob=prob)
}

rbern(10, 0.4)
# [1] 0 1 0 0 0 1 0 0 1 0
tryCatch({
  rbern(10, 10*0.4)
}, error=function(ex) {})