Commit bf557238 authored by Florian Gerber's avatar Florian Gerber

spell check

parent 594bfea2
Package: dotCall64
Type: Package
Title: Enhanced Foreign Function Interface Supporting Long Vectors
Version: 0.9-5
Date: 2017-12-12
Version: 0.9-5.2
Date: 2018-01-08
Authors@R: c(person("Kaspar", "Moesinger", role = c("aut"),
email = "kaspar.moesinger@gmail.com"),
person("Florian", "Gerber", role = c("cre", "ctb"),
......@@ -11,7 +11,7 @@ Authors@R: c(person("Kaspar", "Moesinger", role = c("aut"),
email = "reinhard.furrer@math.uzh.ch"))
Description: An alternative version of .C() and .Fortran() supporting long
vectors and 64-bit integer type arguments. The provided interface .C64()
features mechanisms the avoid unnecessary copies of read-only or write-only
features mechanisms to avoid unnecessary copies of read-only or write-only
arguments. This makes it a convenient and fast interface to C/C++ and Fortran
code.
License: GPL (>= 2)
......
#' dotCall64 - Extended Foreign Function Interface
#'
#' \code{.C64} can be used to call compiled and loaded C functions and Fortran subroutines.
#' It works similar to \code{\link{.C}} and \code{\link{.Fortran}}, and
#' \code{.C64} is similar to \code{\link{.C}} and \code{\link{.Fortran}}, but
#' \enumerate{
#' \item supports long vectors, i.e., vectors with more than \code{2^31-1} elements,
#' \item does the necessary castings to expose the R representation of "64-bit integers" (numeric vectors)
......@@ -11,15 +11,16 @@
#' }
#' Compared to \code{\link{.C}}, \code{.C64} has the additional arguments \code{SIGNATURE}, \code{INTENT} and \code{VERBOSE}.
#' \code{SIGNATURE} specifies the types of the arguments of the compiled function.
#' \code{INTENT} indicates whether the compiled function "reads", "writes", or "read and writes" the R objects passed
#' to the compiled function. This is then used to duplicates R objects if (and only if) necessary.
#' \code{INTENT} indicates whether the compiled function "reads", "writes",
#' or "read and writes" to the R objects passed to the compiled function.
#' This is then used to duplicate R objects if (and only if) necessary.
#'
#' @param .NAME a character vector of length 1. Specifies the name of the compiled function to be called.
#' @param SIGNATURE a character vector of the same length as the number of arguments of the compiled function.
#' @param .NAME character vector of length 1. Name of the compiled function to be called.
#' @param SIGNATURE character vector of the same length as the number of arguments of the compiled function.
#' Accepted strings are \code{"double"}, \code{"integer"}, \code{"int64"} describing the signature
#' of each argument of the compiled function.
#' @param ... arguments passed to the compiled function. One R object for each argument. Up to 65 arguments are supported.
#' @param INTENT a character vector of the same length as the number of arguments of the compiled code.
#' @param INTENT character vector of the same length as the number of arguments of the compiled code.
#' Accepted strings are \code{"rw"}, \code{"r"} or \code{"w"} indicating
#' whether the intent of the argument is "read and write", "read", or "write", respectively.
#' If the INTENT of an argument is \code{"rw"}, the R object is copied and the
......@@ -42,14 +43,13 @@
#' This is intended to add safety for packages,
#' which can use this argument to ensure that no other package can override their external symbols,
#' and also speeds up the search.
#' @param VERBOSE Numeric vector of length 1. If \code{0}, no warnings are printed.
#' @param VERBOSE numeric vector of length 1. If \code{0}, no warnings are printed.
#' If \code{1} warnings are printed (which may help to improve the performance of the call),
#' If \code{2} additional debug information is given as warnings.
#' The default value can be changed via the \code{dotCall64.verbose} option, which is set to \code{0} by default.
#'
#' @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 compiled C or Fortran code.
#' @return list of R objects similar to the list of arguments specified as \code{...} arguments.
#' The objects of the list reflect the changes made by the compiled C or Fortran code.
#'
#' @references
#' F. Gerber, K. Moesinger, and R. Furrer (2017),
......@@ -79,23 +79,24 @@
#' .C64("get_c", SIGNATURE = c("double", "integer", "double"),
#' input = x_long, index = 9, output = double(1))$output
#'
#' ## Since 'index' is of type 'signed int' resulting in a 32-bit integer,
#' ## it can only capture integers op to 2^31-1. To extend this,
#' ## we define the C function as follows:
#' ## #include <stdint.h> // defines the int64_t type
#' ## Since 'index' is of type 'signed int' (a 32-bit integer),
#' ## it can only address vector having up to 2^31-1 elements.
#' ## To also address elements beyond 2^31-1, we change the
#' ## definition of the C function as follows:
#' ## #include <stdint.h> // for int64_t
#' ## void get64_c(double *input, int64_t *index, double *output) {
#' ## output[0] = input[index[0] - 1];
#' ## }
#'
#' ## We can use .C64() to call the function from R.
#' ## Now, we can use .C64() to call the function from R.
#' .C64("get64_c", SIGNATURE = c("double", "int64", "double"),
#' input = x_long, index = 2^31, output = double(1))$output
#'
#' ## Note that .C64() takes 2^31 as double and casts it to int64_t
#' ## before calling the C function get64_c().
#' ## Note that 2^31 is of type double and .C64() casts it to a
#' ## int64_t type before calling the C function get64_c().
#'
#' ## The performance of the previous call can be improved with
#' ## additional options:
#' ## The performance of the previous call can be improved by
#' ## setting additional arguements:
#' .C64("get64_c", SIGNATURE = c("double", "int64", "double"),
#' x = x_long, i = 2^31, r = numeric_dc(1), INTENT = c("r", "r", "w"),
#' NAOK = TRUE, PACKAGE = "dotCall64", VERBOSE = 0)$r
......
......@@ -2,15 +2,15 @@
#'
#' Helper functions to be used in calls to \code{\link{.C64}}.
#' The function \code{vector_dc} and its shortcuts \code{numeric_dc} and
#' \code{integer_dc} return a R object of class \code{c("vector_dc", "list")}
#' \code{integer_dc} return an R object of class \code{c("vector_dc", "list")}
#' containing the necessary information (type and length) to allocate the
#' vector (initialized with 0) inside the call to \code{\link{.C64}}.
#' Using \code{vector_dc} together with \code{INTENT = "w"} argument of \code{\link{.C64}}
#' leads to performance gains by avoiding unnecessary castings and copies.
#'
#' @param mode Character vector of length 1. Storage mode of the vector to allocate.
#' @param length Numeric vector of length 1. Length of the vector to allocate.
#' @return Object of class \code{vector_dc} and \code{list}.
#' @param mode character vector of length 1. Storage mode of the vector.
#' @param length numeric vector of length 1. Length of the vector.
#' @return object of class \code{vector_dc} and \code{list}.
#' @name vector_dc
#' @rdname vector_dc
#' @examples
......
......@@ -9,15 +9,15 @@
VERBOSE = getOption("dotCall64.verbose"))
}
\arguments{
\item{.NAME}{a character vector of length 1. Specifies the name of the compiled function to be called.}
\item{.NAME}{character vector of length 1. Name of the compiled function to be called.}
\item{SIGNATURE}{a character vector of the same length as the number of arguments of the compiled function.
\item{SIGNATURE}{character vector of the same length as the number of arguments of the compiled function.
Accepted strings are \code{"double"}, \code{"integer"}, \code{"int64"} describing the signature
of each argument of the compiled function.}
\item{...}{arguments passed to the compiled function. One R object for each argument. Up to 65 arguments are supported.}
\item{INTENT}{a character vector of the same length as the number of arguments of the compiled code.
\item{INTENT}{character vector of the same length as the number of arguments of the compiled code.
Accepted strings are \code{"rw"}, \code{"r"} or \code{"w"} indicating
whether the intent of the argument is "read and write", "read", or "write", respectively.
If the INTENT of an argument is \code{"rw"}, the R object is copied and the
......@@ -43,19 +43,18 @@ This is intended to add safety for packages,
which can use this argument to ensure that no other package can override their external symbols,
and also speeds up the search.}
\item{VERBOSE}{Numeric vector of length 1. If \code{0}, no warnings are printed.
\item{VERBOSE}{numeric vector of length 1. If \code{0}, no warnings are printed.
If \code{1} warnings are printed (which may help to improve the performance of the call),
If \code{2} additional debug information is given as warnings.
The default value can be changed via the \code{dotCall64.verbose} option, which is set to \code{0} by default.}
}
\value{
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 compiled C or Fortran code.
list of R objects similar to the list of arguments specified as \code{...} arguments.
The objects of the list reflect the changes made by the compiled C or Fortran code.
}
\description{
\code{.C64} can be used to call compiled and loaded C functions and Fortran subroutines.
It works similar to \code{\link{.C}} and \code{\link{.Fortran}}, and
\code{.C64} is similar to \code{\link{.C}} and \code{\link{.Fortran}}, but
\enumerate{
\item supports long vectors, i.e., vectors with more than \code{2^31-1} elements,
\item does the necessary castings to expose the R representation of "64-bit integers" (numeric vectors)
......@@ -65,8 +64,9 @@ to 64-bit integers arguments of the compiled function; int64_t types in C and in
}
Compared to \code{\link{.C}}, \code{.C64} has the additional arguments \code{SIGNATURE}, \code{INTENT} and \code{VERBOSE}.
\code{SIGNATURE} specifies the types of the arguments of the compiled function.
\code{INTENT} indicates whether the compiled function "reads", "writes", or "read and writes" the R objects passed
to the compiled function. This is then used to duplicates R objects if (and only if) necessary.
\code{INTENT} indicates whether the compiled function "reads", "writes",
or "read and writes" to the R objects passed to the compiled function.
This is then used to duplicate R objects if (and only if) necessary.
}
\examples{
## Consider the following C function, which is included
......@@ -86,23 +86,24 @@ x_long[9] <- 9; x_long[2^31] <- -1
.C64("get_c", SIGNATURE = c("double", "integer", "double"),
input = x_long, index = 9, output = double(1))$output
## Since 'index' is of type 'signed int' resulting in a 32-bit integer,
## it can only capture integers op to 2^31-1. To extend this,
## we define the C function as follows:
## #include <stdint.h> // defines the int64_t type
## Since 'index' is of type 'signed int' (a 32-bit integer),
## it can only address vector having up to 2^31-1 elements.
## To also address elements beyond 2^31-1, we change the
## definition of the C function as follows:
## #include <stdint.h> // for int64_t
## void get64_c(double *input, int64_t *index, double *output) {
## output[0] = input[index[0] - 1];
## }
## We can use .C64() to call the function from R.
## Now, we can use .C64() to call the function from R.
.C64("get64_c", SIGNATURE = c("double", "int64", "double"),
input = x_long, index = 2^31, output = double(1))$output
## Note that .C64() takes 2^31 as double and casts it to int64_t
## before calling the C function get64_c().
## Note that 2^31 is of type double and .C64() casts it to a
## int64_t type before calling the C function get64_c().
## The performance of the previous call can be improved with
## additional options:
## The performance of the previous call can be improved by
## setting additional arguements:
.C64("get64_c", SIGNATURE = c("double", "int64", "double"),
x = x_long, i = 2^31, r = numeric_dc(1), INTENT = c("r", "r", "w"),
NAOK = TRUE, PACKAGE = "dotCall64", VERBOSE = 0)$r
......
......@@ -13,17 +13,17 @@ numeric_dc(length = 0)
integer_dc(length = 0)
}
\arguments{
\item{mode}{Character vector of length 1. Storage mode of the vector to allocate.}
\item{mode}{character vector of length 1. Storage mode of the vector.}
\item{length}{Numeric vector of length 1. Length of the vector to allocate.}
\item{length}{numeric vector of length 1. Length of the vector.}
}
\value{
Object of class \code{vector_dc} and \code{list}.
object of class \code{vector_dc} and \code{list}.
}
\description{
Helper functions to be used in calls to \code{\link{.C64}}.
The function \code{vector_dc} and its shortcuts \code{numeric_dc} and
\code{integer_dc} return a R object of class \code{c("vector_dc", "list")}
\code{integer_dc} return an R object of class \code{c("vector_dc", "list")}
containing the necessary information (type and length) to allocate the
vector (initialized with 0) inside the call to \code{\link{.C64}}.
Using \code{vector_dc} together with \code{INTENT = "w"} argument of \code{\link{.C64}}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment