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

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,

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

Standard library The following standard functions are declared with nodiscard attribute: Extended content Allocation functions operator newoperator new[] allocation functions (function) [edit] allocate allocates uninitialized storage (public member function of std::allocator) [edit] allocate[static] allocates uninitialized storage using the allocator (public static member function of std::allocator_traits) [edit] allocate allocates memory (public member function of std::pmr::memory_resource) [edit] allocate allocate memory (public member function of std::pmr::polymorphic_allocator) [edit] allocate allocates uninitialized storage using the outer allocator (public member function of std::scoped_allocator_adaptor<OuterAlloc,InnerAlloc...>) [edit] Indirect access launder(C++17) pointer optimization barrier (function template) [edit] assume_aligned(C++20) informs the compiler that a pointer is aligned (function template) [edit] Emptiness-checking functions empty(C++17) checks whether the container is empty (function template) [edit] empty checks whether the node handle is empty(public member function of node handle) empty checks whether the container is empty (public member function of std::array<T,N>) [edit] empty checks whether the string is empty (public member function of std::basic_string<CharT,Traits,Allocator>) [edit] empty checks whether the view is empty (public member function of std::basic_string_view<CharT,Traits>) [edit] empty checks whether the container is empty (public member function of std::deque<T,Allocator>) [edit] empty checks whether the container is empty (public member function of std::forward_list<T,Allocator>) [edit] empty checks whether the container is empty (public member function of std::list<T,Allocator>) [edit] empty checks whether the container is empty (public member function of std::map<Key,T,Compare,Allocator>) [edit] empty checks whether the match was successful (public member function of std::match_results<BidirIt,Alloc>) [edit] empty checks whether the container is empty (public member function of std::multimap<Key,T,Compare,Allocator>) [edit] empty checks whether the container is empty (public member function of std::multiset<Key,Compare,Allocator>) [edit] empty checks whether the container adaptor is empty (public member function of std::priority_queue<T,Container,Compare>) [edit] empty checks whether the container adaptor is empty (public member function of std::queue<T,Container>) [edit] empty checks whether the container is empty (public member function of std::set<Key,Compare,Allocator>) [edit] empty checks if the sequence is empty (public member function of std::span<T,Extent>) [edit] empty checks whether the container adaptor is empty (public member function of std::stack<T,Container>) [edit] empty checks whether the container is empty (public member function of std::unordered_map<Key,T,Hash,KeyEqual,Allocator>) [edit] empty checks whether the container is empty (public member function of std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>) [edit] empty checks whether the container is empty (public member function of std::unordered_multiset<Key,Hash,KeyEqual,Allocator>) [edit] empty checks whether the container is empty (public member function of std::unordered_set<Key,Hash,KeyEqual,Allocator>) [edit] empty checks whether the container is empty (public member function of std::vector<T,Allocator>) [edit] empty checks if the path is empty (public member function of std::filesystem::path) [edit] 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) [edit] (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

[edit] See also