src/library/methods/man/setAs.Rd - R - Git at Google

 % File src/library/methods/man/setAs.Rd
 % Part of the R package, https://www.R-project.org
 % Copyright 1995-2016 R Core Team
 % Distributed under GPL 2 or later

 \name{setAs}
 \alias{coerce}
 \alias{coerce<-}
 \alias{setAs}
 \alias{coerce-methods}
 \alias{coerce,ANY,array-method}
 \alias{coerce,ANY,call-method}
 \alias{coerce,ANY,character-method}
 \alias{coerce,ANY,complex-method}
 \alias{coerce,ANY,environment-method}
 \alias{coerce,ANY,expression-method}
 \alias{coerce,ANY,function-method}
 \alias{coerce,ANY,integer-method}
 \alias{coerce,ANY,list-method}
 \alias{coerce,ANY,logical-method}
 \alias{coerce,ANY,matrix-method}
 \alias{coerce,ANY,name-method}
 \alias{coerce,ANY,numeric-method}
 \alias{coerce,ANY,single-method}
 \alias{coerce,ANY,ts-method}
 \alias{coerce,ANY,vector-method}
 \alias{coerce,ANY,NULL-method}
 \title{Methods for Coercing an Object to a Class}
 \description{
   A call to \code{setAs} defines a method for coercing an object of
   class \code{from} to class \code{to}.  The methods will then be used
   by calls to \code{\link{as}} for objects with class \code{from},
   including calls that replace part of the object.

   Methods for this purpose work indirectly, by defining methods for
   function \code{coerce}.  The \code{coerce} function is \emph{not} to
   be called directly, and method selection uses class inheritance only
   on the first argument.
 }
 \usage{
 setAs(from, to, def, replace, where = topenv(parent.frame()))
 }
 \arguments{
   \item{from, to}{The classes between which the coerce methods
     \code{def} and \code{replace} perform coercion.
   }
   \item{def}{function of one argument.  It will get an object from
     class \code{from} and had better return an object of class
     \code{to}.  The convention is that
     the name of the argument is \code{from}; if another argument name
     is used, \code{setAs} will attempt to substitute \code{from}. }
   \item{replace}{if supplied, the function to use as a replacement
     method, when \code{as} is used on the left of an assignment.
     Should be a function of two arguments, \code{from, value},
     although \code{setAs} will attempt to substitute if the arguments
     differ.

 \emph{The remaining argument will not be used in standard applications.}
   }

   \item{where}{the position or environment in which to store the
     resulting methods. Do not use this argument when defining a method
     in a package.  Only the default, the namespace of the package,
     should be used in normal situations.
     }
 }

 \section{Inheritance and Coercion}{

  Objects from one class can turn into objects from another class
   either automatically or by an explicit call to the \code{as}
   function.  Automatic conversion is special, and comes from the
   designer of one class of objects asserting that this class extends
   another class.  The most common case is that one or more class names
   are supplied in the \code{contains=} argument to \code{setClass}, in
   which case the new class extends each of the earlier classes (in the
   usual terminology, the earlier classes are \emph{superclasses} of
   the new class and it is a \emph{subclass} of each of them).

 This form of inheritance is called \emph{simple} inheritance in \R.
 See \code{\link{setClass}} for details.
 Inheritance can also be defined explicitly by a call to
 \code{\link{setIs}}.
 The two versions have slightly different implications for coerce methods.
 Simple inheritance implies that inherited slots behave identically in the subclass and the superclass.
 Whenever two classes are related by simple inheritance, corresponding coerce methods
 are defined for both direct and replacement use of \code{as}.
 In the case of simple inheritance, these methods do the obvious
 computation:  they extract or replace the slots in the object that
 correspond to those in the superclass definition.

 The implicitly defined coerce methods may be overridden by a call
 to \code{setAs}; note, however, that the implicit methods are defined for each
 subclass-superclass pair, so that you must override each of these
 explicitly, not rely on inheritance.

 When inheritance is defined by a call to \code{setIs}, the coerce methods are provided explicitly, not generated automatically.
 Inheritance will apply (to the \code{from} argument, as described in  the section below).
 You could also supply methods via \code{setAs} for non-inherited relationships, and now these also can be inherited.

 For further on the distinction between simple and explicit inheritance, see \code{\link{setIs}}.

 }
 \section{How Functions 'as' and 'setAs' Work}{
   The function \code{as}  turns \code{object} into an object
   of class \code{Class}.  In doing so, it applies a \dQuote{coerce
     method}, using S4
   classes and methods, but in a somewhat special way.
 Coerce methods are methods for the function \code{coerce} or, in the
 replacement case the function \code{`coerce<-`}.
 These functions have two arguments in method signatures, \code{from}
 and \code{to}, corresponding to the class of the object and the
 desired coerce class.
 These functions must not be called directly, but are used to store
 tables of methods for the use of \code{as}, directly and for
 replacements.
 In this section we will describe the direct case, but except where
 noted the replacement case works the same way, using \code{`coerce<-`}
 and the \code{replace} argument to \code{setAs}, rather than
 \code{coerce} and the \code{def} argument.

 Assuming the \code{object} is not already of the desired class,
 \code{as} first looks for a method in the table of methods
  for the function
   \code{coerce} for the signature \code{c(from = class(object), to =
     Class)}, in the same way method selection would do its initial lookup.
 To be precise, this means the table of both direct and inherited
 methods, but inheritance is used specially in this case (see below).

 If no method is found, \code{as} looks for one.
 First, if either \code{Class} or \code{class(object)} is a superclass
 of the other, the class definition will contain the information needed
 to construct a coerce method.
 In the usual case that the subclass contains the superclass (i.e., has
 all its slots), the method is constructed either by extracting or
 replacing the inherited slots.
 Non-simple extensions (the result of a call to \code{\link{setIs}})
 will usually contain explicit methods, though possibly not for replacement.

  If no subclass/superclass relationship provides a method, \code{as}
  looks for an inherited method, but applying, inheritance for the argument \code{from} only, not for
   the argument \code{to} (if you think about it, you'll probably agree
   that you wouldn't want the result to be from some class other than the
   \code{Class} specified). Thus,
   \code{selectMethod("coerce", sig, useInherited= c(from=TRUE, to= FALSE))}
   replicates the method selection used by \code{as()}.

 In nearly all cases the method found in this way will be cached in the
 table of coerce methods (the exception being subclass relationships with a test, which
 are legal but discouraged).
 So the detailed calculations should be done only on the first
 occurrence of a coerce from \code{class(object)} to \code{Class}.

 Note that  \code{coerce} is not a standard generic function.  It is
 not intended to be called directly.  To prevent accidentally caching
 an invalid inherited method, calls are routed to an equivalent call to
 \code{as}, and a warning is issued.  Also, calls to
 \code{\link{selectMethod}} for this function may not represent the
 method that \code{as} will choose.  You can only trust the result if
 the corresponding call to \code{as} has occurred previously in this
 session.

   With this explanation as background, the function \code{setAs} does a
   fairly obvious computation:  It constructs and sets a method for the function
   \code{coerce} with signature \code{c(from, to)}, using the \code{def}
   argument to define the body of the method.  The function supplied as
   \code{def} can have one argument (interpreted as an object to be
   coerced) or two arguments (the \code{from} object and the \code{to}
   class).  Either way, \code{setAs} constructs a function of two
   arguments, with the second defaulting to the name of the \code{to}
   class.  The method will be called from \code{as} with the object
   as the \code{from} argument and no \code{to} argument, with the default for this argument being the name of the intended
   \code{to} class, so the method can use this information in messages.

 The direct version of the \code{as} function also has a \code{strict=} argument that defaults to \code{TRUE}.
 Calls during the evaluation of methods for other functions will set this argument to \code{FALSE}.
 The distinction is relevant when the object being coerced is from a simple subclass of the \code{to} class; if \code{strict=FALSE} in this case, nothing need be done.
 For most user-written coerce methods, when the two classes have no subclass/superclass, the \code{strict=} argument is irrelevant.

 The \code{replace} argument to \code{setAs} provides a method for
 \code{`coerce<-`}.
 As with all replacement methods, the last argument of the method must
 have the name \code{value} for the object on the right of the
 assignment.
 As with the \code{coerce} method, the first two arguments are
 \code{from, to}; there is no \code{strict=} option for the replace case.

   The function \code{coerce} exists as a repository for
   such methods, to be selected as described above by the \code{as}
   function.  Actually dispatching the methods using
   \code{standardGeneric} could produce incorrect inherited methods, by using
    inheritance on the
   \code{to} argument; as mentioned, this is not the logic used for
   \code{as}.
   To prevent selecting and caching invalid methods, calls to
   \code{coerce} are
   currently mapped into calls to \code{as}, with a warning message.
 }


 \section{Basic Coercion Methods}{
   Methods are pre-defined for coercing any object to one of the basic
   datatypes.  For example, \code{as(x, "numeric")} uses the existing
   \code{as.numeric} function.  These built-in methods can be listed by
   \code{showMethods("coerce")}.
 }

 \seealso{
   If you think of using \code{try(as(x, cl))}, consider
   \code{\link{canCoerce}(x, cl)} instead.
 }
 \references{
  Chambers, John M. (2016)
  \emph{Extending R},
   Chapman & Hall.
 (Chapters 9 and 10.)
 }

 \examples{
 ## using the definition of class "track" from \link{setClass}

 \dontshow{
 setClass("track", slots = c(x="numeric", y="numeric"))
 setClass("trackCurve", contains = "track", slots = c(smooth = "numeric"))
 }

 setAs("track", "numeric", function(from) from@y)

 t1 <- new("track", x=1:20, y=(1:20)^2)

 as(t1, "numeric")

 ## The next example shows:
 ##  1. A virtual class to define setAs for several classes at once.
 ##  2. as() using inherited information

 setClass("ca", slots = c(a = "character", id = "numeric"))

 setClass("cb", slots = c(b = "character", id = "numeric"))

 setClass("id")
 setIs("ca", "id")
 setIs("cb", "id")


 setAs("id", "numeric", function(from) from@id)

 CA <- new("ca", a = "A", id = 1)
 CB <- new("cb", b = "B", id = 2)

 setAs("cb", "ca", function(from, to )new(to, a=from@b, id = from@id))

 as(CB, "numeric")

 \dontshow{
 ## should generate an error (should have been a function of one argument)
 try(setAs("track", "numeric", function(x, y,z)x@y))
 }
 }
 \keyword{programming}
 \keyword{classes}
 \keyword{methods}
	% File src/library/methods/man/setAs.Rd
	% Part of the R package, https://www.R-project.org
	% Copyright 1995-2016 R Core Team
	% Distributed under GPL 2 or later

	\name{setAs}
	\alias{coerce}
	\alias{coerce<-}
	\alias{setAs}
	\alias{coerce-methods}
	\alias{coerce,ANY,array-method}
	\alias{coerce,ANY,call-method}
	\alias{coerce,ANY,character-method}
	\alias{coerce,ANY,complex-method}
	\alias{coerce,ANY,environment-method}
	\alias{coerce,ANY,expression-method}
	\alias{coerce,ANY,function-method}
	\alias{coerce,ANY,integer-method}
	\alias{coerce,ANY,list-method}
	\alias{coerce,ANY,logical-method}
	\alias{coerce,ANY,matrix-method}
	\alias{coerce,ANY,name-method}
	\alias{coerce,ANY,numeric-method}
	\alias{coerce,ANY,single-method}
	\alias{coerce,ANY,ts-method}
	\alias{coerce,ANY,vector-method}
	\alias{coerce,ANY,NULL-method}
	\title{Methods for Coercing an Object to a Class}
	\description{
	A call to \code{setAs} defines a method for coercing an object of
	class \code{from} to class \code{to}. The methods will then be used
	by calls to \code{\link{as}} for objects with class \code{from},
	including calls that replace part of the object.

	Methods for this purpose work indirectly, by defining methods for
	function \code{coerce}. The \code{coerce} function is \emph{not} to
	be called directly, and method selection uses class inheritance only
	on the first argument.
	}
	\usage{
	setAs(from, to, def, replace, where = topenv(parent.frame()))
	}
	\arguments{
	\item{from, to}{The classes between which the coerce methods
	\code{def} and \code{replace} perform coercion.
	}
	\item{def}{function of one argument. It will get an object from
	class \code{from} and had better return an object of class
	\code{to}. The convention is that
	the name of the argument is \code{from}; if another argument name
	is used, \code{setAs} will attempt to substitute \code{from}. }
	\item{replace}{if supplied, the function to use as a replacement
	method, when \code{as} is used on the left of an assignment.
	Should be a function of two arguments, \code{from, value},
	although \code{setAs} will attempt to substitute if the arguments
	differ.

	\emph{The remaining argument will not be used in standard applications.}
	}

	\item{where}{the position or environment in which to store the
	resulting methods. Do not use this argument when defining a method
	in a package. Only the default, the namespace of the package,
	should be used in normal situations.
	}
	}

	\section{Inheritance and Coercion}{

	Objects from one class can turn into objects from another class
	either automatically or by an explicit call to the \code{as}
	function. Automatic conversion is special, and comes from the
	designer of one class of objects asserting that this class extends
	another class. The most common case is that one or more class names
	are supplied in the \code{contains=} argument to \code{setClass}, in
	which case the new class extends each of the earlier classes (in the
	usual terminology, the earlier classes are \emph{superclasses} of
	the new class and it is a \emph{subclass} of each of them).

	This form of inheritance is called \emph{simple} inheritance in \R.
	See \code{\link{setClass}} for details.
	Inheritance can also be defined explicitly by a call to
	\code{\link{setIs}}.
	The two versions have slightly different implications for coerce methods.
	Simple inheritance implies that inherited slots behave identically in the subclass and the superclass.
	Whenever two classes are related by simple inheritance, corresponding coerce methods
	are defined for both direct and replacement use of \code{as}.
	In the case of simple inheritance, these methods do the obvious
	computation: they extract or replace the slots in the object that
	correspond to those in the superclass definition.

	The implicitly defined coerce methods may be overridden by a call
	to \code{setAs}; note, however, that the implicit methods are defined for each
	subclass-superclass pair, so that you must override each of these
	explicitly, not rely on inheritance.

	When inheritance is defined by a call to \code{setIs}, the coerce methods are provided explicitly, not generated automatically.
	Inheritance will apply (to the \code{from} argument, as described in the section below).
	You could also supply methods via \code{setAs} for non-inherited relationships, and now these also can be inherited.

	For further on the distinction between simple and explicit inheritance, see \code{\link{setIs}}.

	}
	\section{How Functions 'as' and 'setAs' Work}{
	The function \code{as} turns \code{object} into an object
	of class \code{Class}. In doing so, it applies a \dQuote{coerce
	method}, using S4
	classes and methods, but in a somewhat special way.
	Coerce methods are methods for the function \code{coerce} or, in the
	replacement case the function \code{`coerce<-`}.
	These functions have two arguments in method signatures, \code{from}
	and \code{to}, corresponding to the class of the object and the
	desired coerce class.
	These functions must not be called directly, but are used to store
	tables of methods for the use of \code{as}, directly and for
	replacements.
	In this section we will describe the direct case, but except where
	noted the replacement case works the same way, using \code{`coerce<-`}
	and the \code{replace} argument to \code{setAs}, rather than
	\code{coerce} and the \code{def} argument.

	Assuming the \code{object} is not already of the desired class,
	\code{as} first looks for a method in the table of methods
	for the function
	\code{coerce} for the signature \code{c(from = class(object), to =
	Class)}, in the same way method selection would do its initial lookup.
	To be precise, this means the table of both direct and inherited
	methods, but inheritance is used specially in this case (see below).

	If no method is found, \code{as} looks for one.
	First, if either \code{Class} or \code{class(object)} is a superclass
	of the other, the class definition will contain the information needed
	to construct a coerce method.
	In the usual case that the subclass contains the superclass (i.e., has
	all its slots), the method is constructed either by extracting or
	replacing the inherited slots.
	Non-simple extensions (the result of a call to \code{\link{setIs}})
	will usually contain explicit methods, though possibly not for replacement.

	If no subclass/superclass relationship provides a method, \code{as}
	looks for an inherited method, but applying, inheritance for the argument \code{from} only, not for
	the argument \code{to} (if you think about it, you'll probably agree
	that you wouldn't want the result to be from some class other than the
	\code{Class} specified). Thus,
	\code{selectMethod("coerce", sig, useInherited= c(from=TRUE, to= FALSE))}
	replicates the method selection used by \code{as()}.

	In nearly all cases the method found in this way will be cached in the
	table of coerce methods (the exception being subclass relationships with a test, which
	are legal but discouraged).
	So the detailed calculations should be done only on the first
	occurrence of a coerce from \code{class(object)} to \code{Class}.

	Note that \code{coerce} is not a standard generic function. It is
	not intended to be called directly. To prevent accidentally caching
	an invalid inherited method, calls are routed to an equivalent call to
	\code{as}, and a warning is issued. Also, calls to
	\code{\link{selectMethod}} for this function may not represent the
	method that \code{as} will choose. You can only trust the result if
	the corresponding call to \code{as} has occurred previously in this
	session.

	With this explanation as background, the function \code{setAs} does a
	fairly obvious computation: It constructs and sets a method for the function
	\code{coerce} with signature \code{c(from, to)}, using the \code{def}
	argument to define the body of the method. The function supplied as
	\code{def} can have one argument (interpreted as an object to be
	coerced) or two arguments (the \code{from} object and the \code{to}
	class). Either way, \code{setAs} constructs a function of two
	arguments, with the second defaulting to the name of the \code{to}
	class. The method will be called from \code{as} with the object
	as the \code{from} argument and no \code{to} argument, with the default for this argument being the name of the intended
	\code{to} class, so the method can use this information in messages.

	The direct version of the \code{as} function also has a \code{strict=} argument that defaults to \code{TRUE}.
	Calls during the evaluation of methods for other functions will set this argument to \code{FALSE}.
	The distinction is relevant when the object being coerced is from a simple subclass of the \code{to} class; if \code{strict=FALSE} in this case, nothing need be done.
	For most user-written coerce methods, when the two classes have no subclass/superclass, the \code{strict=} argument is irrelevant.

	The \code{replace} argument to \code{setAs} provides a method for
	\code{`coerce<-`}.
	As with all replacement methods, the last argument of the method must
	have the name \code{value} for the object on the right of the
	assignment.
	As with the \code{coerce} method, the first two arguments are
	\code{from, to}; there is no \code{strict=} option for the replace case.

	The function \code{coerce} exists as a repository for
	such methods, to be selected as described above by the \code{as}
	function. Actually dispatching the methods using
	\code{standardGeneric} could produce incorrect inherited methods, by using
	inheritance on the
	\code{to} argument; as mentioned, this is not the logic used for
	\code{as}.
	To prevent selecting and caching invalid methods, calls to
	\code{coerce} are
	currently mapped into calls to \code{as}, with a warning message.
	}


	\section{Basic Coercion Methods}{
	Methods are pre-defined for coercing any object to one of the basic
	datatypes. For example, \code{as(x, "numeric")} uses the existing
	\code{as.numeric} function. These built-in methods can be listed by
	\code{showMethods("coerce")}.
	}

	\seealso{
	If you think of using \code{try(as(x, cl))}, consider
	\code{\link{canCoerce}(x, cl)} instead.
	}
	\references{
	Chambers, John M. (2016)
	\emph{Extending R},
	Chapman & Hall.
	(Chapters 9 and 10.)
	}

	\examples{
	## using the definition of class "track" from \link{setClass}

	\dontshow{
	setClass("track", slots = c(x="numeric", y="numeric"))
	setClass("trackCurve", contains = "track", slots = c(smooth = "numeric"))
	}

	setAs("track", "numeric", function(from) from@y)

	t1 <- new("track", x=1:20, y=(1:20)^2)

	as(t1, "numeric")

	## The next example shows:
	## 1. A virtual class to define setAs for several classes at once.
	## 2. as() using inherited information

	setClass("ca", slots = c(a = "character", id = "numeric"))

	setClass("cb", slots = c(b = "character", id = "numeric"))

	setClass("id")
	setIs("ca", "id")
	setIs("cb", "id")


	setAs("id", "numeric", function(from) from@id)

	CA <- new("ca", a = "A", id = 1)
	CB <- new("cb", b = "B", id = 2)

	setAs("cb", "ca", function(from, to )new(to, a=from@b, id = from@id))

	as(CB, "numeric")

	\dontshow{
	## should generate an error (should have been a function of one argument)
	try(setAs("track", "numeric", function(x, y,z)x@y))
	}
	}
	\keyword{programming}
	\keyword{classes}
	\keyword{methods}