Package 'R.utils'

Description

Utility functions useful when programming and developing R packages.

Warning: The Application Programming Interface (API) of the classes and methods in this package may change. Classes and methods are considered either to be stable, or to be in beta or alpha (pre-beta) stage. See list below for details.

The main reason for publishing this package on CRAN although it lacks a stable API, is that its methods and classes are used internally by other packages on CRAN that the author has published.

For package history, see showHistory(R.utils).

Requirements

This package requires the R.oo package [1].

Installation and updates

To install this package do:

install.packages("R.utils")

To get started

Arguments

[alpha] Methods for common argument processing.

Assert

[alpha] Methods for assertion of values and states.

GString

[alpha] A character string class with methods for simple substitution.

Java

[beta] Reads and writes Java streams.

Options

[alpha] Tree-structured options queried in a file-system like manner.

Settings

[alpha] An Options class for reading and writing package settings.

ProgressBar

[beta] Text-based progress bar.

FileProgressBar

[beta] A ProgressBar that reports progress as file size.

System

[alpha] Methods for access to system.

Verbose

[alpha] A class for verbose and log output. Utilized by the VComments and LComments classes.

SmartComments, VComments, LComments

[alpha] Methods for preprocessing source code comments of certain formats into R code.

In addition to the above, there is a large set of function for file handling such as support for reading/following Windows Shortcut links, but also other standalone utility functions. See package index for a list of these. These should also be considered to be in alpha or beta stage.

How to cite this package

Whenever using this package, please cite [1] as

Bengtsson, H. The R.oo package - Object-Oriented Programming with References Using
Standard R Code, Proceedings of the 3rd International Workshop on Distributed
Statistical Computing (DSC 2003), ISSN 1609-395X, Hornik, K.; Leisch, F. & Zeileis,
A. (ed.), 2003

Wishlist

Here is a list of features that would be useful, but which I have too little time to add myself. Contributions are appreciated.

• Write a TclTkProgressBar class.

• Improve/stabilize the GString class.

• Mature the SmartComments classes. Also add AComments and PComments for assertion and progress/status comments.

If you consider implement some of the above, make sure it is not already implemented by downloading the latest "devel" version!

License

The releases of this package is licensed under LGPL version 2.1 or newer.

The development code of the packages is under a private licence (where applicable) and patches sent to the author fall under the latter license, but will be, if incorporated, released under the "release" license above.

References

[1] H. Bengtsson, The R.oo package - Object-Oriented Programming with References Using Standard R Code, In Kurt Hornik, Friedrich Leisch and Achim Zeileis, editors, Proceedings of the 3rd International Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, Vienna, Austria. https://www.r-project.org/conferences/DSC-2003/Proceedings/

Author(s)

Henrik Bengtsson

Description

Modifies .Last() to call 'finalizeSession() before calling the default .Last() function.

Note that .Last() is not guaranteed to be called when the R session finished. For instance, the user may quit R by calling quit(runLast=FALSE) or run R in batch mode.

Note that this function is called when the R.utils package is loaded.

Usage

## Default S3 method:
addFinalizerToLast(...)

Arguments

Value

Returns (invisibly) TRUE if .Last() was modified, otherwise FALSE.

Author(s)

Henrik Bengtsson

See Also

onSessionExit().

Description

Package: R.utils
Class Arguments

Object
~~|
~~+--Arguments

Directly known subclasses:

public static class Arguments
extends Object

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Description

Package: R.utils
Class Assert

Object
~~|
~~+--Assert

Directly known subclasses:

public static class Assert
extends Object

Usage

Assert(...)

Arguments

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Description

Assigns an objects elements locally.

Usage

## S3 method for class 'list'
attachLocally(object, fields=NULL, excludeFields=NULL, overwrite=TRUE,
  envir=parent.frame(), ...)

Arguments

Value

Returns (invisibly) a character vector of the fields copied.

Author(s)

Henrik Bengtsson

See Also

attachLocally() of class Object. attach().

Examples

foo <- function(object) {
  cat("Local objects in foo():\n")
  print(ls())

  attachLocally(object)

  cat("\nLocal objects in foo():\n")
  print(ls())

  for (name in ls()) {
    cat("\nObject '", name, "':\n", sep="")
    print(get(name, inherits=FALSE))
  }
}

a <- "A string"
l <- list(a=1:10, msg="Hello world", df=data.frame(a=NA, b=2))
foo(l)
print(a)

Description

Call hook functions by hook name.

Usage

## Default S3 method:
callHooks(hookName, ..., removeCalledHooks=FALSE)

Arguments

Value

Returns (invisibly) whatever callHooks.list() returns.

Author(s)

Henrik Bengtsson

See Also

Internally, after retrieving hook functions, callHooks.list() is called.

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 1
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# First, clean up if called more than once
setHook("myFunction.onEnter", NULL, action="replace")
setHook("myFunction.onExit", NULL, action="replace")

runConference <- function(...) {
  callHooks("myFunction.onEnter")
  cat("Speaker A: Hello there...\n")
  callHooks("myFunction.onExit")
}

setHook("myFunction.onEnter", function(...) {
  cat("Chair: Welcome to our conference.\n")
})

setHook("myFunction.onEnter", function(...) {
  cat("Chair: Please welcome Speaker A!\n")
})

setHook("myFunction.onExit", function(...) {
  cat("Chair: Please thanks Speaker A!\n")
})

runConference()


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 2
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
setHook("randomNumber", NULL, action="replace")
setHook("randomNumber", rnorm)      # By function
setHook("randomNumber", "rexp")     # By name
setHook("randomNumber", "runiff")   # Non-existing name
setHook("randomNumber", .GlobalEnv) # Not a function

res <- callHooks("randomNumber", n=1)
str(res)
cat("Number of hooks: ", length(res), "\n")
isErroneous <- unlist(lapply(res, FUN=function(x) !is.null(x$exception)))
cat("Erroneous hooks: ", sum(isErroneous), "\n")

Description

Call hook functions.

Usage

## S3 method for class 'function'
callHooks(hooks, ...)

Arguments

Value

Returns (invisibly) a list that is named with hook names, if possible. Each element in the list is in turn a list with three element: fcn is the hook function called, result is its return value, and exception is the exception caught or NULL.

Author(s)

Henrik Bengtsson

See Also

See callHooks() to call hook function by name.

Description

Capitalizes/decapitalized (making the first letter upper/lower case) of each character string in a vector.

Usage

## Default S3 method:
capitalize(str, ...)
  ## Default S3 method:
decapitalize(str, ...)

Arguments

Value

Returns a vector of character strings of the same length as the input vector.

Author(s)

Henrik Bengtsson

See Also

toCamelCase.

Examples

words <- strsplit("Hello wOrld", " ")[[1]]
cat(paste(toupper(words), collapse=" "), "\n")      # "HELLO WORLD"
cat(paste(tolower(words), collapse=" "), "\n")      # "hello world"
cat(paste(capitalize(words), collapse=" "), "\n")   # "Hello WOrld"
cat(paste(decapitalize(words), collapse=" "), "\n") # "hello wOrld"

