cBind: 'cbind()' and 'rbind()' recursively built on cbind2/rbind2

Description

The base functions cbind and rbind are defined for an arbitrary number of arguments and hence have the first formal argument .... Now, when S4 objects are found among the arguments, base cbind() and rbind() internally “dispatch” recursively, calling cbind2 or rbind2 respectively, where these have methods defined and so should dispatch appropriately.

cbind2() and rbind2() are from the methods package, i.e., standard R, and have been provided for binding together two matrices, where in Matrix, we have defined methods for these and the 'Matrix' matrices.

Usage

## cbind(..., deparse.level = 1)
## rbind(..., deparse.level = 1)
## and e.g.,
# S4 method for denseMatrix,sparseMatrix
cbind2(x,y, sparse = NA, ...)
# S4 method for sparseMatrix,denseMatrix
cbind2(x,y, sparse = NA, ...)
# S4 method for denseMatrix,sparseMatrix
rbind2(x,y, sparse = NA, ...)
# S4 method for sparseMatrix,denseMatrix
rbind2(x,y, sparse = NA, ...)

Arguments

…, x, y

matrix-like R objects to be bound together, see cbind and rbind.

sparse

option logical indicating if the result should be sparse, i.e., formally inheriting from "'>sparseMatrix". The default, NA, decides from the “sparsity” of x and y, see e.g., the R code in selectMethod(cbind2, c("sparseMatrix","denseMatrix")).

deparse.level

integer determining under which circumstances column and row names are built from the actual arguments' ‘expression’, see cbind.

Value

typically a ‘matrix-like’ object of a similar class as the first argument in ….

Note that sometimes by default, the result is a '>sparseMatrix if one of the arguments is (even in the case where this is not efficient). In other cases, the result is chosen to be sparse when there are more zero entries is than non-zero ones (as the default sparse in Matrix()).

Historical Remark

Before R version 3.2.0 (April 2015), we have needed a substitute for S4-enabled versions of cbind and rbind, and provided cBind and rBind with identical syntax and semantic in order to bind together multiple matrices ("matrix" or "Matrix" and vectors. With R version 3.2.0 and newer, cBind and rBind are deprecated and produce a deprecation warning (via .Deprecated), and your code should start using cbind() and rbind() instead.

Examples

Run this code

# NOT RUN {
(a <- matrix(c(2:1,1:2), 2,2))

(M1 <- cbind(0, rbind(a, 7))) # a traditional matrix

D <- Diagonal(2)
(M2 <- cbind(4, a, D, -1, D, 0)) # a sparse Matrix

stopifnot(validObject(M2), inherits(M2, "sparseMatrix"),
          dim(M2) == c(2,9))
# }