Matrix¶

Constructors¶

Matrix::Matrix()¶

Create a matrix with zero row and zero column.

Matrix::Matrix(const Matrix &other)¶

Copy constructor. Resulting object will share the SEXP data with other.

Matrix::Matrix(SEXP x)¶

Wrap a given Matrix. A type conversion will be conducted if types don’t match.

Matrix::Matrix(const Dimension &dims)¶

Create a Matrix with the given dimension, and fill it with zeros. The Dimension class is defined in <Rcpp/Dimension.h>. An example:

library(Rcpp)
evalCpp("NumericMatrix(Dimension(2, 3))")
##      [,1] [,2] [,3]
## [1,]    0    0    0
## [2,]    0    0    0

Matrix::Matrix(const int &nrows_, const int &ncols)¶

Create a Matrix with nrows_ rows and ncols columns, and fill it with zeros.

library(Rcpp)
evalCpp("NumericMatrix(2, 3)")
##      [,1] [,2] [,3]
## [1,]    0    0    0
## [2,]    0    0    0

template <typename Iterator>

Matrix::Matrix(const int &nrows_, const int &ncols, Iterator start)¶

Create a Matrix with nrows_ rows and ncols columns, and fill it with data starting from start.

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_data()
{
    double src[] = {1, 2, 3, 4, 5, 6};
    return NumericMatrix(2, 2, src);
}

/*** R

ex_Matrix_data()
##      [,1] [,2]
## [1,]    1    3
## [2,]    2    4

*/

Matrix::Matrix(const int &n)¶

Create a diagonal Matrix with n rows and n columns, and fill it with zeroes.

library(Rcpp)
evalCpp("NumericMatrix(2)")
##      [,1] [,2]
## [1,]    0    0
## [2,]    0    0

template <bool NA, typename MAT>

Matrix::Matrix(const MatrixBase<RTYPE, NA, MAT> &other)¶

Create a matrix from another object that is also derived from the MatrixBase class. Typically other is an Rcpp sugar expression, such as the example below:

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_fromsugar()
{
    NumericMatrix x(3);
    IntegerMatrix y = col(x); // rhs is a sugar expression
    return y;
}

/*** R

ex_Matrix_fromsugar()
##      [,1] [,2] [,3]
## [1,]    1    2    3
## [2,]    1    2    3
## [3,]    1    2    3

*/

Matrix::Matrix(const SubMatrix<RTYPE> &sub)¶

Create a matrix from a submatrix.

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_fromsub(NumericMatrix x, int n)
{
    NumericMatrix::Sub sub = x(Range(0, n - 1), Range(0, n - 1));
    NumericMatrix res(sub);
    return res;
}

/*** R

x = matrix(as.numeric(1:9), 3, 3)
ex_Matrix_fromsub(x, 2);
##      [,1] [,2]
## [1,]    1    4
## [2,]    2    5

*/

Defined in Matrix¶

int ncol() const¶

Return the number of columns.

int nrow() const¶

Return the number of rows.

int cols() const¶

Alias of ncol().

int rows() const¶

Alias of nrow().

Row row(int i)¶

Return the i-th row (0-based).

Column column(int i)¶

Return the i-th column (0-based).

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_rowcol(NumericMatrix x, int ir, int ic)
{
    NumericMatrix::Row    r = x.row(ir - 1);
    NumericMatrix::Column c = x.column(ic - 1);
    // Row and Column act as vectors
    r[0] = c[0] = 0;
    // They can also be assigned to vectors
    NumericVector rvec = r;
    NumericVector cvec = c;
    return List::create(Named("row") = rvec, Named("col") = cvec);
}

/*** R

x = matrix(as.numeric(1:9), 3, 3)
ex_Matrix_rowcol(x, 2, 2);
## $row
## [1] 0 5 8
##
## $col
## [1] 0 5 6
x
##      [,1] [,2] [,3]
## [1,]    1    0    7
## [2,]    0    5    8
## [3,]    3    6    9

*/

iterator begin()¶

Return an iterator pointing to the first element of the matrix.

iterator end()¶

Return an iterator pointing to the past-the-end element of the matrix.

const_iterator begin() const¶

Return an iterator pointing to the first element of the matrix. Read-only.

const_iterator end() const¶

Return an iterator pointing to the past-the-end element of the matrix. Read-only.

template <typename U>