# Sanity checks
stopifnot(paste(toupper(words), collapse=" ") == "HELLO WORLD")
stopifnot(paste(tolower(words), collapse=" ") == "hello world")
stopifnot(paste(capitalize(words), collapse=" ") == "Hello WOrld")
stopifnot(paste(decapitalize(words), collapse=" ") == "hello wOrld")

Description

Evaluate an R expression and captures the output.

Usage

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

Arguments

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].

Value

Returns captured output as a character vector.

Author(s)

Henrik Bengtsson

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/

See Also

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

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 ...)

Description

Simple access to parsed command-line arguments.

Usage

cmdArgs(args=NULL, names=NULL, unique=TRUE, ..., .args=NULL)
  cmdArg(...)

Arguments

Value

cmdArgs() returns a named list with command-line arguments. cmdArg() return the value of the requested command-line argument.

Coercing to non-character data types

The value of each command-line argument is returned as a character string, unless an argument share name with ditto in the (optional) arguments always and default in case the retrieved value is coerced to that of the latter. Finally, remaining character string command-line arguments are coerced to numerics (via as.numeric()), if possible, that is unless the coerced value becomes NA.

Author(s)

Henrik Bengtsson

See Also

Internally, commandArgs() is used.

Examples

args <- cmdArgs()
cat("User command-line arguments used when invoking R:\n")
str(args)

# Retrieve command line argument 'n', e.g. '-n 13' or '--n=13'
n <- cmdArg("n", 42L)
printf("Argument n=%d\n", n)

# Short version doing the same
n <- cmdArg(n=42L)
printf("Argument n=%d\n", n)

Description

Creates a vector of column classes used for tabular reading based on a compact format string.

Usage

## Default S3 method:
colClasses(fmt, ...)

Arguments

Value

Returns a vector of character strings.

Author(s)

Henrik Bengtsson

See Also

read.table.

Examples

# All predefined types
print(colClasses("-?cdfilnrzDP"))
## [1] "NULL"      "NA"        "character" "double"
## [5] "factor"    "integer"   "logical"   "numeric"
## [9] "raw"       "complex"   "Date"      "POSIXct"

# A string in column 1, integers in column 4 and 5, rest skipped
print(colClasses("c--ii----"))
## [1] "character" "NULL"      "NULL"      "integer"
## [5] "integer"   "NULL"      "NULL"      "NULL"
## [9] "NULL"

# Repeats and custom column classes
c1 <- colClasses("3c{MyClass}3{foo}")
print(c1)
## [1] "character" "character" "character" "MyClass"
## [5] "foo"       "foo"       "foo"

# Passing repeats and class names using sprintf() syntax
c2 <- colClasses("%dc{%s}%d{foo}", 3, "MyClass", 3)
stopifnot(identical(c1, c2))

# Repeats of a vector of column classes
c3 <- colClasses("3{MyClass,c}")
print(c3)
## [1] "MyClass"   "character" "MyClass"   "character"
## [4] "MyClass"   "character"

# Large number repeats
c4 <- colClasses("321{MyClass,c,i,d}")
c5 <- rep(c("MyClass", "character", "integer", "double"), times=321)
stopifnot(identical(c4, c5))

Description

Compressing and decompressing files such as gzip:ed and bzip2:ed files.

NOTE: The default (remove=TRUE) behavior is that the input file is removed after that the output file is fully created and closed.

Usage

## Default S3 method:
compressFile(filename, destname=sprintf("%s.%s", filename, ext), ext, FUN,
  temporary=FALSE, skip=FALSE, overwrite=FALSE, remove=TRUE, BFR.SIZE=1e+07, ...)
 ## Default S3 method:
decompressFile(filename, destname=gsub(sprintf("[.]%s$", ext), "", filename,
  ignore.case = TRUE), ext, FUN, temporary=FALSE, skip=FALSE, overwrite=FALSE,
  remove=TRUE, BFR.SIZE=1e+07, ...)
 ## Default S3 method:
isCompressedFile(filename, method=c("extension", "content"), ext, fileClass, ...)
 ## Default S3 method:
bzip2(filename, ..., ext="bz2", FUN=bzfile)
 ## Default S3 method:
bunzip2(filename, ..., ext="bz2", FUN=bzfile)
 ## Default S3 method:
gzip(filename, ..., ext="gz", FUN=gzfile)
 ## Default S3 method:
gunzip(filename, ..., ext="gz", FUN=gzfile)

Arguments

Details

Internally bzfile() and gzfile() (see connections) are used to read (write) files. If the process is interrupted before completed, the partially written output file is automatically removed.

Value

Returns the pathname of the output file. The number of bytes processed is returned as an attribute.

isCompressedFile(), isGzipped() and isBzipped() return a logical. Note that with method = "extension" (default), only the filename extension is used to infer whether the file is compressed or not. Specifically, it does not matter whether the file actually exists or not.

Author(s)

Henrik Bengtsson

Examples

## bzip2
  cat(file="foo.txt", "Hello world!")
  print(isBzipped("foo.txt"))
  print(isBzipped("foo.txt.bz2"))

  bzip2("foo.txt")
  print(file.info("foo.txt.bz2"))
  print(isBzipped("foo.txt"))
  print(isBzipped("foo.txt.bz2"))

  bunzip2("foo.txt.bz2")
  print(file.info("foo.txt"))

  ## gzip
  cat(file="foo.txt", "Hello world!")
  print(isGzipped("foo.txt"))
  print(isGzipped("foo.txt.gz"))

  gzip("foo.txt")
  print(file.info("foo.txt.gz"))
  print(isGzipped("foo.txt"))
  print(isGzipped("foo.txt.gz"))

  gunzip("foo.txt.gz")
  print(file.info("foo.txt"))

  ## Cleanup
  file.remove("foo.txt")

Description

Compresses a PDF (into a new PDF).

Usage

## Default S3 method:
compressPDF(filename, path=NULL, outFilename=basename(pathname),
  outPath="compressedPDFs", skip=FALSE, overwrite=FALSE, compression="gs(ebook)+qpdf",
  ...)

Arguments

Value

Returns the pathname of the generated PDF.

Author(s)

Henrik Bengtsson

See Also

Internally compactPDF is utilized.

Examples

## Not run: 
  pathnameZ <- compressPDF("report.pdf")

## End(Not run)

Description

Copies a directory.

Usage

## Default S3 method:
copyDirectory(from, to=".", ..., private=TRUE, recursive=TRUE)

Arguments

Details

Note that this method does not use copyFile() to copy the files, but file.copy().

Value

Returns (invisibly) a character vector of pathnames copied.

Author(s)

Henrik Bengtsson

Description

Counts the number of lines in a text file by counting the number of occurrences of platform-independent newlines (CR, LF, and CR+LF [1]), including a last line with neither. An empty file has zero lines.

Usage

## Default S3 method:
countLines(file, chunkSize=5e+07, ...)

Arguments

Details

Both compressed and non-compressed files are supported.

Value

Returns an non-negative integer.

Author(s)

Henrik Bengtsson

References

