C++ attribute: nodiscard (since C++17)
From cppreference.com
< cpp | language | attributes
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
C++ language
Flow control
Conditional execution statements
Iteration statements (loops)
Jump statements
Functions
Function declaration
Lambda function expression
Dynamic exception specifications (until C++17*)
Exceptions
Namespaces
Types
Specifiers
Storage duration specifiers
Initialization
Alternative representations
Literals
Boolean - Integer - Floating-point
Character - String - nullptr (C++11)
User-defined (C++11)
Utilities
Attributes (C++11)
Types
Type alias declaration (C++11)
Casts
Memory allocation
Classes
Class-specific function properties
Special member functions
Templates
Miscellaneous
General topics
inline
specifier noexcept
specifier (C++11)typedef
declaration Declarations
Overview
Specifiers
(C++11)
(C++20)
(C++20)
Translation-unit-local (C++20)
(C++11)
(C++11)
(C++11)
Pack indexing specifier (C++26)
Attributes (C++11)
Declarators
Block declarations
→Structured binding declaration (C++17)
Alias declaration (C++11)
static_assert declaration (C++11)
Opaque enum declaration (C++11)
Other declarations
Explicit template instantiation (C++11)
Attribute declaration (C++11)
Attributes
(C++23)
(C++11)(until C++26)
(C++14)
(C++17)
(C++26)
(C++20)
(C++17)
nodiscard
(C++17)
(C++11)
(C++20)
(TM TS)
(C++20)
If a function declared nodiscard
or a function returning an enumeration or class declared nodiscard
by value is called from a discarded-value expression other than a cast to void, the compiler is encouraged to issue a warning.
Contents
[edit] Syntax
[[nodiscard]]
(1)
(since C++17)
[[nodiscard(
string-literal )]]
(2)
(since C++20)
string-literal
-
an unevaluated string literal that could be used to explain the rationale for why the result should not be discarded
[edit] Explanation
Appears in a function declaration, enumeration declaration, or class declaration.
If, from a discarded-value expression other than a cast to void,
- a function declared
nodiscard
is called, or - a function returning an enumeration or class declared
nodiscard
by value is called, or - a constructor declared
nodiscard
is called by explicit type conversion or static_cast, or - an object of an enumeration or class type declared
nodiscard
is initialized by explicit type conversion or static_cast,
the compiler is encouraged to issue a warning.
The string-literal, if specified, is usually included in the warnings.
(since C++20)[edit] Example
Run this code
struct [[nodiscard]] error_info { /*...*/ }; error_info enable_missile_safety_mode() { /*...*/ return {}; } void launch_missiles() { /*...*/ } void test_missiles() { enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value launch_missiles(); } error_info& foo() { static error_info e; /*...*/ return e; } void f1() { foo(); } // nodiscard type is not returned by value, no warning // nodiscard( string-literal ) (since C++20): [[nodiscard("PURE FUN")]] int strategic_value(int x, int y) { return x ^ y; } int main() { strategic_value(4, 2); // compiler may warn on discarding a nodiscard value auto z = strategic_value(0, 0); // OK: return value is not discarded return z; }
Possible output:
game.cpp:5:4: warning: ignoring return value of function declared with ⮠ 'nodiscard' attribute game.cpp:17:5: warning: ignoring return value of function declared with ⮠ 'nodiscard' attribute: PURE FUN
Standard libraryThe following standard functions are declared with
|
(until C++26) |
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
P1771R1 | C++17 | [[nodiscard]] on constructors has no effect
|
can cause a warning if the constructed object is discarded |
[edit] References
- C++23 standard (ISO/IEC 14882:2024):
- 9.12.9 Nodiscard attribute [dcl.attr.nodiscard]
- C++20 standard (ISO/IEC 14882:2020):
- 9.12.8 Nodiscard attribute [dcl.attr.nodiscard]
- C++17 standard (ISO/IEC 14882:2017):
- 10.6.7 Nodiscard attribute [dcl.attr.nodiscard]
[edit] See also
C documentation for nodiscard