Skip to content
Tutorials Center
My learning

Topics

Lesson 158 of 171 ยท Projects

Project: A Small Matrix Library

Build a C++ Matrix class template in four stages - vector storage, operator overloading, size-checking exceptions, assert-based tests, a concept and a std::formatter.

Most C++ projects eventually grow a small library: a set of types that other code uses without thinking about how they work inside. Writing one is different from writing a program. A library has no main of its own to protect it, so it must defend itself against every misuse, behave the way users of the language expect, and come with tests that prove it works. A matrix type is a classic first library, because the math is familiar, operator overloading makes it pleasant to use, and the mistakes (mismatched sizes, slow loops, broken copies) are real.

In this project you'll build Matrix<T> in four stages: storage and element access, arithmetic operators with size checks, multiplication and a test suite with assert, and finally a concept, a custom std::formatter and two applications: Fibonacci numbers via matrix powers, and rotating shapes. Each stage is a complete program containing the whole library so far, because each run starts fresh.

The project draws on class templates, constructors, std::vector, operator overloading, friend functions, the rule of zero, custom exceptions, concepts, assertions and formatting.

What the library should feel like

Design a library from the user's side first. This is the code we want to be able to write by the end:

C++
Matrix<double> a{{1, 2},
                 {3, 4}};
Matrix<double> b = Matrix<double>::identity(2);

auto c = a * b + 2.0 * a;           // reads like the math
if (c == a * 3.0) { /* ... */ }      // compares sizes and values
std::println("{:.2}", c);            // prints with two decimals

Matrix<int> bad{{1, 2}, {3}};        // throws: rows have different lengths
auto oops = a * Matrix<double>(3, 3);  // throws: a 2x2 times a 3x3

That list is the specification. Everything that follows exists to make those lines work, and to make every wrong line fail loudly with a clear message.

Stage 1: storage and element access

Storage. A matrix with rows ร— cols elements could be stored as a std::vector<std::vector<T>>, but that's one heap allocation per row, rows scattered around memory, and nothing stops a row from having the wrong length. Instead, the class stores all elements in one std::vector<T>, row after row (row-major order), plus the two dimensions. Element (r, c) lives at index r * cols + c. One allocation, contiguous memory, and the shape is guaranteed by construction (see Multidimensional Arrays and Matrices).

The rule of zero. Because the only resource is a std::vector, the class needs no destructor, copy constructor, copy assignment, move constructor or move assignment of its own. The compiler-generated versions copy, move and destroy the vector and the two sizes, which is exactly right. That's the rule of zero: let members that already manage resources (RAII types) do the work. Compare that with storing a raw T* from new T[n]: you'd need all five special member functions, written correctly, to avoid leaks and double deletes (see The Rule of Zero, Three and Five).

Constructors. There are two ways to make a matrix:

  • Matrix<int>(2, 3) makes a 2ร—3 matrix of zeros (or of a fill value you pass).
  • Matrix<int>{{1, 2, 3}, {4, 5, 6}} lists the values row by row, using a nested std::initializer_list. The constructor checks that every row has the same length, and throws std::invalid_argument otherwise. A matrix with zero rows or columns is rejected too, since it makes every later operation a special case.

Element access. Like std::vector, the class offers two ways in. m(r, c) is the fast path with no checks, for code that already knows the indices are valid (loops from 0 to rows()). m.at(r, c) checks and throws std::out_of_range. Both come in a const and a non-const version, so you can read from a const Matrix but only write to a mutable one (see const Member Functions). Why operator() rather than operator[]? Until C++23, operator[] could take only one argument. C++23 allows m[r, c], but operator() is what most existing matrix libraries use, and it works everywhere.

Printing. to_string lines up each column to its widest value, and operator<< makes the matrix printable with streams. The demos print with std::println("{}", to_string(m)); stage 4 makes std::println("{}", m) work directly.

C++ Stage 1: storage, constructors and access

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The copy test shows the rule of zero working: changing copy doesn't touch a, because copying the matrix copied its vector. No code was written for that.

Two smaller decisions are worth calling out. The constructor's member initializer list reads values.begin()->size() only when the list isn't empty, because dereferencing begin() of an empty list is undefined behavior. And std::cout and std::println can share the output safely: by default, C++ streams are synchronized with C's standard output, which is what std::println writes to, so lines come out in program order (see I/O Streams in Depth).

Braces pick the initializer_list constructor whenever they can. Matrix<int>{{2, 3}} is a 1ร—2 matrix holding 2 and 3, while Matrix<int>(2, 3) is a 2ร—3 matrix of zeros. It's the same trap as std::vector<int>{2, 3} versus std::vector<int>(2, 3), so the library's examples always use parentheses for sizes.