[1] Page Newline, Wikipedia, July 2008. https://en.wikipedia.org/wiki/Newline

Examples

pathname <- system.file("NEWS.md", package="R.utils");
n <- countLines(pathname);
n2 <- length(readLines(pathname));
stopifnot(n == n2);

Description

Creates a file atomically by first creating and writing to a temporary file which is then renamed.

Usage

## Default S3 method:
createFileAtomically(filename, path=NULL, FUN, ..., skip=FALSE, overwrite=FALSE,
  backup=TRUE, verbose=FALSE)

Arguments

Value

Returns (invisibly) the pathname.

Author(s)

Henrik Bengtsson

See Also

Internally, pushTemporaryFile() and popTemporaryFile() are used for working toward a temporary file, and pushBackupFile() and popBackupFile() are used for backing up and restoring already existing file.

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Create a file atomically
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
n <- 10
pathname <- createFileAtomically("foobar.txt", path=tempdir(), FUN=function(pathname) {
  cat(file=pathname, "This file was created atomically.\n")
  cat(file=pathname, "Timestamp: ", as.character(Sys.time()), "\n", sep="")
  for (kk in 1:n) {
    cat(file=pathname, kk, "\n", append=TRUE)
    # Emulate a slow process
    if (interactive()) Sys.sleep(0.1)
  }
  cat(file=pathname, "END OF FILE\n", append=TRUE)
}, overwrite=TRUE)

bfr <- readLines(pathname)
cat(bfr, sep="\n")


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Overwrite the file atomically (emulate write failure)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
tryCatch({
  pathname <- createFileAtomically("foobar.txt", path=tempdir(), FUN=function(pathname) {
    cat(file=pathname, "Trying to create a new file.\n")
    cat(file=pathname, "Writing a bit, but then an error...\n", append=TRUE)
    # Emulate write error
    stop("An error occured while writing to the new file.")
    cat(file=pathname, "END OF FILE\n", append=TRUE)
  }, overwrite=TRUE)
}, error = function(ex) {
  print(ex$message)
})

# The original file was never overwritten
bfr2 <- readLines(pathname)
cat(bfr2, sep="\n")
stopifnot(identical(bfr2, bfr))

# The partially temporary file remains
pathnameT <- sprintf("%s.tmp", pathname)
stopifnot(isFile(pathnameT))
bfr3 <- readLines(pathnameT)
cat(bfr3, sep="\n")

file.remove(pathnameT)
file.remove(pathname)

Description

Creates a link to a file or a directory. This method tries to create a link to a file/directory on the file system, e.g. a symbolic link and Windows Shortcut links. It depends on operating and file system (and argument settings), which type of link is finally created, but all this is hidden internally so that links can be created the same way regardless of system.

Usage

## Default S3 method:
createLink(link=".", target, skip=!overwrite, overwrite=FALSE,
  methods=getOption("createLink/args/methods", c("unix-symlink", "windows-ntfs-symlink",
  "windows-shortcut")), ...)

Arguments

Value

Returns (invisibly) the path or pathname to the link. If no link was created, NULL is returned.

Required privileges on Windows

In order for method="unix-symlink" (utilizing file.symlink()), method="windows-ntfs-symlink" (utilizing executable mklink), and/or method="windows-shortcut" (utilizing createWindowsShortcut()) to succeed on Windows, the client/R session must run with sufficient privileges (it has been reported that Administrative rights are necessary).

Author(s)

Henrik Bengtsson

References

