Assertions, preconditions and [[assume]]

mark_at(marks, 3) asks a vector of three marks for a fourth, and an assert stops the program before the read, with exit status 134. Assertionsassertion: A check of something the programmer believes must be true, such as assert(i < v.size()): a false one prints the condition, the file and the line, then stops the program. assert disappears from builds that define NDEBUG. state what a programmer believes must be true at a point in the code, and stop the program when it is not. assert(condition) checks while the program runs and disappears completely from builds that define NDEBUGNDEBUG: A macro that most release builds define. Where it is defined before <cassert> is included, assert(anything) expands to ((void)0), so neither the check nor any work inside its condition is left in the program., as most release builds do; static_assert(condition) checks while the program compiles and costs nothing at run time.

Preconditionsprecondition: What a function requires from its callers before it is called, such as an index inside the array. A public function checks its preconditions in every build, because code it does not control can break them. are what a function requires from its callers, such as an index inside the array. Check preconditions at public boundaries, where code you do not control can break them, in every build, by throwing or returning an error, and use assertions for the internal assumptions that only a bug in your own code can break. [[assume]][[assume]]: A C++23 attribute, [[assume(condition)]], that tells the optimiser to treat a condition as true without checking it. If the condition is false while the program runs, the behaviour is undefined, and nothing reports it., new in C++23, tells the optimiser to treat a condition as true without checking it at all.

A failed assert names its condition and stops the program

mark_at asserts that the index is inside the vector. The string after && is always true, so it changes nothing but the message:

#include <cassert>
#include <cstddef>
#include <print>
#include <vector>

double mark_at(const std::vector<double>& marks, std::size_t i) {
    assert(i < marks.size() && "mark_at: index out of range");
    return marks[i];
}

int main() {
    std::vector<double> marks{72.5, 64.0, 91.5};
    std::println("{}", mark_at(marks, 2));
    std::println("{}", mark_at(marks, 3));
}

from session import run

# A failed assert with both compilers: on macOS both use the C library's assert, so the message is the same.
run("""
clang++ -std=c++23 -Wall -Wextra bad_index.cpp -o bad_index && ./bad_index
g++-16 -std=c++23 -Wall -Wextra bad_index.cpp -o bad_index-gcc && ./bad_index-gcc
""")

$ clang++ -std=c++23 -Wall -Wextra bad_index.cpp -o bad_index && ./bad_index
91.5
Assertion failed: (i < marks.size() && "mark_at: index out of range"), function mark_at, file bad_index.cpp, line 7.
Abort trap: 6
[exit status 134]
$ g++-16 -std=c++23 -Wall -Wextra bad_index.cpp -o bad_index-gcc && ./bad_index-gcc
91.5
Assertion failed: (i < marks.size() && "mark_at: index out of range"), function mark_at, file bad_index.cpp, line 7.
Abort trap: 6
[exit status 134]

Step through the two calls, the good index first and then the one past the end:

The first call passes and prints 91.5. The second fails, and assert prints the condition as written, the function, the file and the line, then calls std::abort, so the exit status is 134, 128 plus the number of SIGABRT. The two compilers print the same message because on macOS both use the C library’s assert. A failed assertion means a bug: the program stops at the line where its belief broke, before a wrong value travels further.

NDEBUG removes an assert, and the work inside it

load_settings fills a map and reports whether it could. Calling it inside assert looks like a careful check:

#include <cassert>
#include <map>
#include <print>
#include <string>

// Fills `out` and reports whether it could.
bool load_settings(std::map<std::string, int>& out) {
    out = {{"port", 8080}, {"retries", 3}, {"workers", 8}};
    return true;
}

int main() {
    std::map<std::string, int> settings;
    assert(load_settings(settings));  // the call is inside the assert, so NDEBUG removes it
    std::println("settings loaded: {}", settings.size());
}

from session import run

# The same program as a debug build and as a release build with NDEBUG, with both compilers.
run("""
clang++ -std=c++23 -Wall -Wextra vanishing.cpp -o vanishing && ./vanishing
clang++ -std=c++23 -Wall -Wextra -DNDEBUG vanishing.cpp -o vanishing-release && ./vanishing-release
g++-16 -std=c++23 -Wall -Wextra vanishing.cpp -o vanishing-gcc && ./vanishing-gcc
g++-16 -std=c++23 -Wall -Wextra -DNDEBUG vanishing.cpp -o vanishing-gcc-release && ./vanishing-gcc-release
""")

