Member functions

To use those functions, include the file CheapMatrix.h in your program and link with -lCheapMatrix -lm. All those functions are located in the CheapMatrix namespace.

Creation & initialisation

Matrix(int rows, int cols, size_t bsize=0, const string& filename="", bool auto_del=false);
inline Vector(int rows, size_t bsize=0, const string& filename="", bool auto_del=false)
Creates a rows by cols Matrix, or a rows by 1 column Vector. The matrix is created either in memory, or using a buffer of bsize elements and dumping the rest to the file specified by filename (actually, the number of elements is rounded up to align the memory to next system page size limit). The file will be created if it doesn't exist, padded or truncated if it is not the correct dimension, and deleted automatically if auto_del is set to true. Data already present in the file is used as initial value for the matrix, so you may use those files as binary caches.
Vectors are considered to be column vectors for all purposes. If you need a row vector, just transpose a Vector or create a Matrix with the correct dimensions.

inline Matrix()
inline Vector()
Creates an empty Matrix or Vector. Those objects are considered null matrices with 0 lines and 0 columns, and are really useful when you don't know the dimensions a matrix will have in advance (like when loading from a file). There is a corresponding boolean test.

inline Matrix(const Matrix& target)
inline Matrix& operator=(const Matrix target)
inline Vector(const Vector& target)
inline Vector& operator=(const Vector target)
inline Vector(const Matrix& target)
inline Vector& operator=(const Matrix target)
These are the copy constructors and operators. Of course, only the matrix information is copied, not the data itself (shallow copy). Use the copy() function to copy the data. Assigning a matrix to a vector is achieved by reshaping to a single column.

inline Matrix& operator=(const MatrixType& t)
inline Matrix& operator,(const MatrixType& t)
inline Vector& operator=(const MatrixType& t)
inline Vector& operator,(const MatrixType& t)
Those are the initialisation list operators. They are used when you write V = 1, 2, 3; for example.

Data

inline MatrixType& Matrix::operator()(int r, int c) const
inline MatrixType& Vector::operator()(int index) const
These operators will return the data for the matrix cell at row r and column c for the Matrix operator, or at the index given for the Vector one, counting from 1 for the indices (FORTRAN convention).

inline MatrixType& Matrix::operator[](int index) const
inline Vector Vector::operator[](int r) const
C-style array indexing (counting from 0 to dimension-1). This returns a row as a vector for the Matrix operator, and a data element for the Vector one. Using the () operators is much faster, thus recommended.

Matrix copy(const Matrix& target) const;
Safe data copy. The data of the target is copied into our own buffer, using a temporary if necessary to avoid side effects. Dimensions must match. Using a for loop is generally slower, and unsafe with respect to side effects. You've been warned...

Matrix copy() const;
Return a copy of our own data in a new matrix. This copy is free of any transformation, and is in its own buffer. See also detach.

Matrix fill(const MatrixType& value) const;
Matrix fill(MatrixType (*func)(int,int)) const;
Fill the current matrix with a value. A generator can also be used. This function is called on each (row, column) pair to produce a value for each cell. See also generate.

Matrix map(MatrixType (*func)(MatrixType)) const;
Matrix map(MatrixType (*func)(MatrixType,void*), void* arg) const;
Map a function to the current matrix. This function is called on each cell, and its result becomes the new cell value. See also map.

bool detach(size_t bsize=0, const string& filename="", bool auto_del=false);
Detaches our own data from any other matrix. This means a new data buffer is created, either in memory or using the swap file given (same comments as for the constructor). The transformation list is emptied, and the new buffer is of course contiguous. See the example range.cpp for a practical use.

Geometry & coordinates

All these functions act on the matrix wrappers and do not copy or move any data, so are quite fast. None of them affect the matrix they refer to, but rather return the result of their operation.

inline int rows() const
Returns the number of rows of this matrix.

inline int cols() const
Returns the number of columns of this matrix.

Matrix reshape(int r, int c) const;
Returns the matrix reshaped to new dimensions. The number of elements must be the same before and after the reshaping. Elements are ordered column by column and this order is kept in the final matrix.

Matrix transpose() const;
Returns the transposed matrix.

Matrix flip_row_range(int r1, int r2) const;
This will flip a range of rows. The row r1 is exchanged with r2, r1+1 with r2-1, and so on. Rows outside the range are unaffected.

Matrix flip_col_range(int c1, int c2) const;
Flips a range of columns. See the equivalent function for rows.