Ben Garrett, Windows File Junctions, Symbolic Links and Hard Links, September 2009 [https://devtidbits.com/2009/09/07/windows-file-junctions-symbolic-links-and-hard-links/]

See Also

createWindowsShortcut() and file.symlink()

Description

Creates a Microsoft Windows Shortcut (.lnk file).

Usage

## Default S3 method:
createWindowsShortcut(pathname, target, overwrite=FALSE, mustWork=FALSE, ...)

Arguments

Value

Returns (invisibly) the pathname.

Required privileges on Windows

In order for this method, which utilizes Windows Script Host a VBScript, to succeed on Windows, the client/R session must run with sufficient privileges (it has been reported that Administrative rights are necessary).

Author(s)

Henrik Bengtsson

References

[1] Create a windows shortcut (.LNK file), SS64.com, https://ss64.com/nt/shortcut.html

See Also

readWindowsShortcut()

Examples

# Create Windows Shortcut links to a directory and a file
targets <- list(
  system.file(package="R.utils"),
  system.file("DESCRIPTION", package="R.utils")
)

for (kk in seq_along(targets)) {
  cat("Link #", kk, "\n", sep="")

  target <- targets[[kk]]
  cat("Target: ", target, "\n", sep="")

  # Name of *.lnk file
  pathname <- sprintf("%s.LNK", tempfile())

  tryCatch({
    # Will only work on Windows systems with support for VB scripting
    createWindowsShortcut(pathname, target=target)
  }, error = function(ex) {
    print(ex)
  })

  # Was it created?
  if (isFile(pathname)) {
    cat("Created link file: ", pathname, "\n", sep="")

    # Validate that it points to the correct target
    dest <- filePath(pathname, expandLinks="any")
    cat("Available target: ", dest, "\n", sep="")

    res <- all.equal(tolower(dest), tolower(target))
    if (!isTRUE(res)) {
      msg <- sprintf("Link target does not match expected target: %s != %s", dest, target)
      cat(msg, "\n")
      warning(msg)
    }

    # Cleanup
    file.remove(pathname)
  }
}

Description

Allocates a data frame with given column classes.

Usage

## Default S3 method:
dataFrame(colClasses, nrow=1, ...)

Arguments

Value

Returns an NxK data.frame where N equals nrow and K equals length(colClasses).

See Also

data.frame.

Examples

df <- dataFrame(colClasses=c(a="integer", b="double"), nrow=10)
  df[,1] <- sample(1:nrow(df))
  df[,2] <- rnorm(nrow(df))
  print(df)

Description

Detaches packages by name, if loaded.

Usage

## Default S3 method:
detachPackage(pkgname, ...)

Arguments

Value

Returns (invisibly) a named logical vector indicating whether each package was detached or not.

Author(s)

Henrik Bengtsson

See Also

detach().

Description

Sets the dimension of an object with the option to infer one dimension automatically. If one of the elements in the dimension vector is NA, then its value is inferred from the length of the object and the other elements in the dimension vector. If the inferred dimension is not an integer, an error is thrown.

Usage

## Default S3 replacement method:
dimNA(x) <- value

Arguments

Value

Returns (invisibly) what dim<-() returns (see dim() for more details).

Author(s)

Henrik Bengtsson

See Also

dim().

Examples

x <- 1:12
  dimNA(x) <- c(2,NA,3)
  stopifnot(dim(x) == as.integer(c(2,2,3)))

Description

Displays the contents of a text file with line numbers and more.

Usage

## Default S3 method:
displayCode(con=NULL, code=NULL, numerate=TRUE, lines=-1, wrap=79, highlight=NULL,
  pager=getOption("pager"), ...)

Arguments

Value

Returns (invisibly) the formatted code as a character string.

Author(s)

Henrik Bengtsson

See Also

file.show().

Examples

file <- system.file("DESCRIPTION", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file)

file <- system.file("NEWS.md", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file, numerate=FALSE, lines=100:110, wrap=65)

file <- system.file("NEWS.md", package="R.utils")
cat("Displaying: ", file, ":\n", sep="")
displayCode(file, lines=100:110, wrap=65, highlight=c(101,104:108))

Description

Executes a function call with option to ignore unused arguments.

Usage

## Default S3 method:
doCall(.fcn, ..., args=NULL, alwaysArgs=NULL, .functions=list(.fcn),
  .ignoreUnusedArgs=TRUE, envir=parent.frame())

Arguments

Author(s)

Henrik Bengtsson

See Also

do.call().

Examples

doCall("plot", x=1:10, y=sin(1:10), col="red", dummyArg=54,
         alwaysArgs=list(xlab="x", ylab="y"),
         .functions=c("plot", "plot.xy"))

Description

Downloads a file.

Usage

## S3 method for class 'character'
downloadFile(url, filename=basename(url), path=NULL, skip=TRUE, overwrite=!skip, ...,
  username=NULL, password=NULL, binary=TRUE, dropEmpty=TRUE, verbose=FALSE)

Arguments

Details

Currently arguments username and password are only used for downloads via URL protocol 'https'. The 'https' protocol requires that either of 'curl' or 'wget' are available on the system.

Value

Returns the local pathname to the downloaded filename, or NULL if no file was downloaded.

Author(s)

Henrik Bengtsson

See Also

Internally download.file is used. That function may generate an empty file if the URL is not available.

Examples

## Not run: 
 pathname <- downloadFile("https://www.r-project.org/index.html", path="www.r-project.org/")
 print(pathname)

## End(Not run)

Description

Global substitute of expression using regular expressions.

Usage

egsub(pattern, replacement, x, ..., value=TRUE, envir=parent.frame(), inherits=TRUE)

Arguments

Value

Returns an expression.

Author(s)

Henrik Bengtsson

Examples

# Original expression
expr <- substitute({
  res <- foo.bar.yaa(2)
  print(res)
  R.utils::use("R.oo")
  x <- .b.
})

# Some predefined objects
foo.bar.yaa <- function(x) str(x)
a <- 2
b <- a

# Substitute with variable name
expr2 <- egsub("^[.]([a-zA-Z0-9_.]+)[.]$", "\\1", expr, value=FALSE)
print(expr2)
## {
##     res <- foo.bar.yaa(2)
##     print(res)
##     R.utils::use("R.oo")
##     x <- b
## }

# Substitute with variable value
expr3 <- egsub("^[.]([a-zA-Z0-9_.]+)[.]$", "\\1", expr, value=TRUE)
print(expr3)
## {
##     res <- foo.bar.yaa(2)
##     print(res)
##     R.utils::use("R.oo")
##     x <- 2
## }
# Substitute the body of a function
warnifnot <- egsub("stop", "warning", stopifnot, value=FALSE)
print(warnifnot)
warnifnot(pi == 3.14)

Description

Creates a new environment, evaluates an expression therein, and returns the environment.

Usage

env(..., hash=FALSE, parent=parent.frame(), size=29L)

Arguments

Value

Returns an environment.

Author(s)

Henrik Bengtsson

References

[1] R-devel thread 'Create an environment and assign objects to it in one go?' on March 9-10, 2011.

See Also

Internally new.env() and evalq() are used.

Examples

x <- list();

x$case1 <- env({
 # Cut'n'pasted from elsewhere
 a <- 1;
 b <- 2;
});

x$case2 <- env({
 # Cut'n'pasted from elsewhere
 foo <- function(x) x^2;
 a <- foo(2);
 b <- 1;
 rm(foo); # Not needed anymore
});

# Turn into a list of lists
x <- lapply(x, FUN=as.list);

str(x);

Description

Extract a subset of an array, matrix or a vector with unknown dimensions.

This method is useful when you do not know the number of dimensions of the object your wish to extract values from, cf. example.

Usage

## S3 method for class 'array'
extract(x, ..., indices=list(...), dims=names(indices), drop=FALSE)

Arguments

Value

Returns an array.

Author(s)

Henrik Bengtsson

See Also

slice.index()

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example using an array with a random number of dimensions
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
maxdim <- 4
dim <- sample(3:maxdim, size=sample(2:maxdim, size=1), replace=TRUE)
ndim <- length(dim)
dimnames <- list()
for (kk in 1:ndim)
  dimnames[[kk]] <- sprintf("%s%d", letters[kk], 1:dim[kk])
x <- 1:prod(dim)
x <- array(x, dim=dim, dimnames=dimnames)

cat("\nArray 'x':\n")
print(x)


cat("\nExtract 'x[2:3,...]':\n")
print(extract(x, "1"=2:3))

cat("\nExtract 'x[3,2:3,...]':\n")
print(extract(x, "1"=3,"2"=2:3))

cat("\nExtract 'x[...,2:3]':\n")
print(extract(x, indices=2:3, dims=length(dim(x))))



# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Assertions
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
y <- array(1:24, dim=c(2,3,4))
yA <- y[,,2:3]
yB <- extract(y, indices=list(2:3), dims=length(dim(y)))
stopifnot(identical(yB, yA))

yA <- y[,2:3,2]
yB <- extract(y, indices=list(2:3,2), dims=c(2,3), drop=TRUE)
stopifnot(identical(yB, yA))

Description

Checks the permission of a file or a directory.

Usage

## Default S3 method:
fileAccess(pathname, mode=0, safe=TRUE, ...)

Arguments

Details

In R there is file.access() for checking whether the permission of a file. Unfortunately, that function cannot be 100% trusted depending on platform used and file system queried, cf. [1].

Value

Returns an integer; 0 if the permission exists, -1 if not.

Symbolic links

This function follows symbolic links (also on Windows) and returns a value based on the link target (rather than the link itself).

Author(s)

Henrik Bengtsson

References

[1] R-devel thread file.access() on network (mounted) drive on Windows Vista? on Nov 26, 2008. https://stat.ethz.ch/pipermail/r-devel/2008-December/051461.html
[2] Filesystem permissions, Wikipedia, 2010. https://en.wikipedia.org/wiki/Filesystem_permissions

See Also

file.access()

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Current directory
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- "."

# Test for existence
print(fileAccess(path, mode=0))
# Test for execute permission
print(fileAccess(path, mode=1))
# Test for write permission
print(fileAccess(path, mode=2))
# Test for read permission
print(fileAccess(path, mode=4))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# A temporary file
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathname <- tempfile()
cat(file=pathname, "Hello world!")

# Test for existence
print(fileAccess(pathname, mode=0))
# Test for execute permission
print(fileAccess(pathname, mode=1))
# Test for write permission
print(fileAccess(pathname, mode=2))
# Test for read permission
print(fileAccess(pathname, mode=4))

file.remove(pathname)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# The 'base' package directory
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- system.file(package="base")

# Test for existence
print(fileAccess(path, mode=0))
# Test for execute permission
print(fileAccess(path, mode=1))
# Test for write permission
print(fileAccess(path, mode=2))
# Test for read permission
print(fileAccess(path, mode=4))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# The 'base' package DESCRIPTION file
# - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathname <- system.file("DESCRIPTION", package="base")

# Test for existence
print(fileAccess(pathname, mode=0))
# Test for execute permission
print(fileAccess(pathname, mode=1))
# Test for write permission
print(fileAccess(pathname, mode=2))
# Test for read permission
print(fileAccess(pathname, mode=4))

Description

Construct the path to a file from components and expands Windows Shortcuts along the pathname from root to leaf. This function is backward compatible with file.path() when argument removeUps=FALSE and expandLinks="none", except that a (character) NA is return if any argument is NA.

This function exists on all platforms, not only Windows systems.

Usage

## Default S3 method:
filePath(..., fsep=.Platform$file.sep, removeUps=TRUE,
  expandLinks=c("none", "any", "local", "relative", "network"), unmap=FALSE,
  mustExist=FALSE, verbose=FALSE)

Arguments

Details

If expandLinks != "none", each component, call it parent, in the absolute path is processed from the left to the right as follows: 1. If a "real" directory of name parent exists, it is followed. 2. Otherwise, if Microsoft Windows Shortcut file with name parent.lnk exists, it is read. If its local target exists, that is followed, otherwise its network target is followed. 3. If no valid existing directory was found in (1) or (2), the expanded this far followed by the rest of the pathname is returned quietly. 4. If all of the absolute path was expanded successfully the expanded absolute path is returned.

Value

Returns a character string.

On speed

Internal file.exists() is call while expanding the pathname. This is used to check if there exists a Windows shortcut file named 'foo.lnk' in 'path/foo/bar'. If it does, 'foo.lnk' has to be followed, and in other cases 'foo' is ordinary directory. The file.exists() is unfortunately a bit slow, which is why this function appears slow if called many times.

Author(s)

Henrik Bengtsson

See Also

readWindowsShellLink(). readWindowsShortcut(). file.path().

Examples

# Default
print(file.path("foo", "bar", "..", "name")) # "foo/bar/../name"

# Shorten pathname, if possible
print(filePath("foo", "bar", "..", "name"))  # "foo/name"
print(filePath("foo/bar/../name"))           # "foo/name"

# Recognize Windows Shortcut files along the path, cf. Unix soft links
filename <- system.file("data-ex/HISTORY.LNK", package="R.utils")
print(filename)
filename <- filePath(filename, expandLinks="relative")
print(filename)

Description

Package: R.utils
Class FileProgressBar

Object
~~|
~~+--ProgressBar
~~~~~~~|
~~~~~~~+--FileProgressBar

Directly known subclasses:

public static class FileProgressBar
extends ProgressBar

Usage

FileProgressBar(pathname=NULL, ...)

Arguments

Details

A progress bar that sets the size of a file accordingly. This class useful to check the progress of a batch job by just querying the size of a file, for instance, via ftp.

Fields and Methods

Methods:

Methods inherited from ProgressBar:
as.character, getBarString, increase, isDone, reset, setMaxValue, setProgress, setStepLength, setTicks, setValue, update

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

## Not run: 
  
# Creates a progress bar (of length 100) that displays it self as a file.

pb <- FileProgressBar(file.path(tempdir(), "progress.simulation"), max = 10L)
reset(pb)
while (!isDone(pb)) {
  x <- rnorm(3e4)
  increase(pb)
  # Emulate a slow process
  if (interactive()) Sys.sleep(0.1)
  cat(sprintf("File size: %d bytes\n", file.info(pb$pathname)$size))
  Sys.sleep(0.01)
}

  
## End(Not run)

Description

Function to call for finalizing the R session. When called, all registered "onSessionExit" hooks (functions) are called. To define such hooks, use the onSessionExit() function.

This method should not be used by the user.

Usage

## Default S3 method:
finalizeSession(...)

Arguments

Value

Returns (invisibly) the hooks successfully called.

Author(s)

Henrik Bengtsson

See Also

onSessionExit().

Description

Finds all 'srcfile' objects generated by source() in all call frames. This makes it possible to find out which files are currently scripted by source().

Usage

## Default S3 method:
findSourceTraceback(...)

Arguments

Value

Returns a named list of srcfile() objects and/or character strings. The names of the list entries corresponds to the 'filename' value of each corresponding 'srcfile' object. The returned list is empty if source() was not called.

Author(s)

Henrik Bengtsson

See Also

See also sourceutils.

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Create two R script files where one source():s the other
# and both lists the traceback of filenames source():d.
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
path <- tempdir()
pathnameA <- Arguments$getWritablePathname("foo.R", path=path)
pathnameB <- Arguments$getWritablePathname("bar.R", path=path)

code <- 'cat("BEGIN foo.R\n")'
code <- c(code, 'print(findSourceTraceback());')
code <- c(code, sprintf('source("%s");', pathnameB))
code <- c(code, 'cat("END foo.R\n")')
code <- paste(code, collapse="\n")
cat(file=pathnameA, code)

code <- 'cat("BEGIN bar.R\n")'
code <- c(code, 'x <- findSourceTraceback();')
code <- c(code, 'print(x);')
code <- c(code, 'cat("END bar.R\n")')
code <- paste(code, collapse="\n")
cat(file=pathnameB, code)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Source the first file
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
source(pathnameA, echo=TRUE)

Description

Converts a binary/octal/hexadecimal number into a string.

Usage

## S3 method for class 'binmode'
format(x, ...)

Arguments

Value

Returns a character.

Author(s)

Henrik Bengtsson

See Also

format.octmode(), cf. octmode. intToBin() (incl. intToOct() and intToHex()).

Description

Parses, evaluates and outputs a GString.

Usage

## Default S3 method:
gcat(..., file="", append=FALSE, envir=parent.frame())

Arguments

Value

Returns (invisibly) a character string.

Author(s)

Henrik Bengtsson

See Also

gstring().

Description

Identifies and removes DLLs of packages already unloaded. When packages are unloaded, they are ideally also unloading any DLLs (also known as a dynamic shared object or library) they have loaded. Unfortunately, not all package do this resulting in "stray" DLLs still being loaded and occupying R's limited registry. These functions identifies and removes such DLLs.

Usage

gcDLLs(gc=TRUE, quiet=TRUE)

Arguments

Details

If a library fails to unload, an informative warning is generated.

Value

Returns (invisibly) the set of stray DLLs identified.

How to unload DLLs in package (for package developers)

To unload a package DLL whenever the package in unloaded, add the following to your package:

  .onUnload <- function(libpath) {
      ## (1) Force finalizers to be called before removing the DLL
      ##     in case some of them need the DLL.
      gc()

      ## (2) Unload the DLL for this package
      library.dynam.unload(.packageName, libpath)
  }
  

Author(s)

Henrik Bengtsson

See Also

getLoadedDLLs().

Description

Gets the absolute pathname string.

Usage

## Default S3 method:
getAbsolutePath(pathname, workDirectory=getwd(), expandTilde=FALSE, ...)

Arguments

Details

This method will replace replicated slashes ('/') with a single one, except for the double forward slashes prefixing a Microsoft Windows UNC (Universal Naming Convention) pathname.

Value

Returns a character string of the absolute pathname.

Author(s)

Henrik Bengtsson

See Also

isAbsolutePath().

Description

Gets the string of the parent specified by this pathname. This is basically, by default the string before the last path separator of the absolute pathname.

Usage

## Default S3 method:
getParent(pathname, depth=1L, fsep=.Platform$file.sep, ...)

Arguments

Value

Returns a character string if the parent exists, otherwise NULL.

Author(s)

Henrik Bengtsson

Description

Gets the relative pathname relative to a directory.

Usage

## Default S3 method:
getRelativePath(pathname, relativeTo=getwd(), caseSensitive=NULL, ...)

Arguments

Details

In case the two paths are on different file systems, for instance, C:/foo/bar/ and D:/foo/, the method returns pathname as is.

Value

Returns a character string of the relative pathname.

Non-case sensitive comparison

If caseSensitive == NULL, the relative path is used to decide if the comparison should be done in a case-sensitive mode or not. The current check is if it is a Windows path or not, that is, if the relative path starts with a device letter, then the comparison is non-case sensitive.

Author(s)

Henrik Bengtsson

See Also

getAbsolutePath(). isAbsolutePath().

Examples

getRelativePath("foo", "foo")                       # "."
  getRelativePath("foo/bar", "foo")                   # "bar"
  getRelativePath("foo/bar", "foo/bar/yah")           # ".."
  getRelativePath("foo/bar/cool", "foo/bar/yah/sub/") # "../../cool"
  getRelativePath("/tmp/bar/", "/bar/foo/")           # "../../tmp/bar"

  # Windows
  getRelativePath("C:/foo/bar/", "C:/bar/")           # "../foo/bar"
  getRelativePath("C:/foo/bar/", "D:/bar/")           # "C:/foo/bar"

Description

Parses and evaluates a GString into a regular string.

Usage

## Default S3 method:
gstring(..., file=NULL, path=NULL, envir=parent.frame())

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

gcat().

Description

Package: R.utils
Class GString

character
~~|
~~+--GString

Directly known subclasses:

public static class GString
extends character

Usage

GString(..., sep="")

Arguments

Fields and Methods

Methods:

Methods inherited from character:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.Date, as.POSIXlt, as.data.frame, as.raster, coerce,ANY,character-method, coerce,character,SuperClassMethod-method, coerce,character,signature-method, coerce<-,ObjectsWithPackage,character-method, coerce<-,signature,character-method, downloadFile, formula, getDLLRegisteredRoutines, glyphJust, isOpen, makeRaw, sha1, toAsciiRegExprPattern, toFileListTree, toLatex, uses

Author(s)

Henrik Bengtsson

See Also

For convenience, see functions gstring() and gcat().

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# First example
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
who <- "world"

# Compare this...
cat(as.character(GString("Hello ${who}\n")))

# ...to this.
cat(GString("Hello ${who}\n"))

# Escaping
cat(as.character(GString("Hello \\${who}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Looping over vectors
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
x <- 1:5
y <- c("hello", "world")
cat(as.character(GString("(x,y)=(${x},${y})")), sep=", ")
cat("\n")

cat(as.character(GString("(x,y)=(${x},$[capitalize]{y})")), sep=", ")
cat("\n")


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Predefined ("builtin") variables
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat(as.character(GString("Hello ${username} on host ${hostname} running ",
"R v${rversion} in process #${pid} on ${os}. R is installed in ${rhome}.")))


# Other built-in variables/functions...
cat(as.character(GString("Current date: ${date}\n")))
cat(as.character(GString("Current date: $[format='%d/%m/%y']{date}\n")))
cat(as.character(GString("Current time: ${time}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Evaluating inline R code
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat(as.character(GString("Simple calculation: 1+1=${`1+1`}\n")))
cat(as.character(GString("Alternative current date: ${`date()`}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Function values
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Call function rnorm with arguments n=1, i.e. rnorm(n=1)
cat(as.character(GString("Random normal number: $[n=1]{rnorm}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Global search-replace feature
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Replace all '-' with '.'
cat(as.character(GString("Current date: ${date/-/.}\n")))
# Another example
cat(as.character(GString("Escaped string: 12*12=${`12*12`/1/}\n")))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Defining new "builtin" function values
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Define your own builtin variables (functions)
setMethodS3("getBuiltinAletter", "GString", function(object, ...) {
  base::letters[runif(1, min=1, max=length(base::letters))]
})

cat(as.character(GString("A letter: ${aletter}\n")))
cat(as.character(GString("Another letter: ${aletter}\n")))


# Another example
setMethodS3("getBuiltinGstring", "GString", function(object, ...) {
  # Return another GString.
  GString("${date} ${time}")
})

cat(as.character(GString("Advanced example: ${gstring}\n")))


# Advanced example
setMethodS3("getBuiltinRunif", "GString", function(object, n=1, min=0, max=1, ...) {
  formatC(runif(n=n, min=min, max=max), ...)
})

cat(as.character(GString("A random number: ${runif}\n")))
n <- 5
cat(as.character(GString("${n} random numbers: ")))
cat(as.character(GString("$[n=n, format='f']{runif}")))
cat("\n")


# Advanced options.
# Options are parsed as if they are elements in a list, e.g.
#   list(n=runif(n=1,min=1,max=5), format='f')
cat(as.character(GString("$Random number of numbers: ")))
cat(as.character(GString("$[n=runif(n=1,min=1,max=5), format='f']{runif}")))
cat("\n")

Description

Checks if one or several pathnames has a URL protocol.

Usage

## Default S3 method:
hasUrlProtocol(pathname, ...)

Arguments

Value

Returns a logical vector.

Author(s)

Henrik Bengtsson

Description

Concatenating vectors into human-readable strings such as "1, 2, 3, ..., 10".

Usage

## Default S3 method:
hpaste(..., sep="", collapse=", ", lastCollapse=NULL,
  maxHead=if (missing(lastCollapse)) 3 else Inf,
  maxTail=if (is.finite(maxHead)) 1 else Inf, abbreviate="...", empty=character(0L))

Arguments

Details

hpaste(..., sep=" ", maxHead=Inf) corresponds to paste(..., sep=" ", collapse=", ").

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

Internally paste() is used.

Examples

# Some vectors
x <- 1:6
y <- 10:1
z <- LETTERS[x]

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Abbreviation of output vector
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
printf("x = %s.\n", hpaste(x))
## x = 1, 2, 3, ..., 6.

printf("x = %s.\n", hpaste(x, maxHead=2))
## x = 1, 2, ..., 6.

printf("x = %s.\n", hpaste(x, maxHead=3)) # Default
## x = 1, 2, 3, ..., 6.

# It will never output 1, 2, 3, 4, ..., 6
printf("x = %s.\n", hpaste(x, maxHead=4))
## x = 1, 2, 3, 4, 5, 6.

# Showing the tail
printf("x = %s.\n", hpaste(x, maxHead=1, maxTail=2))
## x = 1, ..., 5, 6.

# Turning off abbreviation
printf("y = %s.\n", hpaste(y, maxHead=Inf))
## y = 10, 9, 8, 7, 6, 5, 4, 3, 2, 1

## ...or simply
printf("y = %s.\n", paste(y, collapse=", "))
## y = 10, 9, 8, 7, 6, 5, 4, 3, 2, 1


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Adding a special separator before the last element
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Change last separator
printf("x = %s.\n", hpaste(x, lastCollapse=", and "))
## x = 1, 2, 3, 4, 5, and 6.



# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Backward compatibility with paste()
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
s1 <- hpaste(x, maxHead=Inf)
s2 <- paste(x, collapse=", ")
printf("s = %s.\n", s1);
stopifnot(identical(s1, s2))

s1 <- hpaste('<', x, '>', maxHead=Inf)
s2 <- paste('<', x, '>', sep="", collapse=", ")
printf("s = %s.\n", s1);
stopifnot(identical(s1, s2))

s1 <- hpaste(x, y, z, sep="/", maxHead=Inf)
s2 <- paste(x, y, z, sep="/", collapse=", ")
printf("s = %s.\n", s1);
stopifnot(identical(s1, s2))

s1 <- hpaste(x, collapse=NULL, maxHead=Inf)
s2 <- paste(x, collapse=NULL)
stopifnot(identical(s1, s2))

Description

Checks if a set of values are inside one or more intervals.

Usage

## S3 method for class 'numeric'
inAnyInterval(...)

Arguments

Value

Returns a logical vector.

Author(s)

Henrik Bengtsson

See Also

mapToIntervals().

Description

Insert values to a vector at certain positions.

Usage

## Default S3 method:
insert(x, ats, values=NA, useNames=TRUE, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

append() takes argument after (a scalar). For example, append(x, y, after=after) == insert(x, values=y, ats=after+1). Contrary to append(), insert() accepts a vector of insert indices.

Examples

# Insert NAs (default) between all values
y <- c(a=1, b=2, c=3)
print(y)
x <- insert(y, ats=2:length(y))
Ex <- c(y[1], NA_real_, y[2], NA_real_, y[3])
print(x)
stopifnot(identical(x,Ex))

# Insert at first position
y <- c(a=1, b=2, c=3)
print(y)
x <- insert(y, ats=1, values=rep(NA_real_,2))
Ex <- c(NA_real_,NA_real_,y)
print(x)
stopifnot(identical(x,Ex))

x <- insert(y, ats=1, values=rep(NA_real_,2), useNames=FALSE)
print(x)

# Insert at last position (names of 'values' are ignored
# because input vector has no names)
x <- insert(1:3, ats=4, values=c(d=2, e=1))
Ex <- c(1:3,2,1)
print(x)
stopifnot(identical(x,Ex))


# Insert in the middle of a vector
x <- insert(c(1,3,2,1), ats=2, values=2)
print(x)
stopifnot(identical(as.double(x),as.double(Ex)))


# Insert multiple vectors at multiple indices at once
x0 <- c(1:4, 8:11, 13:15)

x <- insert(x0, ats=c(5,9), values=list(5:7,12))
print(x)
Ex <- 1:max(x)
stopifnot(identical(as.double(x),as.double(Ex)))

x <- insert(x0, ats=c(5,9,12), values=list(5:7,12,16:18))
print(x)
Ex <- 1:max(x)
stopifnot(identical(as.double(x),as.double(Ex)))


# Insert missing indices
Ex <- 1:20
missing <- setdiff(Ex, x0)
x <- x0
for (m in missing)
  x <- insert(x, ats=m, values=m)
print(x)
stopifnot(identical(as.double(x),as.double(Ex)))

Description

Install R packages by name or URL.

Usage

## Default S3 method:
installPackages(pkgs, types="auto", repos=getOption("repos"), ..., destPath=".",
  cleanup=TRUE)

Arguments

Value

Returns nothing.

Limitations

This method cannot install any packages that are already in use. Certain packages are always in use when calling this method, e.g. R.methodsS3, R.oo, and R.utils.

Author(s)

Henrik Bengtsson

Examples

## Not run: 
 installPackages("R.rsp")
 installPackages("https://cran.r-project.org/src/contrib/Archive/R.rsp/R.rsp_0.8.2.tar.gz")
 installPackages("https://cran.r-project.org/bin/windows/contrib/4.0/R.rsp_0.44.0.zip")

## End(Not run)

Description

Generates a vector of indices from a matrix of intervals.

Usage

## S3 method for class 'matrix'
intervalsToSeq(fromTo, sort=FALSE, unique=FALSE, ...)

Arguments

Author(s)

Henrik Bengtsson

See Also

seqToIntervals().

Examples

## Not run: See example(seqToIntervals)

Description

Converts an integer to a binary/octal/hexadecimal number.

Usage

intToBin(x)
 intToOct(x)
 intToHex(x)

Arguments

Details

For length(x) > 1, the number of characters in each of returned elements is the same and driven by the x element that requires the highest number of character - all other elements are padded with zeros (or ones for negative values). This is why we for instance get intToHex(15) == "f" but intToHex(15:16) == c("0f", "10").

The supported range for intToHex(), intToOct(), and intToBin() is that of R integers, i.e. [-.Machine$integer.max, +.Machine$integer.max] where. .Machine$integer.max is $2^31-1$. This limitation is there such that negative values can be converted too.

Value

Returns a character string of length length(x). For coercions out of range, NA_character_ is returned for such elements.

Author(s)

Henrik Bengtsson

Description

Checks if this pathname is absolute.

Usage

## Default S3 method:
isAbsolutePath(pathname, ...)

Arguments

Value

Returns a TRUE if the pathname is absolute, otherwise FALSE.

Author(s)

Henrik Bengtsson

Description

Checks if the file specification is a directory.

Usage

## Default S3 method:
isDirectory(pathname, ...)

Arguments

Value

Returns TRUE if the file specification is a directory, otherwise FALSE is returned.

Symbolic links

This function follows symbolic links (also on Windows) and returns a value based on the link target (rather than the link itself).

Author(s)

Henrik Bengtsson

See Also

To check if it is a file see isFile(). Internally file.info() is used. See also file_test.

Description

Checks if the current file position for a connection is at the 'End of File'.

Usage

## S3 method for class 'connection'
isEof(con, ...)

Arguments

Details

Internally seek() is used, which according to to the R help is discouraged on Windows. However, after many years of large-scale testing on various Windows versions and file systems we have yet to experience issues with using seek() on Windows.

Value

Returns a logical.

Author(s)

Henrik Bengtsson

See Also

For more information see connection.

Description

Checks if the file specification is a file.

Usage

## Default S3 method:
isFile(pathname, ...)

Arguments

Value

Returns TRUE if the file specification is a file, otherwise FALSE is returned.

Symbolic links

This function follows symbolic links (also on Windows) and returns a value based on the link target (rather than the link itself).

Author(s)

Henrik Bengtsson

See Also

To check if it is a directory see isDirectory(). Internally file.info() is used. See also file_test.

Description

Checks if there is an open connection to a file.

Usage

## S3 method for class 'character'
isOpen(pathname, rw=c("read", "write"), ...)

Arguments

Value

Returns a logical vector indicating for each file whether there exists an open file connection or not.

Author(s)

Henrik Bengtsson

See Also

See isOpen() in connections. showConnections().

Description

Checks if a package is installed or not.

Usage

## Default S3 method:
isPackageInstalled(package, ...)

Arguments

Value

Returns a logical vector.

Author(s)

Henrik Bengtsson

See Also

isPackageLoaded().

Description

Checks if a package is loaded or not. Note that, contrary to require(), this function does not load the package if not loaded.

Usage

## Default S3 method:
isPackageLoaded(package, version=NULL, ...)

Arguments

Value

Returns a logical.

Author(s)

Henrik Bengtsson

See Also

To check if a package is installed or not, see isPackageInstalled().

Description

Identifies all entries with replicated values, that is, with values that exist more than once.

Usage

isReplicated(x, ...)
 replicates(x, ...)

Arguments

Details

Let reps <- isReplicated(x). Then it always holds that:

• reps == rev(isReplicated(rev(x)))

• reps == duplicated(x) | duplicated(x, fromLast=TRUE)

• reps == !is.element(x, setdiff(x, unique(x[duplicated(x)])))

Value

A logical vector of length K, where TRUE indicates that the value exists elsewhere, otherwise not.

Author(s)

Henrik Bengtsson

See Also

Internally duplicated() is used. See also isSingle().

Examples

x <- c(1,1,2,3,4,2,1)
x <- base::letters[x]
print(x)

# Identify entries with replicated values
reps <- isReplicated(x)
print(x[reps])
stopifnot(x[reps] == replicates(x))

# Identify entries with unique values
print(x[!reps])
stopifnot(x[!reps] == singles(x))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Validation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
x <- c(1,1,2,3,4,2,1)
x <- base::letters[x]
reps <- isReplicated(x)

stopifnot(all(table(x[reps]) > 1))
stopifnot(all(table(x[!reps]) == 1))
stopifnot(all(reps == rev(isReplicated(rev(x)))))
stopifnot(all(reps == duplicated(x) | duplicated(x, fromLast=TRUE)))
stopifnot(all(reps == !is.element(x, setdiff(x, unique(x[duplicated(x)])))))
stopifnot(all(sort(c(singles(x), replicates(x))) == sort(x)))


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Benchmarking singles()
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
set.seed(0xBEEF)
n <- 1e6
x <- sample(1:(n/2), size=n, replace=TRUE)
t <- system.time({
  s <- isSingle(x)
})
print(sum(s))

t0 <- system.time({
  s0 <- !(x %in% x[duplicated(x)]);
})
print(t/t0)
stopifnot(all(s == s0))

Description

Identifies all entries that exists exactly once.

Usage

isSingle(x, ...)
 singles(x, ...)

Arguments

Value

A logical vector of length K, indicating whether the value is unique or not.

Author(s)

Henrik Bengtsson

See Also

Internally isReplicated() is used.

Description

Checks if one or several pathnames is URLs.

Usage

## Default S3 method:
isUrl(pathname, ...)

Arguments

Value

Returns a logical vector of either TRUE or FALSE.

Author(s)

Henrik Bengtsson

Description

Checks if a value (or a vector of values) is (close to) zero or not where "close" means if the absolute value is less than neps*eps. Note that x == 0 will not work in all cases.

By default eps is the smallest possible floating point value that can be represented by the running machine, i.e. .Machine$double.eps and neps is one. By changing neps it is easy to adjust how close to zero "close" means without having to know the machine precision (or remembering how to get it).

Usage

## Default S3 method:
isZero(x, neps=1, eps=.Machine$double.eps, ...)

Arguments

Value

Returns a logical vector indicating if the elements are zero or not.

Author(s)

Henrik Bengtsson

See Also

all.equal(). Comparison. .Machine.

Examples

x <- 0
print(x == 0)      # TRUE
print(isZero(x))   # TRUE

x <- 1
print(x == 0)      # FALSE
print(isZero(x))   # FALSE

x <- .Machine$double.eps
print(x == 0)      # FALSE
print(isZero(x))   # FALSE

x <- 0.9*.Machine$double.eps
print(x == 0)      # FALSE
print(isZero(x))   # TRUE

# From help(Comparisions)
x1 <- 0.5 - 0.3
x2 <- 0.3 - 0.1
print(x1 - x2)
print(x1 == x2)                           # FALSE on most machines
print(identical(all.equal(x1, x2), TRUE)) # TRUE everywhere
print(isZero(x1-x2))                      # TRUE everywhere

Description

Package: R.utils
Class Java

Object
~~|
~~+--Java

Directly known subclasses:

public static class Java
extends Object

Static class that provides methods for reading and writing Java data types. Currently the following data types are supported: byte, short and int. R character strings can be written as UTF-8 formatted strings, which can be read by Java. Currently on Java String's that contain ASCII characters can be imported into R. The reason for this is that other characters are translated into non-eight bits data, e.g. 16- and 24-bits, which the readChar() method currently does not support.

Furthermore, the Java class defines some static constants describing the minimum and maximum value of some of the common Java data types: BYTE.MIN, BYTE.MAX SHORT.MIN, SHORT.MAX INT.MIN, INT.MAX LONG.MIN, and LONG.MAX.

Usage

Java()

Fields and Methods

Methods:

Methods inherited from Object:
$, $<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save

Author(s)

Henrik Bengtsson

Examples

pathname <- tempfile()

# Open the temporary file for writing
out <- file(pathname, open="wb")
b <- -128:127
Java$writeByte(out, b)
s <- -32768:32767
Java$writeShort(out, s)
i <- c(-2147483648, -2147483647, -1, 0, +1, 2147483646, 2147483647);
Java$writeInt(out, i)
str <- c("This R string was written (using the UTF-8 format) using",
         "the static methods of the Java class in the R.io package.")
str <- paste(str, collapse="\n")
Java$writeUTF(out, str)
close(out)

# Open the temporary file for reading
inn <- file(pathname, open="rb")

bfr <- Java$readByte(inn, n=length(b))
cat("Read ", length(bfr), " bytes.\n", sep="")
if (!identical(bfr, b))
  throw("Failed to read the same data that was written.")

bfr <- Java$readShort(inn, n=length(s))
cat("Read ", length(bfr), " shorts.\n", sep="")
if (!identical(bfr, s))
  throw("Failed to read the same data that was written.")

bfr <- Java$readInt(inn, n=length(i))
cat("Read ", length(bfr), " ints.\n", sep="")
if (!identical(bfr, i))
  throw("Failed to read the same data that was written.")

bfr <- Java$readUTF(inn)
cat("Read ", nchar(bfr), " UTF characters:\n", "'", bfr, "'\n", sep="")

close(inn)

file.remove(pathname)