Matrix Arithmetic — Operator Overloading¶

ARITHMETIC OPERATORS¶

In-Place Operations

This section defines the arithmetic operators that act on the current matrix itself (in-place operations). These operators modify the matrix and return a reference to it, enabling chained operations like A += B += C. The operators are optimized to handle padding and use DSP-accelerated functions when available.

Copy assignment¶

Mat &operator=(const Mat &src);

Description:

Copy assignment operator for the matrix. Copies elements from source matrix to current matrix. Handles dimension changes by reallocating memory if necessary. Prevents assignment to sub-matrix views for safety.

Mathematical Principle:

Creates an independent copy of the source matrix. Unlike copy constructor, this is used for existing matrices.

Parameters:

const Mat &src : Source matrix.

Returns:

Mat& - Reference to the current matrix (enables chaining).

Usage Insights:

Memory Management: Automatically reallocates memory if dimensions differ. Frees old memory if it was internally allocated.
Sub-Matrix Protection: Assignment to sub-matrix views is forbidden to prevent accidental data corruption.
Self-Assignment: Handles self-assignment safely (A = A).
Performance: O(n²) for n×n matrices. For large matrices, consider if a view would suffice.

Add matrix¶

Mat &operator+=(const Mat &A);

Description:

Adds the specified matrix to this matrix.

Parameters:

const Mat &A : Matrix to be added.

Add constant¶

Mat &operator+=(float C);

Description:

Element-wise addition of a constant to this matrix.

Parameters:

float C : The constant to add.

Returns:

Mat& - Reference to the current matrix.

Subtract matrix¶

Mat &operator-=(const Mat &A);

Description:

Subtracts the specified matrix from this matrix.

Parameters:

const Mat &A : Matrix to be subtracted.

Subtract constant¶

Mat &operator-=(float C);

Description:

Element-wise subtraction of a constant from this matrix.

Parameters:

float C : The constant to subtract.

Returns:

Mat& - Reference to the current matrix.

Multiply matrix¶

Mat &operator*=(const Mat &A);

Description:

Matrix multiplication: this = this * A. Performs standard matrix multiplication (not element-wise). The number of columns of the current matrix must equal the number of rows of A.

Mathematical Principle:

Matrix multiplication C = A * B where Cᵢⱼ = Σₖ Aᵢₖ * Bₖⱼ. This is the standard matrix product, not element-wise multiplication.

Dimension Requirements:

Current matrix: m × n
Matrix A: n × p
Result: m × p

Parameters:

const Mat &A : Matrix to be multiplied (must have n rows, where n = current matrix columns).

Returns:

Mat& - Reference to the current matrix.

Usage Insights:

Memory Efficiency: Creates a temporary copy to avoid overwriting data during computation, then updates the current matrix.
Padding Support: Handles matrices with padding using specialized DSP functions when available.
Performance: O(mnp) for m×n * n×p multiplication. Uses optimized DSP functions on ESP32 platform.
Common Mistake: This is matrix multiplication, not element-wise. For element-wise, use a loop with operator()().

Multiply constant¶

Mat &operator*=(float C);

Description:

Element-wise multiplication by a constant.

Parameters:

float C : The constant multiplier.

Returns:

Mat& - Reference to the current matrix.

Divide matrix (element-wise)¶

Mat &operator/=(const Mat &B);

Description:

Element-wise division: this = this / B.

Parameters:

const Mat &B : The matrix divisor.

Returns:

Mat& - Reference to the current matrix.

Divide constant¶

Mat &operator/=(float C);

Description:

Element-wise division of this matrix by a constant.

Parameters:

float C : The constant divisor.

Returns:

Mat& - Reference to the current matrix.

Exponentiation¶

Mat operator^(int C);

Description:

Element-wise integer exponentiation. Returns a new matrix where each element is raised to the given power.

Parameters:

int C : The exponent (integer).

Returns:

Mat - New matrix after exponentiation.