Stage 2: arithmetic operators and size errors

Operator overloading is about meeting expectations. Users of a matrix type expect a + b, a - b, 2 * a, a * 2, -a and a == b to mean what they mean in math, and a += b to be the efficient in-place version. The canonical way to build that set:

  1. Implement the compound assignments (+=, -=, *= with a scalar) as member functions. They modify *this and return *this by reference, like the built-in operators do.
  2. Implement the binary operators in terms of them: a + b copies a (by taking it by value) and applies += b to the copy. Each piece of arithmetic is written exactly once.
  3. Define the binary operators as hidden friends: friend functions defined inside the class. They aren't members, so 2.0 * a and a * 2.0 are both possible (a member function can't have the scalar on the left). And because they're only found by argument-dependent lookup when a Matrix is involved, they don't clutter overload resolution for unrelated types (see Friend Functions and Classes).

Equality for free. bool operator==(const Matrix&) const = default; (C++20) compares the members in order: rows, then columns, then the vector of values. Different shapes compare unequal, and != comes along automatically. One line, no bugs.

Size mismatches are exceptions. Adding a 2ร—3 to a 3ร—2 matrix is meaningless. The library can't know whether the caller made a programming error or passed bad data from a file, so it reports the problem with an exception the caller can catch, and stays usable afterwards. DimensionError derives from std::invalid_argument, so generic handlers still work, but callers can catch size problems specifically. Its message names both shapes, because "dimension mismatch" alone sends people hunting through their code.

Equality and floating point. Exact == is right for integers and for checking that two computations are the same. For floating-point results of different computations, rounding gets in the way: 0.1 + 0.2 isn't exactly 0.3. The library offers approx_equal, which compares element by element within a tolerance, for those cases (see Floating-Point Numbers).

C++ Stage 2: operators, equality and DimensionError

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Notice that x + x == y is true: doubling is exact in binary floating point, so this particular comparison is safe. The last line shows the case that isn't: 0.1 + 0.2 differs from 0.3 in its last bit, exact equality says false, and approx_equal says true.

A few details:

  • operator+ takes left by value. That copy is the result. If the caller passes a temporary, as in a + b + c (the left side of the second + is the temporary a + b), it's moved in instead of copied, so chains of additions don't copy more than necessary. Returning left += right returns a reference to left, which the compiler then copies or moves into the return value.
  • friend Matrix operator-(Matrix m) is the unary minus. It's implemented as multiplication by T{-1}. That works for signed numbers, but T{-1} doesn't even compile for unsigned types, because brace initialization rejects the narrowing. Stage 4 turns that observation into a rule with a concept.
  • auto nonsense = a + tall; throws before it assigns anything, so nonsense never exists. The compiler doesn't warn about an unused variable here because constructing a Matrix has side effects.

Stage 3: multiplication, transpose and tests

Matrix multiplication is the operation that makes matrices useful: transforming points, chaining transformations, solving systems of equations, and running neural networks. For an mร—n matrix A and an nร—p matrix B, the product is mร—p, and each entry is a dot product of a row of A and a column of B. The inner sizes must match, which is the check that throws DimensionError.

Loop order matters

The textbook loop order is i, j, k: for each result cell, walk along a row of A and down a column of B. Walking down a column of B means jumping cols elements at a time through memory, which uses the CPU cache poorly on large matrices. Swapping the two inner loops to i, k, j gives the same result (each result(i, j) receives the same sum of products, just in a different order), but the innermost loop now walks along rows of both B and the result, touching consecutive memory. For large matrices that's often several times faster, with no change in complexity. It's the simplest example of cache-friendly code (see Writing Fast C++).

identity(n) is a static member function that builds the nร—n identity matrix, and transposed() returns a new matrix with rows and columns swapped. It's a const function that returns a new object, which is why it's named with a past participle: a.transposed() doesn't change a.

Testing with assert

A library needs tests, and the simplest testing tool in C++ is assert from <cassert>. assert(condition) does nothing when the condition is true. When it's false, it prints the condition, file, line and function, then aborts the program. Two rules make asserts useful and safe:

  • Asserts are for bugs, not for user errors. If you compile with -DNDEBUG (as most release builds do), every assert disappears. So the library itself never relies on assert to check its inputs; it throws exceptions, which always run. The tests use assert because a failing test is a bug.
  • Never put necessary work inside an assert. assert(m.load(file)) would skip loading in release builds. Compute first, then assert on the result.

