C++ attribute: assume (since C++23)

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Diagnostics library

Memory management library

Metaprogramming library (C++11)

General utilities library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library (C++17)

Concurrency support library (C++11)

Execution control library (C++26)

Technical specifications

Symbols index

External libraries

 

C++ language

General topics
Preprocessor Comments	Keywords Escape sequences
Flow control
Conditional execution statements
if	switch
Iteration statements (loops)
for range-for (C++11)	while do-while
Jump statements
continue - break	goto - return
Functions
Function declaration
Lambda function expression
inline specifier
Dynamic exception specifications (until C++17*)
noexcept specifier (C++11)
Exceptions
throw-expression try block	catch handler
Namespaces
Namespace declaration	Namespace aliases
Types
Fundamental types Enumeration types Function types	Class/struct types Union types
Specifiers
const/volatile decltype (C++11) auto (C++11)	constexpr (C++11) consteval (C++20) constinit (C++20)
Storage duration specifiers
Initialization
Default-initialization Value-initialization Zero-initialization Copy-initialization Direct-initialization	Aggregate initialization List-initialization (C++11)   Constant initialization Reference initialization

Expressions
Value categories Order of evaluation	Operators Operator precedence
Alternative representations
Literals
Boolean - Integer - Floating-point
Character - String - nullptr (C++11)
User-defined (C++11)
Utilities
Attributes (C++11)
Types
typedef declaration
Type alias declaration (C++11)
Casts
Implicit conversions static_cast const_cast	Explicit conversions dynamic_cast reinterpret_cast
Memory allocation
new expression	delete expression
Classes
Class declaration Constructors this pointer	Access specifiers friend specifier
Class-specific function properties
Virtual function override specifier (C++11)   final specifier (C++11)	explicit (C++11) static
Special member functions
Default constructor Copy constructor Move constructor (C++11)	Copy assignment Move assignment (C++11) Destructor
Templates
Class template Function template	Template specialization Parameter packs (C++11)
Miscellaneous
Inline assembly	History of C++

 

Declarations

Overview Declaration syntax decl-specifier-seq Declarator Conflicting declarations Specifiers typedef inline virtual function specifier explicit function specifier friend constexpr (C++11) consteval (C++20) constinit (C++20) Storage class specifiers Translation-unit-local (C++20) class/struct union enum decltype (C++11) auto (C++11) alignas (C++11) constvolatile Pack indexing specifier (C++26)     Elaborated type specifier Attributes (C++11)

Declarators Reference Pointer Array Block declarations Simple-declaration   →Structured binding declaration (C++17) Alias declaration (C++11) Namespace alias definition using declaration using directive static_assert declaration (C++11) asm declaration Opaque enum declaration (C++11) Other declarations Namespace definition Function declaration Class template declaration Function template declaration Explicit template instantiation (C++11) Explicit template specialization Linkage specification Attribute declaration (C++11) Empty declaration

 

Attributes

assume (C++23)

carries_dependency (C++11)(until C++26)

deprecated (C++14)

fallthrough (C++17)

indeterminate (C++26)

likely (C++20)

maybe_unused (C++17)

nodiscard (C++17)

noreturn (C++11)

no_unique_address (C++20)

optimize_for_synchronized (TM TS)

unlikely (C++20)

 

Specifies that the given expression is assumed to always evaluate to true at a given point in order to allow compiler optimizations based on the information given.

Syntax

[[assume( expression )]]

expression

-

any expression (except unparenthesized comma expressions)

Explanation

[[assume]] an only be applied to a null statement, as in [[assume(x > 0)]];. This statement is called an assumption.

expression is contextually converted to bool, but it is not evaluated (it is still potentially evaluated).

• If the converted expression would evaluate to true at the point where the assumption appears, the assumption has no effect.
• Otherwise, evaluation of the assumption has runtime-undefined behavior.

Notes

Since assumptions cause runtime-undefined behavior if they do not hold, they should be used sparingly.

One correct way to use them is to follow assertions with assumptions:

assert(x > 0);     // trigger an assertion when NDEBUG is not defined and x > 0 is false
[[assume(x > 0)]]; // provide optimization opportunities when NDEBUG is defined

Example

#include <cmath>

void f(int& x, int y)
{
    void g(int);
    void h();
    
    [[assume(x > 0)]]; // Compiler may assume x is positive
    
    g(x / 2); // More efficient code possibly generated
    
    x = 3;
    int z = x;
    
    [[assume((h(), x == z))]]; // Compiler may assume x would have the same value after
                               // calling h
                               // The assumption does not cause a call to h
    
    h();
    g(x); // Compiler may replace this with g(3);
    
    h();
    g(x); // Compiler may NOT replace this with g(3);
          // An assumption applies only at the point where it appears
    
    z = std::abs(y);
    
    [[assume((g(z), true))]]; // Compiler may assume g(z) will return
    
    g(z); // Due to above and below assumptions, compiler may replace this with g(10);
    
    [[assume(y == -10)]]; // Undefined behavior if y != -10 at this point
    
    [[assume((x - 1) * 3 == 12)]];
    
    g(x); // Compiler may replace this with g(5);
}

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
CWG 2924	C++23	violating an assumption would result in undefined behavior	results in runtime-undefined behavior

References

• C++23 standard (ISO/IEC 14882:2024):

• 9.12.3 Assumption attribute [dcl.attr.assume]

See also

unreachable (C++23)	marks unreachable point of execution (function)
contract_assert statement (C++26)	verifies an internal condition during execution

External links

1.	Clang language extensions doc: __builtin_assume.
2.	Clang attribute reference doc: assume.
3.	MSVC doc: __assume built-in.
4.	GCC doc: __attribute__((assume(...))).