STREAM OPERATORS¶

Matrix output stream operator¶

std::ostream &operator<<(std::ostream &os, const Mat &m);

Description:

Overloaded output stream operator for the matrix.

Parameters:

std::ostream &os : Output stream.
const Mat &m : Matrix to be output.

ROI output stream operator¶

std::ostream &operator<<(std::ostream &os, const Mat::ROI &roi);

Description:

Overloaded output stream operator for the ROI structure.

Parameters:

std::ostream &os : Output stream.
const Mat::ROI &roi : ROI structure.

Matrix input stream operator¶

std::istream &operator>>(std::istream &is, Mat &m);

Description:

Overloaded input stream operator for the matrix.

Parameters:

std::istream &is : Input stream.
Mat &m : Matrix to be input.

Tip

This section is actually kind of overlapping with print function in terms of showing the matrix.

GLOBAL ARITHMETIC OPERATORS¶

Non-Modifying Operations

The operators in this section return a new matrix object, which is the result of the operation. The original matrices remain unchanged. These are functional-style operations that don't modify their operands, making them safe for use with const references and temporary objects.

When to Use

Use global operators (A + B) when you want to preserve original matrices
Use member operators (A += B) when you want to modify the matrix in-place (more memory efficient)

Add matrix¶

Mat operator+(const Mat &A, const Mat &B);

Description:

Adds two matrices element-wise.

Parameters:

const Mat &A : First matrix.
const Mat &B : Second matrix.

Returns:

Mat - Result matrix A+B.

Add constant¶

Mat operator+(const Mat &A, float C);

Description:

Adds a constant to a matrix element-wise.

Parameters:

const Mat &A : Input matrix A.
float C : Input constant.

Returns:

Mat - Result matrix A+C.

Subtract matrix¶

Mat operator-(const Mat &A, const Mat &B);

Description:

Subtracts two matrices element-wise.

Parameters:

const Mat &A : First matrix.
const Mat &B : Second matrix.

Returns:

Mat - Result matrix A-B.

Subtract constant¶

Mat operator-(const Mat &A, float C);

Description:

Subtracts a constant from a matrix element-wise.

Parameters:

const Mat &A : Input matrix A.
float C : Input constant.

Returns:

Mat - Result matrix A-C.

Multiply matrix¶

Mat operator*(const Mat &A, const Mat &B);

Description:

Multiplies two matrices (matrix multiplication).

Parameters:

const Mat &A : First matrix.
const Mat &B : Second matrix.

Returns:

Mat - Result matrix A*B.

Multiply constant¶

Mat operator*(const Mat &A, float C);

Description:

Multiplies a matrix by a constant element-wise.

Parameters:

const Mat &A : Input matrix A.
float C : Floating point value.

Returns:

Mat - Result matrix A*C.

Multiply constant (left side)¶

Mat operator*(float C, const Mat &A);

Description:

Multiplies a constant by a matrix element-wise.

Parameters:

float C : Floating point value.
const Mat &A : Input matrix A.

Returns:

Mat - Result matrix C*A.

Divide matrix (by constant)¶

Mat operator/(const Mat &A, float C);

Description:

Divides a matrix by a constant element-wise.

Parameters:

const Mat &A : Input matrix A.
float C : Floating point value.

Returns:

Mat - Result matrix A/C.

Divide matrix (element-wise)¶

Mat operator/(const Mat &A, const Mat &B);

Description:

Divides matrix A by matrix B element-wise.

Parameters:

const Mat &A : Input matrix A.
const Mat &B : Input matrix B.

Returns:

Mat - Result matrix C, where C[i,j] = A[i,j]/B[i,j].

Equality check¶

bool operator==(const Mat &A, const Mat &B);

Description:

Checks if the specified matrices are equal.

Parameters:

const Mat &A : First matrix.
const Mat &B : Second matrix.

Returns:

bool - true if equal, false otherwise.