Matrix flip_rows(int r1, int r2) const;
Exchange the rows r1 and r2.

Matrix flip_cols(int c1, int c2) const;
Exchange the columns c1 and c2.

inline Matrix operator()(int r1, int r2, int c1, int c2) const
Sub-Matrix extraction, basic form. This will extract the matrix ranging from row r1 to r2, and column c1 to c2.

Matrix operator()(const Vector& indices, int c1, int c2) const;
Matrix operator()(int r1, int r2, const Vector& indices) const;
inline Matrix operator()(const Vector& indices, int c) const
inline Matrix operator()(int r, const Vector& indices) const
Matrix operator()(IndexRange i, int c1, int c2) const;
Matrix operator()(int r1, int r2, IndexRange i) const;
inline Matrix operator()(IndexRange i, int c) const
inline Matrix operator()(int r, IndexRange i) const
Matrix operator()(const Vector& indices, IndexRange i) const;
Matrix operator()(IndexRange i, const Vector& indices) const;
Sub-Matrix extraction, extended modes.
Feeding a Vector to one of those operators will result in extracting the rows or columns corresponding to the values in the vector. For example, if v is a size 3 Vector containing the values 3, 9, 5, then A(4, v) will extract the submatrix of A from the row 4, and columns 3, 9 and 5 in this order.
It is also possible to specify an index range, currently 'all' or 'boundary' are the two possibilities. A(all, 5, 7) will return a matrix containing all the rows of A, but only the columns from 5 to 7. Boundary selects only the first and last row or column, not all of them.
Combined with the range utility, all this enables complex extractions very easily. As you would write B(:, 5:2:9) in Octave for instance, you can write B(all, range(5,2,9)) here. See also the example range.cpp

inline Vector operator()(int r1, int r2) const
Vector operator()(const Vector& indices) const;
Vector operator()(IndexRange i) const;
Sub-Vector extraction. See the equivalent operators for Matrices for a description.

Tests

inline operator bool() const
You can test all Matrices for nullity with this conversion to bool. if (a) {/* a is not null */} for example.

bool operator==(const Matrix& a) const;
Test for data equality.

bool operator!=(const Matrix& a) const;
Test for data inequality.

inline bool equal_ref(const Matrix& a) const
Test for data reference equality. This is true if both matrix refer to the same data buffer, all transformations omitted. This enables testing for a possibility of side effects, in which case you ought to abort or ensure a correct result still. See the copy function, and the example side_effects.cpp for a description of the problem.

Memory management

bool hold() const
Try to hold the whole matrix in memory. Returns true if the data is already in memory, and false for null matrices (cannot hold nothing).

bool release() const
Revert to the default of loading only a buffer in memory. This function returns true even if there is no file mapping (considering the data is then in fact one big buffer) or if the matrix is null.

static void temporary_buffer(size_t buf_size = 0)
Specify a buffer size for temporary matrices. Temporary matrices can be used for example to store in-between results on a line with arithmetic (example: In Matrix a = b + c; the data referred by a comes from a temporary). The default size of 0 means that temporaries will use memory only.

static Matrix temporary(int rows, int cols);
static Vector temporary(int rows);
Returns a temporary Matrix or Vector, with a buffer size set by the previous function. The file name, if used, was found with tmpnam and the file will be destroyed after use.

off_t contiguous() const;
This function will return the leading dimension of the matrix if it is contiguous, or 0. Contiguous means that the column elements are next to each other in memory, but there can be a fixed gap between one column and another. Hence the leading dimension, which is the distance in number of elements between the beginning of two consecutive columns. This function is really useful when calling LAPACK routines. This also means you could hack with pointer arithmetic on continuous, all in memory, matrices, but I recommend not to bother with that except for legacy C/Fortran code compatibility.

Arithmetic

Matrix operator*=(const Matrix& a);
This is the matrix multiply and affect operator. It works on square matrices only, an assertion is used to ensure that.

Matrix multiply(const Matrix& b);
Matrix divide(const Matrix& b);
Element by element multiplication and division and affectation. This was created as a substitute for the operator= syntax for the corresponding functions.

Matrix& operator++();
Matrix operator++(int);
Matrix& operator--();
Matrix operator--(int);
Respectively the prefix and postfix increment and decrement operators. The corresponding operation is applied on each matrix element.

inline Matrix operator+()
Matrix operator-();
Unary + and - operators. As expected, + has no effect and - returns a temporary with all elements negated.

Nicolas Brodu, 2000-06-17