Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | language‎ | attributes
 
 
C++ language
General topics
Flow control
Conditional execution statements
if
Iteration statements (loops)
for
range-for (C++11)
Jump statements
Functions
Function declaration
Lambda function expression
inline specifier
Dynamic exception specifications (until C++17*)
noexcept specifier (C++11)
Exceptions
Namespaces
Types
Specifiers
decltype (C++11)
auto (C++11)
alignas (C++11)
Storage duration specifiers
Initialization
Expressions
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
Classes
Class-specific function properties
explicit (C++11)
static
Special member functions
Templates
Miscellaneous
 
 
Attributes
(C++14)
nodiscard
(C++17)
(C++20)(C++20)
(C++23)
 

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)
[[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,

the compiler is encouraged to issue a warning.

The string-literal, if specified, is usually included in the warnings.

(since C++20)

[edit] Example

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

[edit] Standard library

The following standard functions are declared with nodiscard attribute:

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

[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] See also

(C++11)
placeholder to skip an element when unpacking a tuple using tie
(constant) [edit]
C documentation for nodiscard