$ clang++ -std=c++23 -Wall -Wextra vanishing.cpp -o vanishing && ./vanishing
settings loaded: 3
$ clang++ -std=c++23 -Wall -Wextra -DNDEBUG vanishing.cpp -o vanishing-release && ./vanishing-release
settings loaded: 0
$ g++-16 -std=c++23 -Wall -Wextra vanishing.cpp -o vanishing-gcc && ./vanishing-gcc
settings loaded: 3
$ g++-16 -std=c++23 -Wall -Wextra -DNDEBUG vanishing.cpp -o vanishing-gcc-release && ./vanishing-gcc-release
settings loaded: 0

Step through the line in a debug build and in a build with NDEBUG:

The debug builds load 3 settings; the release builds load none. When NDEBUG is defined where <cassert> is included, assert(anything) becomes ((void)0), so its argument is never evaluated, and the call vanished with it. Both compilers built the release programs without a warning, even with -Wall -Wextra, so nothing in the build output points at the missing call.

Checks while compiling cost nothing at run time

A message header must be exactly 8 bytes to match a wire format, and static_assert makes the compiler check it:

#include <cstdint>

// The header of a message on the wire: exactly 8 bytes, in this order.
struct Header {
    std::uint16_t type;
    std::uint32_t length;
    std::uint16_t flags;
};

static_assert(sizeof(Header) == 8, "Header must match the 8-byte wire format");

int main() {}

from session import run

# A static_assert that fails: the program does not compile with either compiler.
run("""
clang++ -std=c++23 -c wire.cpp -o wire.o
g++-16 -std=c++23 -c wire.cpp -o wire-gcc.o
""")

$ clang++ -std=c++23 -c wire.cpp -o wire.o
wire.cpp:10:15: error: static assertion failed due to requirement 'sizeof(Header) == 8': Header must match the 8-byte wire format
   10 | static_assert(sizeof(Header) == 8, "Header must match the 8-byte wire format");
      |               ^~~~~~~~~~~~~~~~~~~
wire.cpp:10:30: note: expression evaluates to '12 == 8'
   10 | static_assert(sizeof(Header) == 8, "Header must match the 8-byte wire format");
      |               ~~~~~~~~~~~~~~~^~~~
1 error generated.
[exit status 1]
$ g++-16 -std=c++23 -c wire.cpp -o wire-gcc.o
wire.cpp:10:30: error: static assertion failed: Header must match the 8-byte wire format
   10 | static_assert(sizeof(Header) == 8, "Header must match the 8-byte wire format");
      |               ~~~~~~~~~~~~~~~^~~~
  • the comparison reduces to '(12 == 8)'
[exit status 1]

Neither compiler builds the program. Both show the values they compared, 12 against 8: the std::uint32_t member must start at a multiple of 4, so 2 bytes of padding follow type, and 2 more follow flags, as the lesson on memory layout, alignment and padding explains. Step through the bytes, as declared and with length moved to the front:

Moving length to the front makes the header 8 bytes. Rule P.5 of the C++ Core Guidelines prefers compile-time checks like this one to run-time checks wherever the condition is known while compiling.

Who can break a condition decides how to check it

Four kinds of check differ in when, if ever, they run:

Preconditions of a public function belong to the third row, because its callers include code you do not control, such as a file a user wrote. The row’s CHECK is a macro that stops the program with a message in every build, an assert that nothing removes. The function’s own internal helpers can rely on assertions, because a broken condition there is a bug in the same code. The standard library follows the same split: its hardened modeshardened standard library: A standard library that checks the preconditions of calls such as operator[] and front() while the program runs, and stops it when one fails, as libc++'s hardening modes and libstdc++ with _GLIBCXX_ASSERTIONS do. C++26 makes such hardened implementations part of the standard. More in “std::vector: the container to reach for first” check its own preconditions, such as the index given to operator[], in release builds too.

[[assume]] belongs to no row of checks at all. The optimiser treats its condition as a fact and may remove code that would only matter if the condition were false; if the condition is false at run time, the behaviour is undefinedundefined behaviour: What a program does when it breaks a rule for which the C++ standard sets no requirements, such as reading past the end of an array. The compiler may assume it never happens, so the result can change with the compiler and the optimisation level. More in “Object lifetime and undefined behaviour in C++”, and nothing reports it.

Practise: put each check where it belongs

Nine questions on the four kinds of check, the idea you have answered least well first, each choice explained.

What [[assume]] changes in the generated code, and what a false one does Pro: opens with a Pro, Premium or Ultimate pass

A precondition policy for every build, with an exercise Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• Assertions check your own beliefs: assert in debug builds, static_assert while compiling, at no run-time cost.
• NDEBUG removes an assert and everything inside it, so never put work in its condition.
• Check preconditions at public boundaries in every build, and report them to the caller as errors.
• [[assume]] is a promise, never a check: when it is false, the behaviour is undefined.