\name{setExternalStorageClass}
\alias{setExternalStorageClass}
\title{ Create subclass of externalStorage }
\description{
  Function to create a subclass of "externalStorage" and associate
  native C methods with the class.
}
\usage{
setExternalStorageClass(Class, methodNames, \dots, contains = "externalStorage", where = topenv(parent.frame()))
}
\arguments{
  \item{Class}{ Character string, name for the class. }
  \item{methodNames}{ Character vector, names of the native C
    functions for use as methods (see Adding Native Methods below). }
  \item{\dots}{ Other arguments passed to \code{setClass}. }
  \item{contains}{ what classes does this class extend?  (These are called
    superclasses in some languages.) Should have at least one class
    name which is a subclass of "externalStorage". }
  \item{where}{ The environment in which to
    store or remove the definition.  Defaults to the top-level
    environment of the calling function (the global environment
    for ordinary computations, but the environment or namespace
    of a package when loading that package). }
}
\details{
  This function does two things. It creates a subclass of
  "externalStorage". It also associates a set of given C methods as
  native methods for this subclass of "externalStorage".
}
\section{Adding Native Methods}{
  To make the external vectors as efficient as possible, the interface
  between the storage method classes and the
  "externalVectorWithSTorage" class uses a set of C function pointers
  for each subclass of "externalStorage". There are two types of
  methods - those which are for a particular type of vector and those
  which are not for a particular type. For a type \code{xxx} where
  \code{xxx} is one of \code{logical}, \code{integer}, \code{numeric},
  \code{complex} or \code{character}, the type specific functions are
  \tabular{ll}{
    xxxGetElt \tab get an element from vector of type xxx\cr
    xxxSetElt \tab set an element in a vector of type xxx\cr
    xxxSubset \tab subset a vector of type xxx\cr
    xxxSubassign \tab subassign a vector of type xxx\cr
    xxxGetMatrixElt \tab get an element from matrix of type xxx\cr
    xxxSetMatrixElt \tab set an element in a matrix of type xxx\cr
    xxxMatrixSubset \tab subset a matrix of type xxx\cr
    xxxMatrixSubassign \tab subassign a matrix of type xxx\cr
  }
  The functions not specific to any type are
  \tabular{ll}{
    alloc \tab allocate a new storage object\cr
    size \tab return the length of the vector in the storage object\cr
    resize \tab modify the length of the vector in the storage object\cr
  }
  The subset and subassign functions for vectors and matrices have
  reasonable default implementations in terms of the element get/set functions
  - so they need not be implemented for each "externalStorage" subclass.
  
  The \code{methodNames} argument to \code{setExternalStorageClass}
  must be used to register any C function for use as a particular
  method. This argument must be a character vector with elements of the
  form \code{methodName=functionName} where \code{methodName} is one of
  the method names given in the tables above and function name is a C
  function name which has been registered as a C function with R using
  the foreign function registration mechanism. See the chapter on
  \dQuote{System and foreign language interfaces} in
  \dQuote{Writing \R Extensions} in the \file{doc/manual}
  subdirectory of the \R source tree for more details on registering C
  functions.
}
\seealso{ \code{\link[methods]{setClass}} for possible arguments in \dots.
  \code{\link{externalStorage-class}} for the "externalStorage" class.
}
\examples{
\dontrun{
setExternalStorageClass("simpleStorage", c(logicalGetElt="simpleLogicalGetElt",
                                           logicalSetElt="simpleLogicalSetElt",
                                           numericGetElt="simpleNumericGetElt",
                                           numericSetElt="simpleNumericSetElt",
                                           size="simpleSize",
                                           resize="simpleResize"
                                           alloc="simpleAlloc"),
                        contains = "externalStorage")
}
}
\keyword{classes}
\keyword{programming}