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

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

C++ language

 

Declarations

Overview declaration syntax decl-specifier-seq declarator Specifiers typedef inline virtual function specifier explicit function specifier friend constexpr (C++11) consteval (C++20) storage class specifiers classstruct 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-definition 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)

expectsensuresassert (C++20)(C++20)(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]]

Explanation

Appears in a function declaration, enumeration declaration, or class declaration.

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.

Example

Run this code

struct [[nodiscard]] error_info { };
error_info enable_missile_safety_mode();
void launch_missiles();
void test_missiles() {
   enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value
   launch_missiles();
}
error_info& foo();
void f1() {
    foo(); // nodiscard type is not returned by value, no warning
}

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	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	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	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	checks whether the container is empty (public member function of std::unordered_map<Key,T,Hash,KeyEqual,Allocator>)
empty	checks whether the container is empty (public member function of std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>)
empty	checks whether the container is empty (public member function of std::unordered_multiset<Key,Hash,KeyEqual,Allocator>)
empty	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)