help file

DESCRIPTION

@@ -9,11 +9,11 @@ Authors@R: c(person("Kaspar", "Moesinger", role = c("aut"),
     email = "florian.gerber@math.uzh.ch"),
     person("Reinhard", "Furrer", role = "ctb",
     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 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.
+Description: The package provides .C64(), which is an enhanced version of .C()
+    and .Fortran(). .C64() supports long vectors, arguments of type 64-bit
+    integer, and provides a mechanism to avoid unnecessary copies of read-only
+    and write-only arguments. This makes it a convenient and fast interface to
+    C/C++ and Fortran code.
 License: GPL (>= 2)
 URL: https://git.math.uzh.ch/reinhard.furrer/dotCall64
 BugReports: https://git.math.uzh.ch/reinhard.furrer/dotCall64/issues

R/dotCall64.R

@@ -3,17 +3,17 @@
 #' \code{.C64} can be used to call compiled and loaded C functions and Fortran subroutines.
 #' \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 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)
-#' to 64-bit integers arguments of the compiled function; int64_t types in C and integer (kind = 8) in Fortran,
-#'    \item provides a mechanism the control the duplication of the R objects exposed to the compiled code,
-#'    \item checks if the provided R objects are of the expected type and coerces the R object if necessary. 
+#' to 64-bit integers arguments of the compiled function. The latter are int64_t in C code and integer (kind = 8) in Fortran code
+#'    \item provides a mechanism the control duplication of the R objects exposed to the compiled code
+#'    \item checks if the provided R objects are of the expected types and coerces them if necessary
 #' }
 #' 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" to the R objects passed to the compiled function.
-#' This is then used to duplicate R objects if (and only if) necessary.
+#' This is then used to duplicate R objects if and only if necessary.
 #' 
 #' @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.
@@ -30,15 +30,14 @@
 #' While this avoids copying and hence is more efficient in terms of speed and memory usage,
 #' it is absolutely necessary that the compiled function does not alter the object,
 #' since this corrupts the R object in the current R session.
-#' When the intent is \code{"w"}, the corresponding input argument can be specified
+#' When the INTENT is \code{"w"}, the corresponding input argument can be specified
 #' with the function \code{\link{vector_dc}} or its shortcuts \code{\link{integer_dc}} and \code{\link{numeric_dc}}.
 #' This avoids copying the passed R objects and hence is more efficient in terms of speed and memory usage.
-#' By default, all arguments have intent \code{"rw"}.
-#' @param NAOK logical vector of length 1. If \code{FALSE} (default), the presence of \code{NA} or \code{NaN} or \code{Inf}
+#' By default, all arguments have INTENT \code{"rw"}.
+#' @param NAOK logical vector of length 1. If \code{FALSE} (default), the presence of \code{NA}, \code{NaN}, and \code{Inf}
 #' in the R objects passed through \code{...} results in an error.
-#' If \code{TRUE}, any \code{NA} or \code{NaN} or \code{Inf} values in the
-#' arguments are passed on to the compiled function.
-#' The used time to check arguments (if \code{FALSE}) maybe considerable for large vectors. 
+#' If \code{TRUE}, \code{NA}, \code{NaN}, and \code{Inf} values are passed to the compiled function.
+#' The used time to check arguments (if \code{FALSE}) is considerable for large vectors. 
 #' @param PACKAGE character vector of length 1. Specifies where to search for the function given in \code{.NAME}. 
 #' This is intended to add safety for packages,
 #' which can use this argument to ensure that no other package can override their external symbols,
@@ -80,7 +79,7 @@
 #'      input = x_long, index = 9, output = double(1))$output
 #'
 #' ## Since 'index' is of type 'signed int' (a 32-bit integer),
-#' ## it can only address vector having up to 2^31-1 elements.
+#' ## it can only address the first 2^31-1 elements of 'input'.
 #' ## To also address elements beyond 2^31-1, we change the
 #' ## definition of the C function as follows:
 #' ## #include <stdint.h>  //  for int64_t 
@@ -92,11 +91,11 @@
 #' .C64("get64_c", SIGNATURE = c("double", "int64", "double"),
 #'      input = x_long, index = 2^31, output = double(1))$output
 #'
-#' ## Note that 2^31 is of type double and .C64() casts it to a
+#' ## Note that 2^31 is of type double and .C64() casts it into an
 #' ## int64_t type before calling the C function get64_c().
 #'
 #' ## The performance of the previous call can be improved by
-#' ## setting additional arguements:
+#' ## setting additional arguments:
 #' .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
@@ -112,7 +111,6 @@
 #' ## The function is provided in dotCall64 and can be called with
 #' .C64("get64_f", SIGNATURE = c("double", "int64", "double"),
 #'      input = x_long, index = 2^31, output = double(1))$output
-#'
 #' }
 #' @useDynLib dotCall64, .registration = TRUE
 #' @export

R/vector_dc.R

 #' Allocate vectors in .C64()
 #'
-#' 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 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}}.
+#' \code{vector_dc} and its shortcuts \code{numeric_dc} and
+#' \code{integer_dc} are helper functions used in calls to \code{\link{.C64}}.
+#' They return an R object of class \code{c("vector_dc", "list")}, 
+#' which contains information on the type and length of the vector to allocate.
 #' Using \code{vector_dc} together with \code{INTENT = "w"} argument of \code{\link{.C64}}
 #' leads to performance gains by avoiding unnecessary castings and copies. 
 #'

man/dotCall64.Rd

@@ -27,16 +27,15 @@ function receives a pointer to the R object itself.
 While this avoids copying and hence is more efficient in terms of speed and memory usage,
 it is absolutely necessary that the compiled function does not alter the object,
 since this corrupts the R object in the current R session.
-When the intent is \code{"w"}, the corresponding input argument can be specified
+When the INTENT is \code{"w"}, the corresponding input argument can be specified
 with the function \code{\link{vector_dc}} or its shortcuts \code{\link{integer_dc}} and \code{\link{numeric_dc}}.
 This avoids copying the passed R objects and hence is more efficient in terms of speed and memory usage.
-By default, all arguments have intent \code{"rw"}.}
+By default, all arguments have INTENT \code{"rw"}.}
 