void fill_diag(const U &u)¶

Fill the diagonal elements of this matrix with u.

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_filldiag(NumericMatrix x)
{
    x.fill_diag(0.0);
    return x;
}

/*** R

x = matrix(as.numeric(1:9), 3, 3)
ex_Matrix_filldiag(x);
x
##      [,1] [,2] [,3]
## [1,]    0    4    7
## [2,]    2    0    8
## [3,]    3    6    0

## This leads to unexpected results
x2 = matrix(as.numeric(1:8), 2, 4)
ex_Matrix_filldiag(x2);
##      [,1] [,2] [,3] [,4]
## [1,]    0    3    5    7
## [2,]    2    4    0    8

*/

Proxy operator[](int i)¶

Get the reference of the i-th element (0-based) of the matrix without bound check.

const_Proxy operator[](int i) const¶

Get the i-th element of the vector without bound check. Read-only.

Proxy operator()(const size_t &i, const size_t &j)¶

Get the reference of the element in i-th row and j-th column (both 0-based) with bound check.

const_Proxy operator()(const size_t &i, const size_t &j) const¶

Get the element in i-th row and j-th column (both 0-based) with bound check. Read-only.

Row operator()(int i, internal::NamedPlaceHolder)¶

Get the i-th row of the matrix (0-based). The symbol _ can be used as a placeholder for the second argument.

Column operator()(internal::NamedPlaceHolder, int i)¶

Get the i-th column of the matrix. The symbol _ can be used as a placeholder for the first argument.

Column operator()(internal::NamedPlaceHolder, int i) const¶

Get the i-th column of the matrix. Read-only.

Sub operator()(const Range &row_range, const Range &col_range)¶

Get the submatrix specified by the row range and column range.

Sub operator()(internal::NamedPlaceHolder, const Range &col_range)¶

Select several columns of this matrix.

Sub operator()(const Range &row_range, internal::NamedPlaceHolder)¶

Select several rows of this matrix.

Examples of matrix subsetters:

#include <Rcpp.h>
using namespace Rcpp;

// [[Rcpp::export]]
RObject ex_Matrix_subsetter()
{
    double src[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};
    NumericMatrix mat(3, 4, src);
    Rcout << "Matrix:\n";
    Rf_PrintValue(mat);

    // Single index subsetter
    Rcout << "\nFirst element: " << mat[0] << "\n";
    Rcout << "\nLast element: " << mat[mat.length() - 1] << "\n";

    // double indices subsetter
    Rcout << "\n(1, 3) element: " << mat(0, 2) << "\n";

    // Get the first row
    NumericVector r = mat(0, _);
    Rcout << "\nFirst row:\n";
    Rf_PrintValue(r);

    // Get the first two rows
    NumericMatrix rs = mat(Range(0, 1), _);
    Rcout << "\nFirst two rows:\n";
    Rf_PrintValue(rs);

    // Get the last column
    NumericVector c = mat(_, mat.ncol() - 1);
    Rcout << "\nLast column:\n";
    Rf_PrintValue(c);

    // Get columns 1 to 3
    NumericMatrix cs = mat(_, Range(0, 2));
    Rcout << "\nColumns 1 to 3:\n";
    Rf_PrintValue(cs);

    // Submatrix from (2, 2) to (3, 4)
    NumericMatrix sub = mat(Range(1, 2), Range(1, 3));
    Rcout << "\n(2, 2) to (3, 4) block:\n";
    Rf_PrintValue(sub);

    return R_NilValue;
}

/*** R

invisible(ex_Matrix_subsetter())
## Matrix:
##      [,1] [,2] [,3] [,4]
## [1,]    1    4    7   10
## [2,]    2    5    8   11
## [3,]    3    6    9   12
##
## First element: 1
##
## Last element: 12
##
## (1, 3) element: 7
##
## First row:
## [1]  1  4  7 10
##
## First two rows:
##      [,1] [,2] [,3] [,4]
## [1,]    1    4    7   10
## [2,]    2    5    8   11
##
## Last column:
## [1] 10 11 12
##
## Columns 1 to 3:
##      [,1] [,2] [,3]
## [1,]    1    4    7
## [2,]    2    5    8
## [3,]    3    6    9
##
## (2, 2) to (3, 4) block:
##      [,1] [,2] [,3]
## [1,]    5    8   11
## [2,]    6    9   12

*/