C++ attribute: nodiscard (since C++17)

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

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++20)
noexcept specifier (C++11)
Exceptions
throw-expression	try-catch block
Namespaces
Namespace declaration	Namespace aliases
Types
Fundamental types Enumeration types Function types	Class/struct types Union types
Specifiers
decltype (C++11) auto (C++11) alignas (C++11)	const/volatile constexpr (C++11)
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 - Explicit conversions
static_cast - dynamic_cast
const_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 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 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

noreturn‎ (C++11)

carries_dependency (C++11)

deprecated (C++14)

fallthrough (C++17)

nodiscard (C++17)

maybe_unused (C++17)

likelyunlikely (C++20)(C++20)

no_unique_address (C++20)

optimize_for_synchronized (TM TS)

 

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.

Syntax

[[nodiscard]]	(1)
[[nodiscard( string-literal )]]	(2)	(since C++20)

string-literal

-

text that could be used to explain the rationale for why the result should not be discarded

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)

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 library

The following standard functions are declared with nodiscard attribute:

Allocation functions
operator newoperator new[]	allocation functions (function)
allocate	allocates uninitialized storage (public member function of std::allocator<T>)
allocate [static]	allocates uninitialized storage using the allocator (public static member function of std::allocator_traits<Alloc>)
allocate	allocates memory (public member function of std::pmr::memory_resource)
allocate	Allocate memory (public member function of std::pmr::polymorphic_allocator<T>)
allocate	allocates uninitialized storage using the outer allocator (public member function of std::scoped_allocator_adaptor<OuterAlloc,InnerAlloc...>)
Indirect access
launder (C++17)	pointer optimization barrier (function template)
assume_aligned (C++20)	informs the compiler that a pointer is aligned (function template)
Emptiness-checking functions
empty (C++17)	checks whether the container is empty (function template)
empty	checks whether the node handle is empty (public member function of node handle)
empty (C++11)	checks whether the container is empty (public member function of std::array<T,N>)
empty	checks whether the string is empty (public member function of std::basic_string<CharT,Traits,Allocator>)
empty (C++17)	checks whether the view is empty (public member function of std::basic_string_view<CharT,Traits>)
empty	checks whether the container is empty (public member function of std::deque<T,Allocator>)
empty (C++11)	checks whether the container is empty (public member function of std::forward_list<T,Allocator>)
empty	checks whether the container is empty (public member function of std::list<T,Allocator>)
empty	checks whether the container is empty (public member function of std::map<Key,T,Compare,Allocator>)
empty	checks whether the match was successful (public member function of std::match_results<BidirIt,Alloc>)
empty	checks whether the container is empty (public member function of std::multimap<Key,T,Compare,Allocator>)
empty	checks whether the container is empty (public member function of std::multiset<Key,Compare,Allocator>)
empty	checks whether the underlying container is empty (public member function of std::priority_queue<T,Container,Compare>)
empty	checks whether the underlying container is empty (public member function of std::queue<T,Container>)
empty	checks whether the container is empty (public member function of std::set<Key,Compare,Allocator>)
empty	checks if the sequence is empty (public member function of std::span<T,Extent>)
empty	checks whether the underlying container is empty (public member function of std::stack<T,Container>)
empty (C++11)	checks whether the container is empty (public member function of std::unordered_map<Key,T,Hash,KeyEqual,Allocator>)
empty (C++11)	checks whether the container is empty (public member function of std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>)
empty (C++11)	checks whether the container is empty (public member function of std::unordered_multiset<Key,Hash,KeyEqual,Allocator>)
empty (C++11)	checks whether the container is empty (public member function of std::unordered_set<Key,Hash,KeyEqual,Allocator>)
empty	checks whether the container is empty (public member function of std::vector<T,Allocator>)
empty	checks if the path is empty (public member function of std::filesystem::path)
Miscellaneous
async (C++11)	runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result (function template)

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