Атрибут C++: nodiscard (начиная с C++17)

Если вызывается функция, объявленная nodiscard, или функция, возвращающая по значению перечисление или класс, объявленные nodiscard, из выражения с отбрасываемым значением, отличного от преобразования к void, компилятору рекомендуется выдать предупреждение.

Синтаксис

`[[nodiscard]]`	(1)	(начиная с C++17)
`[[nodiscard(` строковый литерал `)]]`	(2)	(начиная с C++20)

строковый литерал

невычисляемый строковый литерал, который можно использовать для пояснения причины, по которой результат не следует отбрасывать

Пояснение

Используется в объявлении функции, перечисления или класса.

Если из выражения с отбрасываемым значением, отличного от преобразования к void,

вызывается функция, объявленная nodiscard, или
вызывается функция, возвращающая по значению перечисление или класс, объявленные nodiscard, или
вызывается конструктор, объявленный nodiscard, посредством явного преобразования типа или static_cast, или
объект перечислимого типа или типа класса, объявленного nodiscard, инициализируется посредством явного преобразования типа или static_cast,

компилятору рекомендуется выдать предупреждение.

Указанный строковый литерал обычно включается в предупреждения.

(начиная с C++20)

Пример

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;
}

Возможный вывод:

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

Стандартная библиотека

Следующие функции стандартной библиотеки объявлены с атрибутом nodiscard:

Дополнительное содержимое

Функции выделения памяти
operator newoperator new[]	функции выделения памяти (функция)
allocate	выделяет неинициализированную память (открытая функция-член `std::allocator<T>`)
allocate [static]	выделяет неинициализированную память с использованием аллокатора (открытая статическая функция-член `std::allocator_traits<Alloc>`)
allocate	выделяет память (открытая функция-член `std::pmr::memory_resource`)
allocate	выделяет память (открытая функция-член `std::pmr::polymorphic_allocator<T>`)
allocate	выделяет неинициализированную память с использованием внешнего аллокатора (открытая функция-член `std::scoped_allocator_adaptor<OuterAlloc,InnerAlloc...>`)
Косвенный доступ
launder (C++17)	барьер для оптимизации указателей (шаблон функции)
assume_aligned (C++20)	сообщает компилятору, что указатель выровнен (шаблон функции)
Функции проверки на пустоту
empty (C++17)	проверяет, пуст ли контейнер (шаблон функции)
empty	проверяет, пуст ли дескриптор узла (открытая функция-член `node handle`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::array<T,N>`)
empty	проверяет, пуста ли строка (открытая функция-член `std::basic_string<CharT,Traits,Allocator>`)
empty	проверяет, пусто ли представление (открытая функция-член `std::basic_string_view<CharT,Traits>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::deque<T,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::forward_list<T,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::list<T,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::map<Key,T,Compare,Allocator>`)
empty	проверяет, было ли сопоставление успешным (открытая функция-член `std::match_results<BidirIt,Alloc>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::multimap<Key,T,Compare,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::multiset<Key,Compare,Allocator>`)
empty	проверяет, пуст ли адаптер контейнера (открытая функция-член `std::priority_queue<T,Container,Compare>`)
empty	проверяет, пуст ли адаптер контейнера (открытая функция-член `std::queue<T,Container>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::set<Key,Compare,Allocator>`)
empty	проверяет, пуста ли последовательность (открытая функция-член `std::span<T,Extent>`)
empty	проверяет, пуст ли адаптер контейнера (открытая функция-член `std::stack<T,Container>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::unordered_map<Key,T,Hash,KeyEqual,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::unordered_multimap<Key,T,Hash,KeyEqual,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::unordered_multiset<Key,Hash,KeyEqual,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::unordered_set<Key,Hash,KeyEqual,Allocator>`)
empty	проверяет, пуст ли контейнер (открытая функция-член `std::vector<T,Allocator>`)
empty	проверяет, пуст ли путь (открытая функция-член `std::filesystem::path`)
Разное
async (C++11)	асинхронно выполняет функцию (возможно, в новом потоке) и возвращает `std::future`, в котором будет храниться результат (шаблон функции)

(до C++26)

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были применены задним числом к ранее опубликованным стандартам C++.

DR	Применён к	Опубликованное поведение	Корректное поведение
P1771R1	C++17	`[[nodiscard]]` у конструкторов не действует	может привести к предупреждению, если созданный объект отбрасывается

Ссылки

Стандарт C++23 (ISO/IEC 14882:2024):

9.12.9 Атрибут nodiscard [dcl.attr.nodiscard]

Стандарт C++20 (ISO/IEC 14882:2020):

9.12.8 Атрибут nodiscard [dcl.attr.nodiscard]

Стандарт C++17 (ISO/IEC 14882:2017):

10.6.7 Атрибут nodiscard [dcl.attr.nodiscard]

См. также

ignore (C++11)	заполнитель для пропуска элемента при распаковке `tuple` с помощью `tie` (константа)
Документация C для `nodiscard`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/language/attributes/nodiscard

Атрибут C++: nodiscard (начиная с C++17)

Синтаксис

Пояснение

Пример

Стандартная библиотека

Функции выделения памяти

Косвенный доступ

Функции проверки на пустоту

Разное

Отчёты об ошибках

Ссылки

См. также