quickr (version 0.2.1)

quick: Compile a Quick Function

Description

Compile an R function.

Usage

quick(fun, name = NULL)

Value

A quicker R function.

Arguments

fun

An R function

name

String, name to use for the function. This is optional in regular usage but required in an R package. As a convenience, arguments fun and name can also be supplied as positional arguments to quick with name in the first position.

Details

declare(type()) syntax:

The shape and mode of all function arguments must be declared. Local and return variables may optionally also be declared.

declare(type()) also has support for declaring size constraints, or size relationships between variables. Here are some examples of declare calls:

declare(type(x = double(NA))) # x is a 1-d double vector of any length
declare(type(x = double(10))) # x is a 1-d double vector of length 10
declare(type(x = double(1)))  # x is a scalar double
declare(type(x = integer(2, 3)))  # x is a 2-d integer matrix with dim (2, 3)
declare(type(x = integer(NA, 3))) # x is a 2-d integer matrix with dim (<any>, 3)
# x is a 4-d logical matrix with dim (<any>, 24, 24, 3)
declare(type(x = logical(NA, 24, 24, 3)))
# x and y are 1-d double vectors of any length
declare(type(x = double(NA)),
        type(y = double(NA)))
# x and y are 1-d double vectors of the same length
declare(
  type(x = double(n)),
  type(y = double(n)),
)
# x and y are 1-d double vectors, where length(y) == length(x) + 2
declare(type(x = double(n)),
        type(y = double(n+2)))

You can provide declarations to declare() as:

• Multiple arguments to a single declare() call

• Separate declare() calls

• Multiple arguments within a code block ({}) inside declare()

declare(
  type(x = double(n)),
  type(y = double(n)),
)
declare(type(x = double(n)))
declare(type(y = double(n)))
declare({
  type(x = double(n))
  type(y = double(n))
})

Return values

The shape and type of a function return value must be known at compile time. In most situations, this will be automatically inferred by quick(). However, if the output is dynamic, then you may need to provide a hint. For example, returning the result of seq() will fail because the output shape cannot be inferred.

# Will fail to compile:
quick_seq <- quick(function(start, end) {
  declare({
    type(start = integer(1))
    type(end = integer(1))
  })
  out <- seq(start, end)
  out
})

However, if the output size can be declared as a dynamic expression using other values known at runtime, compilation will succeed:

# Succeeds:
quick_seq <- quick(function(start, end) {
  declare({
    type(start = integer(1))
    type(end = integer(1))
    type(out = integer(end - start + 1))
  })
  out <- seq(start, end)
  out
})
quick_seq(1L, 5L)

Examples

# \donttest{
add_ab <- quick(function(a, b) {
  declare(type(a = double(n)),
          type(b = double(n)))
  a + b
})
add_ab(1, 2)
add_ab(c(1, 2, 3), c(4, 5, 6))
# }