setGeneric(methods)
setGeneric()所属R语言包：methods
Define a New Generic Function
定义一个新的通用功能
译者：生物统计家园网 机器人LoveR
描述----------Description----------
Create a new generic function of the given name, that is, a function that dispatches methods according to the classes of the arguments, from among the formal methods defined for this function.
给定的名称，就是一个调度方法，根据参数的类，从正规的方法，这个函数定义的函数创建一个新的通用功能。
用法----------Usage----------
setGeneric(name, def= , group=list(), valueClass=character(),
where= , package= , signature= , useAsDefault= ,
genericFunction= , simpleInheritanceOnly = )
setGroupGeneric(name, def= , group=list(), valueClass=character(),
knownMembers=list(), package= , where= )
参数----------Arguments----------
参数：name
The character string name of the generic function. The simplest (and recommended) call, setGeneric(name), looks for a function with this name and creates a corresponding generic function, if the function found was not generic.
泛型函数的字符串名称。最简单的调用（和建议），setGeneric(name)，看上去与这个名字的功能，并创建一个相应的通用功能，如果发现是不通用的功能。
参数：def
An optional function object, defining the generic. Don't supply this argument if you want an existing non-generic function to supply the arguments. Do supply it if there is no current function of this name, or if you want the generic function to have different arguments. In that case, the formal arguments and default values for the generic are taken from def. You can also supply this argument if you want the generic function to do something other than just dispatch methods. Note that def is not the default method; use argument useAsDefault if you want to specify the default separately.
一个可选的函数对象，定义泛型。如果您想将现有的非泛型函数提供的参数不提供此参数。做供应，如果没有这个名字的当前功能，或者如果您想泛型函数有不同的参数。在这种情况下，正式通用的参数和默认值从def。如果你想不仅仅是调度方法做一些其他的通用功能，还可以提供这种说法。注意def是不是默认的方法，使用参数useAsDefault如果你想单独指定默认。
参数：group
Optionally, a character string giving the name of the group generic function to which this function belongs. See Methods for details of group generic functions in method selection.
可选，给泛型函数组的名称字符串属于这一功能。方法选择组通用功能的详细信息，请参阅方法。
参数：valueClass
An optional character vector of one or more class names. The value returned by the generic function must have (or extend) this class, or one of the classes; otherwise, an error is generated.
可选的特征向量的一个或多个类名。泛型函数的返回值必须拥有（或延长）这个类，或一个类的，否则，就会产生错误。
参数：package
The name of the package with which this function is associated. Usually determined automatically (as the package containing the non-generic version if there is one, or else the package where this generic is to be saved).
与此功能相关联的包的名称。一般自动确定（包含的非泛型版本，如果有一个，否则包是被保存在这个通用）。
参数：where
Where to store the resulting initial methods definition, and possibly the generic function; by default, stored into the top-level environment.
存储造成的最初的定义方法，可能是通用的功能，默认情况下，存储到顶级的环境。
参数：signature
Optionally, the vector of names, from among the formal arguments to the function, that can appear in the signature of methods for this function, in calls to setMethod. If ... is one of the formal arguments, it is treated specially. Starting with version 2.8.0 of R, ... may be signature of the generic function. Methods will then be selected if their signature matches all the ... arguments. See the documentation for topic dotsMethods for details. In the present version, it is not possible to mix ... and other arguments in the signature (this restriction may be lifted in later versions). By default, the signature is inferred from the implicit generic function corresponding to a non-generic function. If no implicit generic function has been defined, the default is all the formal arguments except ..., in the order they appear in the function definition. In the case that ... is the only formal argument, that is also the default signature. To use ... as the signature in a function that has any other arguments, you must supply the signature argument explicitly. See the “Implicit Generic” section below for more details.
或者，向量的名称，从形式参数的功能，可以在此功能的方法签名出现在调用setMethod。如果...是正式的参数之一，它是特殊处理。与R的2.8.0版本开始，...可能是泛型函数的签名。如果他们的签名相匹配所有方法，然后将选择......参数。请参见详情主题dotsMethods的文件。在目前的版本，它是不可能的混合...并在签名中的其他参数（这个限制可以在以后的版本中取消）。默认情况下，签名是推断隐含的通用功能，相应的非通用功能。如果没有隐含的通用功能已被定义，默认是所有除......，在他们的顺序出现在函数定义的形式参数。万一......是唯一正式的说法，这也是默认的签名。使用...有任何其他参数在函数的签名，你必须提供明确的签名参数。详情请参阅“隐通用”节。
参数：useAsDefault
Override the usual choice of default argument (an existing non-generic function or no default if there is no such function). Argument useAsDefault can be supplied, either as a function to use for the default, or as a logical value. FALSE says not to have a default method at all, so that an error occurs if there is not an explicit or inherited method for a call. TRUE says to use the existing function as default, unconditionally (hardly ever needed as an explicit argument). See the section on details.
覆盖通常选择默认参数（现有的非通用功能或没有默认值，如果没有这样的功能）。参数useAsDefault可提供，无论是作为一个函数来使用的默认，或作为一个逻辑值。 FALSE不说有一个默认的方法，所以发生错误，如果没有明确呼叫或继承的方法。 TRUE说默认情况下，使用现有的功能，无条件（未落需要一个明确的说法）。看到细节部分。
参数：simpleInheritanceOnly
Supply this argument as TRUE to require that methods selected be inherited through simple inheritance only; that is, from superclasses specified in the contains= argument to setClass, or by simple inheritance to a class union or other virtual class. Generic functions should require simple inheritance if they need to be assured that they get the complete original object, not one that has been transformed. Examples of functions requiring simple inheritance are initialize, because by definition it must return an object from the same class as its argument, and show, because it claims to give a full description of the object provided as its argument.
TRUE这种说法提供要求，选择的方法，可以通过简单的继承继承;也就是说，从contains=setClass参数指定的父，或通过简单的继承类工会或其他虚拟类。通用功能要求简单的继承，如果他们需要得到保证，他们得到完整的原始对象，而不是一个已经转化。需要简单继承的功能的例子是initialize，因为由定义，它必须返回一个对象从同一类作为其参数，和show，因为它声称作为其提供给一个对象的完整描述参数。
参数：genericFunction
Don't use; for (possible) internal use only.
不要使用（可能）仅供内部使用。
参数：knownMembers
(For setGroupGeneric only.) The names of functions that are known to be members of this group. This information is used to reset cached definitions of the member generics when information about the group generic is changed.
（setGroupGeneric只），被称为是该组的成员函数的名称。重置缓存定义的成员泛型组通用的信息改变时，使用此信息。
值----------Value----------
The setGeneric function exists for its side effect: saving the generic function to allow methods to be specified later. It returns name.
setGeneric函数存在的副作用：拯救通用的功能，允许指定的方法。它返回name。
基本使用----------Basic Use----------
The setGeneric function is called to initialize a generic function as preparation for defining some methods for that function.
被称为setGeneric函数初始化为一个泛型函数，该函数定义的一些方法做准备。
The simplest and most common situation is that name is already an ordinary non-generic non-primitive function, and you now want to turn this function into a generic. In this case you will most often supply only name, for example:
最简单和最常见的情况是name已经是一个普通的非泛型非原始的功能，你现在想变成一个通用的功能。在这种情况下，你会最经常只提供name，例如：
setGeneric("colSums")
setGeneric("colSums")
There must be an existing function of this name, on some attached package (in this case package "base"). A generic version of this function will be created in the current package (or in the global environment if the call to setGeneric() is from an ordinary source file or is entered on the command line). The existing function becomes the default method, and the package slot of the new generic function is set to the location of the original function ("base" in the example). It's an important feature that the same generic function definition is created each time, depending in the example only on the definition of print and where it is found. The signature of the generic function, defining which of the formal arguments can be used in specifying methods, is set by default to all the formal arguments except ....
必须有这个名字的现有功能，在一些附加的包（在这种情况下，包"base"）。此功能的一个通用版本将创建在当前包（或在全球环境中，如果调用setGeneric()是从一个普通的源文件或在命令行上输入）。现有的功能，成为默认的方法，新的通用功能的包槽设置的原有功能的位置（"base"中的例子）。这是一个重要的功能相同的通用函数定义被创建，例如在每次仅依赖于print发现的定义。 signature的通用功能，定义的形式参数可用于在指定的方法，是默认设置以外的所有形式参数....
Note that calling setGeneric() in this form is not strictly necessary before calling setMethod() for the same function. If the function specified in the call to setMethod is not generic, setMethod will execute the call to setGeneric itself. Declaring explicitly that you want the function to be generic can be considered better programming style; the only difference in the result, however, is that not doing so produces a message noting the creation of the generic function.
需要注意的是调用setGeneric()在这种形式是不是之前调用setMethod()相同的功能绝对必要的。如果调用setMethod在指定的函数是不是通用的，setMethod会setGeneric本身执行的调用。声明明确指出你想要的功能是通用的，可以被认为是更好的编程风格;然而，唯一的区别，结果是，不这样做，产生一个消息，指出创建泛型函数。
You cannot (and never need to) create an explicit generic version of the primitive functions in the base package. Those which can be treated as generic functions have methods selected and dispatched from the internal C code, to satisfy concerns for efficiency, and the others cannot be made generic. See the section on Primitive Functions below.
你不能（永远需要）创建一个明确的基础包的原始功能的通用版本。那些通用功能，可作为治疗的选择和内部的C代码派出的方法，以满足对效率的关注，和其他人无法进行仿制。看到在下面的原始函数一节。
The description above is the effect when the package that owns the non-generic function has not created an implicit generic version. Otherwise, it is this implicit generic function that is used. See the section on Implicit Generic Functions below. Either way, the essential result is that the same version of the generic function will be created each time.
上面的描述是包时，拥有的非通用功能尚未建立一个隐含的仿制版本的影响。否则，它是用于这种隐含的通用功能。看到隐通用功能部分。无论哪种方式，重要的结果是同一版本的通用功能，将创建每次。
The second common use of setGeneric() is to create a new generic function, unrelated to any existing function, and frequently having no default method. In this case, you need to supply a skeleton of the function definition, to define the arguments for the function. The body of a generic function is usually a standard form, standardGeneric(name) where name is the quoted name of the generic function. When calling setGeneric in this form, you would normally supply the def argument as a function of this form. See the second and third examples below.
第二setGeneric()共同使用是创建一个新的通用功能，无关的任何现有的功能，并经常有没有默认的方法。在这种情况下，你需要提供一个骨架的功能定义，定义为函数的参数。一个泛型函数的主体通常是一个标准的形式，standardGeneric(name)name是泛型函数的引用名称。当调用setGeneric在这种形式中，你通常会提供这种形式的函数def参数。看到下面的第二个和第三个例子。
The useAsDefault argument controls the default method for the new generic. If not told otherwise, setGeneric will try to find a non-generic version of the function to use as a default. So, if you do have a suitable default method, it is often simpler to first set this up as a non-generic function, and then use the one-argument call to setGeneric at the beginning of this section. See the first example in the Examples section below.
useAsDefault参数控制默认为新的通用方法。如果不告诉，否则，setGeneric会尝试找到一个非泛型版本的功能作为默认使用。所以，如果你有一个合适的默认方法，它往往是简单，首先设置作为一个非泛型函数，然后使用一个参数调用，在本节开始setGeneric。下面的示例“部分中看到的第一个例子。
If you don't want the existing function to be taken as default, supply the argument useAsDefault. That argument can be the function you want to be the default method, or FALSE to force no default (i.e., to cause an error if there is no direct or inherited method selected for a call to the function).
如果你不想采取默认现有的功能，提供的参数useAsDefault。这样的说法可以成为你想成为默认的方法，或FALSE迫使没有默认值（即导致错误，如果没有直接或继承的方法，调用函数选择）的功能。
Details
详情----------Details----------
If you want to change the behavior of an existing function (typically, one in another package) when you create a generic version, you must supply arguments to setGeneric correspondingly. Whatever changes are made, the new generic function will be assigned with a package slot set to the current package, not the one in which the non-generic version of the function is found. This step is required because the version you are creating is no longer the same as that implied by the function in the other package. A message will be printed to indicate that this has taken place and noting one of the differences between the two functions.
如果你想改变现有的功能（通常，在一个又一个的包）当你创建一个通用版本的行为，您必须提供的setGeneric相应的参数。任何变化，新的通用功能将被分配设置当前包，而不是在非泛型版本的功能是发现了一个包槽。这一步是必需的，因为您正在创建的版本已不再是暗示，在其他包的功能相同。将打印一条消息表明，这已经发生，并指出这两个函数之间的差异之一。
The body of a generic function usually does nothing except for dispatching methods by a call to standardGeneric. Under some circumstances you might just want to do some additional computation in the generic function itself. As long as your function eventually calls standardGeneric that is permissible (though perhaps not a good idea, in that it may make the behavior of your function less easy to understand). If your explicit definition of the generic function does not call standardGeneric you are in trouble, because none of the methods for the function will ever be dispatched.
一个泛型函数体通常除了为调用standardGeneric由调度方法一无所知。在某些情况下，你可能只想做一些额外的计算，在泛型函数本身。只要你的函数最终会调用standardGeneric是允许（但也许不是一个好主意，因为它可能使你的函数的行为不太容易理解）。如果您明确定义的通用功能，不叫standardGeneric你有麻烦了，因为没有人会被派遣函数的方法。
By default, the generic function can return any object. If valueClass is supplied, it should be a vector of class names; the value returned by a method is then required to satisfy is(object, Class) for one of the specified classes. An empty (i.e., zero length) vector of classes means anything is allowed. Note that more complicated requirements on the result can be specified explicitly, by defining a non-standard generic function.
默认情况下，通用的函数可以返回任何对象。如果valueClass提供，它应该是一个向量类名，方法返回的值，然后需要满足指定的类之一is(object, Class)。空（即长度为零）类的向量，是指任何被允许的。请注意结果更复杂的要求，可以明确指定，定义非标准的通用功能。
The setGroupGeneric function behaves like setGeneric except that it constructs a group generic function, differing in two ways from an ordinary generic function. First, this function cannot be called directly, and the body of the function created will contain a stop call with this information. Second, the group generic function contains information about the known members of the group, used to keep the members up to date when the group definition changes, through changes in the search list or direct specification of methods, etc.
setGroupGeneric函数的行为就像setGeneric除了它构造一组通用的功能，在两种方式从一个普通的通用功能的不同。首先，这个函数不能被直接调用，创建函数体将包含此信息的一站式呼叫。二，组通用功能包含保持成员组定义的变化时，迄今，已知组的成员，通过在搜索列表或直接规范的变化，方法等信息
隐式通用功能----------Implicit Generic Functions----------
Saying that a non-generic function “is converted to a generic” is more precisely state that the function is converted to the corresponding implicit generic function. If no special action has been taken, any function corresponds implicitly to a generic function with the same arguments, in which all arguments other than ... can be used. The signature of this generic function is the vector of formal arguments, in order, except for ....
说，非通用功能“被转换为一个通用的”，是更精确的状态，该函数被转换成相应的隐式通用功能。如果没有特殊的已采取行动，任何功能对应隐含一个泛型函数具有相同的参数，其中以外的所有参数...可以使用。这个泛型函数的签名是向量形式参数，以便，除....
The source code for a package can define an implicit generic function version of any function in that package (see implicitGeneric for the mechanism). You can not, generally, define an implicit generic function in someone else's package. The usual reason for defining an implicit generic is to prevent certain arguments from appearing in the signature, which you must do if you want the arguments to be used literally or if you want to enforce lazy evaluation for any reason. An implicit generic can also contain some methods that you want to be predefined; in fact, the implicit generic can be any generic version of the non-generic function. The implicit generic mechanism can also be used to prohibit a generic version (see prohibitGeneric).
可以定义为一个包的源代码包（见机制implicitGeneric）隐含的通用功能版本的任何功能。一般，你不能在别人的包定义隐含的通用功能。定义一个隐含的通用通常的原因是为了防止某些参数出现在签名中，你必须做，如果你想用文字，或者如果你想以任何理由强制执行懒惰的评价参数。一个隐含的通用，也可以包含一些方法，你想成为预定;事实上，隐式通用可以是任何非通用功能的通用版本。隐式的通用机制也可以用来禁止一个通用版本（见prohibitGeneric）。
Whether defined or inferred automatically, the implicit generic will be compared with the generic function that setGeneric creates, when the implicit generic is in another package. If the two functions are identical, then the package slot of the created generic will have the name of the package containing the implicit generic. Otherwise, the slot will be the name of the package in which the generic is assigned.
是否自动定义或推断，隐通用将与通用功能，setGeneric创建，时隐通用在另一个包。如果这两个函数是相同的，然后package创建通用的插槽将有包包含隐式通用名称。否则，该插槽将包中的通用分配的名称。
The purpose of this rule is to ensure that all methods defined for a particular combination of generic function and package names correspond to a single, consistent version of the generic function. Calling setGeneric with only name and possibly package as arguments guarantees getting the implicit generic version, if one exists.
这一规则的目的是为了确保一个泛型函数和包名的特定组合中定义的所有方法对应一个单一的，一致的版本的通用功能。调用setGeneric只name可能package作为参数保证，如果存在隐含的通用版本。
Including any of the other arguments can force a new, local version of the generic function. If you don't want to create a new version, don't use the extra arguments.
包括任何其他参数，可以强制一个新的本地版本的通用功能。如果你不想创建一个新的版本，不使用额外的参数。
泛型函数和原始功能----------Generic Functions and Primitive Functions----------
A number of the basic R functions are specially implemented as primitive functions, to be evaluated directly in the underlying C code rather than by evaluating an R language definition. Most have implicit generics (see implicitGeneric), and become generic as soon as methods (including group methods) are defined on them. Others cannot be made generic.
特别是实施作为原始功能，在底层的C代码，而不是直接进行评估，通过评估R语言定义一些基本的R函数。最有隐泛型（见implicitGeneric），并尽快成为通用方法（包括组方法）上定义。别人不能通用的。
Even when methods are defined for such functions, the generic version is not visible on the search list, in order that the C version continues to be called. Method selection will be initiated in the C code. Note, however, that the result is to restrict methods for primitive functions to signatures in which at least one of the classes in the signature is a formal S4 class.
即使在方法定义等功能，通用的版本是不是在搜索列表中可见，为了继续被称为C版本。在C代码中，方法的选择，将启动。但是请注意，这个结果是限制签名签名类，其中至少有一个是一个正式的S4类的原始功能的方法。
To see the generic version of a primitive function, use getGeneric(name). The function isGeneric will tell you whether methods are defined for the function in the current session.
看到通用版本的原始功能，使用getGeneric(name)。函数isGeneric会告诉你是否在本届会议的功能定义方法。
Note that S4 methods can only be set on those primitives which are "internal generic", plus %*%.
注意S4方法只能对这些原语是“内部通用的，加上%*%。
参考文献----------References----------
Software for Data Analysis: Programming with R Springer. (For the R version.)
Programming with Data Springer (For the original S4 version.)
参见----------See Also----------
Methods and the links there for a general discussion, dotsMethods for methods that dispatch on “...”, and setMethod for method definitions.
Methods“有联系，进行了一般性讨论dotsMethods派遣”的方法......“，setMethod方法定义。
举例----------Examples----------
## create a new generic function, with a default method[＃创建一个新的通用功能，默认方法]
props <- function(object) attributes(object)
setGeneric("props")
## A new generic function with no default method[＃一个新的通用功能没有默认方法]
setGeneric("increment",
function(object, step, ...)
standardGeneric("increment")
)
### A non-standard generic function. It insists that the methods[＃一个非标准的通用功能。它坚持认为，这些方法]
### return a non-empty character vector (a stronger requirement than[＃返回一个非空字符向量（更强的要求比]
### valueClass = "character" in the call to setGeneric)[＃valueClass =“字符”在呼叫setGeneric）]
setGeneric("authorNames",
function(text) {
value <- standardGeneric("authorNames")
if(!(is(value, "character") && any(nchar(value)>0)))
stop("authorNames methods must return non-empty strings")
value
})
## An example of group generic methods, using the class[＃一个例子组通用的方法，使用类]
## "track"; see the documentation of \link{setClass} for its definition[＃“跟踪”，见\ {setClass}其定义的链接文件]
## define a method for the Arith group[＃定义为Arith组方法]
setMethod("Arith", c("track", "numeric"),
function(e1, e2) {
e1@y <- callGeneric(e1@y , e2)
e1
})
setMethod("Arith", c("numeric", "track"),
function(e1, e2) {
e2@y <- callGeneric(e1, e2@y)
e2
})
## now arithmetic operators will dispatch methods:[＃现在的算术运算符将派遣方法：]
t1 <- new("track", x=1:10, y=sort(stats::rnorm(10)))
t1 - 100
1/t1
转载请注明:出自 生物统计家园网(http://www.biostatistic.net)。
注：
注1：为了方便大家学习，本文档为生物统计家园网机器人LoveR翻译而成，仅供个人R语言学习参考使用，生物统计家园保留版权。
注2：由于是机器人自动翻译，难免有不准确之处，使用时仔细对照中、英文内容进行反复理解，可以帮助R语言的学习。
注3：如遇到不准确之处，请在本贴的后面进行回帖，我们会逐渐进行修订。
|
发表于 2012-2-16 18:10:58
