Utility function for defining S3 methods

Utility function for defining S3 methods [R logo]

Help pages for package ‘R.methodsS3’ version 1.0.3

R.methodsS3-package | Package R.methodsS3
getGenericS3 | Get an S3 generic function
getGenericS3.default | Get an S3 generic function
getMethodS3 | Get an S3 method
getMethodS3.default | Get an S3 method
R.methodsS3 | Package R.methodsS3
setMethodS3 | Creates an S3 method
setMethodS3.default | Creates an S3 method
throw | Throws an exception
throw.default | Throws an exception


Get an S3 generic function

Description

Get an S3 generic function.

Usage

## Default S3 method:
getGenericS3(name, ...)

Arguments

name | The name of the generic function.
... | Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

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

[Package R.methodsS3 version 1.0.3 Index]


Get an S3 method

Description

Get an S3 method.

Usage

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

Arguments

name | The name of the method.
class | The class of the method.
... | Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

See Also

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

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 defintion; 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")


Checks if a function is a S3/UseMethod generic function

Description

Checks if a function is a S3/UseMethod generic function.

Usage

## Default S3 method:
isGenericS3(fcn, ...)

Arguments

fcn | A function or a character string.
... | Not used.

Details

A function is considered to be a generic S3/UseMethod function if its body, that is the source code, contains the regular pattern "UseMethod[(]".

Value

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

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)


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 maintainance for package developers. For example, generic functions are created automatically, if missing, and name conflict are automatically solved, if possible. The method setMethodS3() is a good start for those who in the future want to migrate to S4. This is a cross-platform package implemented in pure R and is generating standard S3 methods. This contents of this package was extracted from the R.oo package [1].

Installation and updates

To install this package do

install.packages("R.methodsS3")

To get the "devel" version, see http://www.braju.com/R/.

Dependancies 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

@INPROCEEDINGS{BengtssonH_2003,
 author       = {Henrik Bengtsson},
 title        = {The {R.oo} package - Object-Oriented Programming
                 with References Using Standard {R} Code},
 booktitle    = {Proceedings of the 3rd International Workshop on
                 Distributed Statistical Computing (DSC 2003)},
 year         = {2003},
 editor       = {Kurt Hornik and Friedrich Leisch and Achim Zeileis},
 address      = {Vienna, Austria},
 month        = {March},
 issn         = {1609-395X},
 howpublished = {http://www.ci.tuwien.ac.at/Conferences/DSC-2003/},
}

License

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

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

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. http://www.ci.tuwien.ac.at/Conferences/DSC-2003/Proceedings/


Creates a generic function in S3/UseMethod style

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, envir=parent.frame(), ellipsesOnly=TRUE, dontWarn=getOption("dontWarnPkgs"), validators=getOption("R.methodsS3:validators:setGenericS3"), ...)

Arguments

name | The name of the generic function.
envir | The environment for where this method should be stored.
ellipsesOnly | If TRUE, the only arguments in the generic function will be ....
dontWarn | If a non-generic method with the same name is found it will be "renamed" to a default method. If that method is found in a package with a name that is not found in dontWarn a warning will be produced, otherwise it will be renamed silently.
validators | An optional list of functions that can be used to assert that the generated generic function meets certain criteria.
... | Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

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);
  attr(mat, "class") <- "matrix";  # Has to be done as of [R] V1.4.0.
  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, static=FALSE, abstract=FALSE, trial=FALSE, deprecated=FALSE, envir=parent.frame(), overwrite=TRUE, conflict=c("warning", "error", "quiet"), createGeneric=TRUE, appendVarArgs=TRUE, validators=getOption("R.methodsS3:validators:setMethodS3"), ...)

Arguments

name | The name of the method.
class | The class for which the method should be defined. If class == "default" a function with name <name>.default will be created.
definition | The method defintion.
private, protected | If private=TRUE, the method is declared private. If protected=TRUE, the method is declared protected. In all other cases the method is declared public.
static | If TRUE this method is defined to be static, otherwise not. Currently this has no effect expect as an indicator.
abstract | If TRUE this method is defined to be abstract, otherwise not. Currently this has no effect expect as an indicator.
trial | If TRUE this method is defined to be a trial method, otherwise not. A trial method is a method that is introduced to be tried out and it might be modified, replaced or even removed in a future release. Some people prefer to call trial versions, beta version. Currently this has no effect expect as an indicator.
deprecated | If TRUE this method is defined to be deprecated, otherwise not. Currently this has no effect expect as an indicator.
envir | The environment for where this method should be stored.
overwrite | If TRUE an already existing method with the same name (and of the same class) will be overwritten, otherwise not.
conflict | If a method already exists with the same name (and of the same class), different actions can be taken. If "error", an exception will be thrown and the method will not be created. If "warning", a warning will be given and the method will be created, otherwise the conflict will be passed unnotice.
createGeneric | If TRUE, a generic S3/UseMethod function is defined for this method.
appendVarArgs | If TRUE, argument ... is added with a warning, if missing. For special methods such as $ and [[, this is never done. This will increase the chances that the method is consistent with a generic function with many arguments and/or argument ....
validators | An optional list of functions that can be used to assert that the generated method meets certain criteria.
... | Not used.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

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 defintion; 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 throw implementation is fully backward compatible with this one, but the error object thrown is of class Exception.

Usage

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

Arguments

... One or several strings that are concatenated and collapsed into on message string.

Value

Returns nothing.

Author(s)

Henrik Bengtsson (http://www.braju.com/R/)

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) {}
  )