static-assert.md

description	title	ms.date	f1_keywords	helpviewer_keywords	ms.assetid
Learn more about: static_assert	static_assert	07/29/2019	static_assert_cpp	assertions [C++], static_assert static_assert	28dd3668-e78c-4de8-ba68-552084743426

static_assert

Tests a software assertion at compile time. If the specified constant expression is false, the compiler displays the specified message, if one is provided, and the compilation fails with error C2338; otherwise, the declaration has no effect.

Syntax

static_assert( constant-expression, string-literal ); static_assert( constant-expression ); // C++17 (Visual Studio 2017 and later) 

Parameters

constant-expression
An integral constant expression that can be converted to a Boolean. If the evaluated expression is zero (false), the string-literal parameter is displayed and the compilation fails with an error. If the expression is nonzero (true), the static_assert declaration has no effect.

string-literal
A message that is displayed if the constant-expression parameter is zero. The message is a string of characters in the base character set of the compiler; that is, not multibyte or wide characters.

Remarks

The constant-expression parameter of a static_assert declaration represents a software assertion. A software assertion specifies a condition that you expect to be true at a particular point in your program. If the condition is true, the static_assert declaration has no effect. If the condition is false, the assertion fails, the compiler displays the message in string-literal parameter, and the compilation fails with an error. In Visual Studio 2017 and later, the string-literal parameter is optional.

The static_assert declaration tests a software assertion at compile time. In contrast, the assert Macro and _assert and _wassert functions test a software assertion at run time and incur a run time cost in space or time. The static_assert declaration is especially useful for debugging templates because template arguments can be included in the constant-expression parameter.

The compiler examines the static_assert declaration for syntax errors when the declaration is encountered. The compiler evaluates the constant-expression parameter immediately if it does not depend on a template parameter. Otherwise, the compiler evaluates the constant-expression parameter when the template is instantiated. Consequently, the compiler might issue a diagnostic message once when the declaration is encountered, and again when the template is instantiated.

You can use the static_assert keyword at namespace, class, or block scope. (The static_assert keyword is technically a declaration, even though it does not introduce new name into your program, because it can be used at namespace scope.)

Description of static_assert with namespace scope

In the following example, the static_assert declaration has namespace scope. Because the compiler knows the size of type void *, the expression is evaluated immediately.

Example: static_assert with namespace scope

static_assert(sizeof(void *) == 4, "64-bit code generation is not supported.");

Description of static_assert with class scope

In the following example, the static_assert declaration has class scope. The static_assert verifies that a template parameter is a plain old data (POD) type. The compiler examines the static_assert declaration when it is declared, but does not evaluate the constant-expression parameter until the basic_string class template is instantiated in main().

Example: static_assert with class scope

#include<type_traits> #include<iosfwd>namespacestd { template <classCharT, classTraits = std::char_traits<CharT> > classbasic_string { static_assert(std::is_pod<CharT>::value, "Template argument CharT must be a POD type in class template basic_string"); // ... }; } structNonPOD { NonPOD(const NonPOD &) {} virtual~NonPOD() {} }; intmain() { std::basic_string<char> bs; }

Description of static_assert with block scope

In the following example, the static_assert declaration has block scope. The static_assert verifies that the size of the VMPage structure is equal to the virtual memory pagesize of the system.

Example: static_assert at block scope

#include<sys/param.h>// defines PAGESIZEclassVMMClient { public:structVMPage { // ... }; intcheck_pagesize() { static_assert(sizeof(VMPage) == PAGESIZE, "Struct VMPage must be the same size as a system virtual memory page."); // ... } // ... };

See also

Assertion and User-Supplied Messages (C++)
#error Directive (C/C++)
assert Macro, _assert, _wassert
Templates
ASCII Character Set
Declarations and Definitions