Good tests check properties, not just examples. Besides a hand-computed product, the suite checks identities that must hold for any matrices: A ร— I = A, transposing twice gives back the original, and (AB)แต€ = Bแต€Aแต€. It also checks that errors are errors: the throws<E> helper runs a lambda and reports whether it threw exactly the expected exception type.

C++ Stage 3: multiplication and an assert test suite

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

a * b is 2ร—2, but b * a is 3ร—3. Matrix multiplication isn't commutative, and not even the shapes agree. The test throws<DimensionError>([&] { (void)(a * a); }) confirms that multiplying a 2ร—3 by a 2ร—3 is rejected.

Inside assert, a matrix literal needs extra parentheses: assert(a * b == (Matrix<int>{{58, 64}, {139, 154}})). assert is a macro, and the preprocessor splits macro arguments at commas that aren't inside parentheses. It doesn't understand braces, so without the extra parentheses it would see several "arguments" and fail to compile.

operator*=(const Matrix&) is implemented as *this = *this * other, the reverse of the pattern for addition. In-place multiplication can't overwrite elements of *this while they're still needed for the other entries, so it computes the product into a new matrix and move-assigns it.

What a failing test looks like

It's worth seeing a failure once, so you recognize it. This tiny program contains a deliberately wrong expectation. Running it aborts with a message naming the file, line, function and the exact condition that failed:

C++ A deliberately failing assert

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

You'll see a line like main.cpp:11: int main(): Assertion 'square(4) == 15' failed., and the program is killed by the SIGABRT signal. The line number points you straight at the broken expectation. Notice what you probably don't see: first check passed. When output goes to a pipe or a file (as it does here), stdout is buffered, and abort ends the program without flushing buffers, so text that was "printed" just before a crash can vanish. That's why debugging output belongs on stderr (which is unbuffered), or must be flushed explicitly. Real projects graduate to a test framework (GoogleTest, Catch2, doctest, Boost.Test) for nicer reports and test selection, but the idea is the same.

Stage 4: a concept, a formatter and two applications

Constraining T with a concept

What should Matrix<std::string> mean? Strings support +=, so addition would "work" (it would concatenate), but *= with a scalar and T{1} in identity wouldn't compile, and the errors would point deep inside the class. And Matrix<unsigned> compiles but behaves badly: -a and a - b wrap around to huge numbers instead of going negative.

A concept states the requirement up front: Matrix<T> is for signed integers and floating-point numbers.

C++
template <typename T>
concept Scalar = std::signed_integral<T> || std::floating_point<T>;

template <Scalar T>
class Matrix { /* ... */ };

Now Matrix<unsigned> or Matrix<std::string> fails immediately, at the point of use, with an error that says the constraint Scalar<T> isn't satisfied, instead of a page of template errors from inside operator*=. The concept is also documentation: anyone reading the declaration knows what T can be (see Concepts and Constraints).

A std::formatter for Matrix

Calling to_string(m) everywhere works, but users of a modern C++ library expect std::println("{}", m). That requires a specialization of std::formatter<Matrix<T>> with two member functions:

  • parse reads the format spec between : and }. Ours accepts an optional precision like .3, stores it, and rejects anything else with std::format_error. It's constexpr because std::format checks format strings at compile time: a typo like {:x} becomes a compile error, not a runtime surprise.
  • format writes the matrix to the output, here by calling to_string with the stored precision.

to_string gained a precision parameter: for floating-point elements, {:.{}f} prints that many decimals; integers ignore it.

Application 1: Fibonacci numbers with matrix powers

The matrix [[1, 1], [1, 0]] raised to the power n contains Fibonacci numbers: its top-right entry is F(n). Computing the power by multiplying n times would take n multiplications. Exponentiation by squaring needs only about 2 logโ‚‚ n: square the base repeatedly, and multiply it into the result whenever the current bit of the exponent is 1. F(90) takes 10 matrix multiplications (6 squarings, plus 4 multiplications into the result, one for each 1 bit of 90 = 1011010 in binary) instead of 89. The same trick computes large powers of numbers, and it's used in cryptography.

F(90) = 2,880,067,194,370,816,120, which fits in a long long (the limit is about 9.2 ร— 10ยนโธ). F(93) would overflow, which for a signed integer is undefined behavior, so the demo stops at 90 (see Integer Types).

Application 2: rotating a triangle

A 2ร—2 rotation matrix [[cos ฮธ, โˆ’sin ฮธ], [sin ฮธ, cos ฮธ]] rotates a point around the origin by the angle ฮธ. Store the corners of a shape as the columns of a 2ร—N matrix, and one multiplication rotates them all. Two rotations by 30ยฐ must equal one rotation by 60ยฐ, which approx_equal confirms (exact equality would likely fail, because the two computations round differently).

