#' dotCall64 - Extended Foreign Function Interface
#' 
#' \code{.C64} is a function to make calls to compiled code that has been loaded into R.
#' The function works similar to the ones of the Foreign Function Interface but it
#' \enumerate{
#'    \item supports long vectors.
#'    \item supports int64_t as argument for compiled code.
#'    \item duplicates objects if necessary to not corrupt another variable.
#'    \item casts objects to the expected argument.
#' }
#' This is achieved by the two addional arguments \code{INTENT} and \code{SIGNATURE}.
#' They describe how the arguments will be used.
#' dotCall64 will uses this information to prepare the arguments.
#' The user just has to describe its intentions and the package will do the actual work.
#' 
#' @param name a character string giving the name of a C function or Fortran subroutine. 
#' @param ... arguments to be passed to the foreign function. Up to 65.
#' @param INTENT a vector of type character. For each argument, the string indicates the intent of the function.
#' The accepted values are \code{"r"}, \code{"w" }or \code{"rw"} for indicating read, write respectively read/write.
#' Additionally, the modifiers speed \code{"s"} and copy \code{"c"} can be added.
#' If this argument is missing, it is assumed that all arguments are \code{"rw"}.
#' See details.
#' @param SIGNATURE a vector of type character.
#' It describes the signature of the C/Fortran function.
#' It accepts \code{"double"}, \code{"integer"}, \code{"int64"}.
#' @param PACKAGE if supplied, confine the search for a character string .NAME to the DLL given by this argument (plus the conventional extension, '.so', '.dll', ...).
#' This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols, and also speeds up the search (see 'Note').
#' 
#' @return A list similar to the \code{...} list of arguments passed in (including any names given to the arguments), but reflecting any changes made by the C or Fortran code.
#' 
#' @details
#' DotCall64 prioritizes memory efficiency over speed.
#' If we have an argument of signature \code{int64_t} and intent \code{"r"}, 
#' then before calling the function, \code{dotCall64} casts the double array in place 
#' (meaning it overwrites the memory of the double object) into \code{int64_t} and casts them back after the call, such that the original object is still readable.
#' If the modifier speed is set, then instead of reusing the memory, it allocates new memory and casts the values into this new memory.
#' After the call, it just discards the memory as there is no need to cast it back.
#' 
#' @section Warning:
#' If intent is set to \code{"w"}, then the function \emph{must not} assume that the elements are initialized to zero.
#' If this should be the case, use \code{"rw"} and pass a zero initialized vector.
#' 
#' @examples
#' \dontrun{
#' TODO: Demo aus Paper nehmen
#' }
#' 
#' 
#' @useDynLib dotCall64
#' @export
#' @name dotCall64
.C64 <- function(name, SIGNATURE, ..., INTENT=NULL, PACKAGE = "") {
  .External("dC64",  name, SIGNATURE=SIGNATURE, ..., INTENT=INTENT, f.PACKAGE=PACKAGE)
    }
#.External("dC64",  name, SIGNATURE=SIGNATURE, ..., INTENT=INTENT, f.PACKAGE=PACKAGE, PACKAGE="dotCall64")