-\item{NAOK}{logical vector of length 1. If \code{FALSE} (default), the presence of \code{NA} or \code{NaN} or \code{Inf}
+\item{NAOK}{logical vector of length 1. If \code{FALSE} (default), the presence of \code{NA}, \code{NaN}, and \code{Inf}
 in the R objects passed through \code{...} results in an error.
-If \code{TRUE}, any \code{NA} or \code{NaN} or \code{Inf} values in the
-arguments are passed on to the compiled function.
-The used time to check arguments (if \code{FALSE}) maybe considerable for large vectors.}
+If \code{TRUE}, \code{NA}, \code{NaN}, and \code{Inf} values are passed to the compiled function.
+The used time to check arguments (if \code{FALSE}) is considerable for large vectors.}
 
 \item{PACKAGE}{character vector of length 1. Specifies where to search for the function given in \code{.NAME}. 
 This is intended to add safety for packages,
@@ -56,17 +55,17 @@ The objects of the list reflect the changes made by the compiled C or Fortran co
 \code{.C64} can be used to call compiled and loaded C functions and Fortran subroutines.
 \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 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)
-to 64-bit integers arguments of the compiled function; int64_t types in C and integer (kind = 8) in Fortran,
-   \item provides a mechanism the control the duplication of the R objects exposed to the compiled code,
-   \item checks if the provided R objects are of the expected type and coerces the R object if necessary. 
+to 64-bit integers arguments of the compiled function. The latter are int64_t in C code and integer (kind = 8) in Fortran code
+   \item provides a mechanism the control duplication of the R objects exposed to the compiled code
+   \item checks if the provided R objects are of the expected types and coerces them if necessary
 }
 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" to the R objects passed to the compiled function.
-This is then used to duplicate R objects if (and only if) necessary.
+This is then used to duplicate R objects if and only if necessary.
 }
 \examples{
 ## Consider the following C function, which is included
@@ -87,7 +86,7 @@ x_long[9] <- 9; x_long[2^31] <- -1
      input = x_long, index = 9, output = double(1))$output
 
 ## Since 'index' is of type 'signed int' (a 32-bit integer),
-## it can only address vector having up to 2^31-1 elements.
+## it can only address the first 2^31-1 elements of 'input'.
 ## To also address elements beyond 2^31-1, we change the
 ## definition of the C function as follows:
 ## #include <stdint.h>  //  for int64_t 
@@ -99,11 +98,11 @@ x_long[9] <- 9; x_long[2^31] <- -1
 .C64("get64_c", SIGNATURE = c("double", "int64", "double"),
      input = x_long, index = 2^31, output = double(1))$output
 
-## Note that 2^31 is of type double and .C64() casts it to a
+## Note that 2^31 is of type double and .C64() casts it into an
 ## int64_t type before calling the C function get64_c().
 
 ## The performance of the previous call can be improved by
-## setting additional arguements:
+## setting additional arguments:
 .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
@@ -119,7 +118,6 @@ x_long[9] <- 9; x_long[2^31] <- -1
 ## The function is provided in dotCall64 and can be called with
 .C64("get64_f", SIGNATURE = c("double", "int64", "double"),
      input = x_long, index = 2^31, output = double(1))$output
-
 }
 }
 \references{

man/vector_dc.Rd

@@ -21,11 +21,10 @@ integer_dc(length = 0)
 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 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}}.
+\code{vector_dc} and its shortcuts \code{numeric_dc} and
+\code{integer_dc} are helper functions used in calls to \code{\link{.C64}}.
+They return an R object of class \code{c("vector_dc", "list")}, 
+which contains information on the type and length of the vector to allocate.
 Using \code{vector_dc} together with \code{INTENT = "w"} argument of \code{\link{.C64}}
 leads to performance gains by avoiding unnecessary castings and copies.
 }