C++ Stage 4: the finished library

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

F(90) appears in the top-right corner of the result after only 10 multiplications, the triangle's corners are printed with three decimals through the custom formatter, and the two ways of rotating by 60ยฐ agree within the tolerance. Remove the // before Matrix<unsigned> u(2, 2); and run it to see how a concept failure is reported: GCC reports a "template constraint failure" for Matrix and then explains that Scalar<unsigned> evaluated to false.

A note on the tests

The new tests check the formatter's exact output, which is the cheapest way to keep printing code honest: std::format("{:.1}", Matrix<double>{{0.25, 2.0}}) must produce [ 0.2 2.0 ]. (Yes, 0.25 rounds to 0.2. std::format rounds to the nearest representable result, and 0.25 is exactly halfway, so it uses round-half-to-even, the same rule as printf.) Tests like these break the moment someone changes the layout by accident, which is exactly what you want.

Why power counts multiplications through a pointer

int* multiplications = nullptr is an optional output parameter: callers who don't care pass nothing, and the function writes the count only when given somewhere to put it. It's a common C-style pattern. A more modern design would return a small struct with both the matrix and the count, as tic-tac-toe's SearchResult did (see Returning Values). Both are fine for a demo; for a public API, prefer returning a struct.

Ideas to extend it

  • Compile-time sizes. Write FixedMatrix<T, Rows, Cols> with std::array storage and non-type template parameters. Size mismatches in + and * then become compile errors instead of exceptions (see Class Templates).
  • Determinant and inverse. Implement Gaussian elimination with partial pivoting for Matrix<double>, throw an exception for singular matrices, and test that a * inverse(a) is approximately the identity.
  • Mixed types. Allow Matrix<int> * double to produce a Matrix<double> using std::common_type_t<T, U>, constrained with your Scalar concept.
  • C++23 subscripts. Add operator[](std::size_t r, std::size_t c) so users can write m[r, c], the multidimensional subscript operator that C++23 allows.
  • Measure the loop order. Multiply two 300ร—300 matrices with the i-j-k and i-k-j orders, time both with <chrono>, and see the cache effect for yourself (see Dates, Times and Durations with chrono).
  • Row views. Return a std::span<const T> for a row, so std::ranges::max(m.row(1)) works without copying (see std::span).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does Matrix need no destructor, copy constructor or move operations of its own?

    The generated special members act member by member. std::vector handles deep copies, moves and cleanup, so the defaults are exactly right.
  2. 2. What is the shape of Matrix<int>{{2, 3}}?

    Braces prefer the initializer_list constructor, so {{2, 3}} is a list with one row of two values. Use parentheses, Matrix<int>(2, 3), for a 2x3 matrix of zeros.
  3. 3. Why are the binary operators like operator+ and operator* (with a scalar) defined as friend functions inside the class instead of as members?

    For 2 * a, the left operand is a plain number, so the operator can't be a member of Matrix. Defining it as a hidden friend keeps it inside the class and out of unrelated overload sets.
  4. 4. Why is assert(a * b == Matrix<int>{{58, 64}, {139, 154}}); a compile error, while the same line with extra parentheses around the matrix works?

    assert is a macro. To the preprocessor, the commas inside the braces separate macro arguments, so it sees too many arguments. Wrapping the expression in parentheses makes it a single argument.
  5. 5. What happens to the assert-based tests when the program is compiled with -DNDEBUG?

    With NDEBUG defined, assert expands to nothing. Tests should run in builds without NDEBUG, and code that must always validate its inputs should throw exceptions.

Summary

  • Design a library from the user's code first; that code is the specification, including how misuse should fail.
  • Store a matrix in one std::vector<T> in row-major order. The vector manages the memory, so the rule of zero gives correct copies, moves and destruction for free.
  • Offer unchecked operator() for speed and checked at() that throws std::out_of_range, both with const overloads.
  • Implement compound assignments as members and binary operators as hidden friends built on them; = default gives a correct operator==.
  • Report shape mismatches with a specific exception that names both shapes. Compare floating-point results with a tolerance.
  • Prefer cache-friendly loop orders (i-k-j) for multiplication, test both examples and properties with assert, and never rely on assert for input validation.
  • A concept documents and enforces what T may be, and a std::formatter specialization makes std::println("{}", m) work with custom format specs.

Next: Data Structures in C++, where you'll implement dynamic arrays, stacks, queues, linked lists and binary search trees as templates, and learn when the standard library's versions are the better choice.