Evaluate an R expression and captures the output.

captureOutput(expr, file=NULL, append=FALSE, collapse=NULL, envir=parent.frame())

Arguments

expr

The R expression to be evaluated.

file

A file name or a connection to where the output is directed. Alternatively, if NULL the output is captured to and returned as a character vector.

append

If TRUE, the output is appended to the file or the (unopened) connection, otherwise it overwrites.

collapse

A character string used for collapsing the captured rows. If NULL, the rows are not collapsed.

envir

The environment in which the expression is evaluated.

Value

Returns captured output as a character vector.

Details

This method imitates capture.output with the major difference that it captures strings via a raw connection rather than via internal strings. The latter becomes exponentially slow for large outputs [1,2].

Author

Henrik Bengtsson

See also

Internally, eval() is used to evaluate the expression. and capture.output to capture the output.

References

[1] R-devel thread 'capture.output(): Using a rawConnection() [linear] instead of textConnection() [exponential]?', 2014-02-04. https://stat.ethz.ch/pipermail/r-devel/2014-February/068349.html [2] JottR blog post 'PERFORMANCE: captureOutput() is much faster than capture.output()', 2015-05-26. https://www.jottr.org/2014/05/26/captureoutput/

Examples

# captureOutput() is much faster than capture.output()
# for large outputs when capturing to a string.
for (n in c(10e3, 20e3, 30e3, 40e3)) {
  printf("n=%d\n", n)

  x <- rnorm(n)

  t0 <- system.time({
    bfr0 <- capture.output(print(x))
  })
  print(t0)

  t1 <- system.time({
    bfr <- captureOutput(print(x))
  })
  print(t1)
  print(t1/t0)

  bfr2n <- captureOutput(print(x), collapse="\n")
  bfr2r <- captureOutput(print(x), collapse="\r")

  stopifnot(identical(bfr, bfr0))
} # for (n ...)
#> n=10000
#>    user  system elapsed 
#>   0.016   0.000   0.016 
#>    user  system elapsed 
#>   0.005   0.000   0.006 
#>    user  system elapsed 
#>  0.3125     NaN  0.3750 
#> n=20000
#>    user  system elapsed 
#>   0.062   0.001   0.063 
#>    user  system elapsed 
#>   0.010   0.000   0.011 
#>      user    system   elapsed 
#> 0.1612903 0.0000000 0.1746032 
#> n=30000
#>    user  system elapsed 
#>   0.112   0.001   0.113 
#>    user  system elapsed 
#>   0.014   0.000   0.014 
#>      user    system   elapsed 
#> 0.1250000 0.0000000 0.1238938 
#> n=40000
#>    user  system elapsed 
#>   0.187   0.002   0.190 
#>    user  system elapsed 
#>   0.019   0.000   0.019 
#>      user    system   elapsed 
#> 0.1016043 0.0000000 0.1000000