Static Assertions in Rust

Implementing Compile-Time Checks in Rust with a Simple Macro

20 November 2025

Tags

In C++, we have a useful way to ensure certain conditions are met during compilation. This is called static_assert. Here is an oversimplified example, which should always pass:

constexpr int A = 6;

static_assert(A == 6);

In Rust it's not obvious that we have an equivalent for static_assert out of the box. Of course, we have the assert! macro but there's nothing built-in like a static_assert! or the more fitting const_assert! to use. However, with modern Rust, it’s easy to make an equivalent to use in your projects with a small macro.

The macro code is short and sweet, so let's begin by showing it first:

macro_rules! const_assert {
    ($x:expr) => {
        const _: () = ::core::assert!($x);
    };
}

If you haven't come across const in Rust, it has a different meaning than in C++. You can read more about it here but the main difference is that it usually means "compile-time", while in C++ it means "immutable" or "constant". If the Rust compiler can't evaluate it at compile-time, it throws an error.

Now going back to the macro_rules! part, let me explain this super simple example. First, we define a name for the macro - in this case const_assert:

macro_rules! const_assert

Then we want to define how the arguments are matched and parsed. These are called designators, and they are written in the form of $name:type. So in our case, we are defining $x with a type of expr (short for expression.)

($x:expr) => {

Now that we have an expression, we can substitute it in new code. For our case that's putting it in an assert! but in a const context:

const _: () = ::core::assert!($x);

Macros are a huge topic on their own, and our example here is on the easier side. You can read more about how macro_rules! can be used here if you're curious. If you want to test your skills, try modifying the macro to accept other forms of assert!, e.g. to pass a custom error message.

Let's move back to const_assert!, here's the above example but written in Rust:

const A: i32 = 6;

const_assert!(A == 6);

And it's roughly equivalent to writing this manually:

const A: i32 = 6;

const _: () = assert!(A == 6);

In my opinion, though, the intent isn't as clear in the non-macro version. The nice thing about the macro - and the main draw - is that it looks like an assert! which is an existing language construct that you would already be familiar reading.

And similar to static_assert in C++, the macro can be put in the global scope and also in functions:

const A: i32 = 6;

const B: i32 = 5;

const_assert!(B == 6);

fn main() {
    const_assert!(A == 6);

    println!("{A}");
}

I didn’t create this macro, I stumbled across it while researching static assertions to use in CXX-Qt. I was initially going to pick from one of the many choices of static assertion crates, until I looked at their source code and found a lot of them are identical to the macro I showed above. Since macro_rules! are so easy to integrate, it made sense to vendor it instead of adding another dependency.

There was an issue brought forward to the Rust Library team to add something akin to C++'s static_assert into the standard library. The thread goes over some of the limitations with the method shown here as well. Yet they ultimately decided that having an equivalent in the standard library isn't something they want. I'm not sure if I agree with that decision, but, fortunately, it's easy to add your own.

Tags:

rust

About KDAB

The KDAB Group is a globally recognized provider for software consulting, development and training, specializing in embedded devices and complex cross-platform desktop applications. In addition to being leading experts in Qt, C++ and 3D technologies for over two decades, KDAB provides deep expertise across the stack, including Linux, Rust and modern UI frameworks. With 100+ employees from 20 countries and offices in Sweden, Germany, USA, France and UK, we serve clients around the world.

1 Comment

Const blocks were stabilised already in 1.79 (released in June 2024). See https://github.com/rust-lang/rust/pull/104087/ (the last example in the first post is of a const assert). That is the way to write this nowdays.