[libc++] Add _LIBCPP_ENABLE_NODISCARD and _LIBCPP_NODISCARD_EXT to allow pre-C++2a [[nodiscard]]

Summary:
The `[[nodiscard]]` attribute is intended to help users find bugs where
function return values are ignored when they shouldn't be. After C++17 the
C++ standard has started to declared such library functions as `[[nodiscard]]`.
However, this application is limited and applies only to dialects after C++17.
Users who want help diagnosing misuses of STL functions may desire a more
liberal application of `[[nodiscard]]`.

For this reason libc++ provides an extension that does just that! The
extension must be enabled by defining `_LIBCPP_ENABLE_NODISCARD`. The extended
applications of `[[nodiscard]]` takes two forms:

1. Backporting `[[nodiscard]]` to entities declared as such by the
   standard in newer dialects, but not in the present one.

2. Extended applications of `[[nodiscard]]`, at the libraries discretion,
   applied to entities never declared as such by the standard.

Users may also opt-out of additional applications `[[nodiscard]]` using
additional macros.

Applications of the first form, which backport `[[nodiscard]]` from a newer
dialect may be disabled using macros specific to the dialect it was added. For
example `_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17`.

Applications of the second form, which are pure extensions, may be disabled
by defining `_LIBCPP_DISABLE_NODISCARD_EXT`.

This patch was originally written by me (Roman Lebedev),
then but then reworked by Eric Fiselier.

Reviewers: mclow.lists, thakis, EricWF

Reviewed By: thakis, EricWF

Subscribers: llvm-commits, mclow.lists, lebedev.ri, EricWF, rjmccall, Quuxplusone, cfe-commits, christof

Differential Revision: https://reviews.llvm.org/D45179

git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@342808 91177308-0d34-0410-b5e6-96231b3b80d8

test/libcxx/diagnostics/enable_nodiscard.fail.cpp

@@ -0,0 +1,33 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// Test that _LIBCPP_NODISCARD_EXT and _LIBCPP_NODISCARD_AFTER_CXX17 are defined
+// to the appropriate warning-generating attribute when _LIBCPP_ENABLE_NODISCARD
+// is explicitly provided.
+
+// UNSUPPORTED: c++98, c++03
+
+// GCC 7 is the first version to introduce [[nodiscard]]
+// UNSUPPORTED: gcc-4.9, gcc-5, gcc-6
+
+// MODULES_DEFINES: _LIBCPP_ENABLE_NODISCARD
+#define _LIBCPP_ENABLE_NODISCARD
+
+#include <__config>
+
+_LIBCPP_NODISCARD_EXT int foo() { return 42; }
+_LIBCPP_NODISCARD_AFTER_CXX17 int bar() { return 42; }
+
+int main() {
+  foo(); // expected-error-re {{ignoring return value of function declared with {{'nodiscard'|warn_unused_result}} attribute}}
+  bar(); // expected-error-re {{ignoring return value of function declared with {{'nodiscard'|warn_unused_result}} attribute}}
+  (void)foo(); // OK. void casts disable the diagnostic.
+  (void)bar();
+}

test/libcxx/diagnostics/enable_nodiscard_disable_after_cxx17.fail.cpp

@@ -0,0 +1,33 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++98, c++03
+
+// GCC 7 is the first version to introduce [[nodiscard]]
+// UNSUPPORTED: gcc-4.9, gcc-5, gcc-6
+
+// Test that _LIBCPP_DISABLE_NODISCARD_EXT only disables _LIBCPP_NODISCARD_EXT
+// and not _LIBCPP_NODISCARD_AFTER_CXX17.
+
+// MODULES_DEFINES: _LIBCPP_ENABLE_NODISCARD
+// MODULES_DEFINES: _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
+#define _LIBCPP_ENABLE_NODISCARD
+#define _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
+#include <__config>
+
+
+_LIBCPP_NODISCARD_EXT int foo() { return 42; }
+_LIBCPP_NODISCARD_AFTER_CXX17 int bar() { return 42; }
+
+int main() {
+  foo(); // expected-error-re {{ignoring return value of function declared with {{'nodiscard'|warn_unused_result}} attribute}}
+  bar(); // OK.
+  (void)foo(); // OK.
+}

test/libcxx/diagnostics/enable_nodiscard_disable_nodiscard_ext.fail.cpp

@@ -0,0 +1,31 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++98, c++03
+
+// GCC 7 is the first version to introduce [[nodiscard]]
+// UNSUPPORTED: gcc-4.9, gcc-5, gcc-6
+
+
+// MODULES_DEFINES: _LIBCPP_ENABLE_NODISCARD
+// MODULES_DEFINES: _LIBCPP_DISABLE_NODISCARD_EXT
+#define _LIBCPP_ENABLE_NODISCARD
+#define _LIBCPP_DISABLE_NODISCARD_EXT
+#include <__config>
+
+
+_LIBCPP_NODISCARD_EXT int foo() { return 42; }
+_LIBCPP_NODISCARD_AFTER_CXX17 int bar() { return 42; }
+
+int main() {
+  bar(); // expected-error-re {{ignoring return value of function declared with {{'nodiscard'|warn_unused_result}} attribute}}
+  foo(); // OK.
+  (void)bar(); // OK.
+}

test/libcxx/diagnostics/nodiscard.pass.cpp

@@ -8,18 +8,13 @@
 //
 //===----------------------------------------------------------------------===//
 
-// Test that _LIBCPP_NODISCARD_AFTER_CXX17 works
-//	#define _LIBCPP_NODISCARD_AFTER_CXX17 [[nodiscard]]
+// Test that _LIBCPP_NODISCARD_EXT is not defined to [[nodiscard]] unless
+// explicitly enabled by _LIBCPP_ENABLE_NODISCARD
 
-// UNSUPPORTED: c++98, c++03, c++11, c++14
-
-// MODULES_DEFINES: _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
-#define _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
 #include <__config>
 
-_LIBCPP_NODISCARD_AFTER_CXX17 int foo() { return 6; }
+_LIBCPP_NODISCARD_EXT int foo() { return 42; }
 
-int main ()
-{
-	foo();	// no error here!
+int main() {
+  foo(); // OK.
 }

test/libcxx/diagnostics/nodiscard_aftercxx17.fail.cpp

@@ -12,7 +12,6 @@
 //	#define _LIBCPP_NODISCARD_AFTER_CXX17 [[nodiscard]]
 
 // UNSUPPORTED: c++98, c++03, c++11, c++14, c++17
-// UNSUPPORTED: clang-3.3, clang-3.4, clang-3.5, clang-3.6, clang-3.7, clang-3.8
 
 #include <__config>
 

test/libcxx/diagnostics/nodiscard_aftercxx17.pass.cpp

@@ -0,0 +1,23 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// Test that _LIBCPP_NODISCARD_AFTER_CXX17 is disabled whenever
+// _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17 is defined by the user.
+
+// MODULES_DEFINES: _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
+#define _LIBCPP_DISABLE_NODISCARD_AFTER_CXX17
+#include <__config>
+
+_LIBCPP_NODISCARD_AFTER_CXX17 int foo() { return 6; }
+
+int main ()
+{
+	foo();	// no error here!
+}

test/libcxx/diagnostics/nodiscard_extensions.fail.cpp

@@ -0,0 +1,32 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++98, c++03
+
+// Test that entities declared [[nodiscard]] as at extension by libc++, are
+// only actually declared such when _LIBCPP_ENABLE_NODISCARD is specified.
+
+// All entities to which libc++ applies [[nodiscard]] as an extension should
+// be tested here and in nodiscard_extensions.pass.cpp. They should also
+// be listed in `UsingLibcxx.rst` in the documentation for the extension.
+
+// MODULES_DEFINES: _LIBCPP_ENABLE_NODISCARD
+#define _LIBCPP_ENABLE_NODISCARD
+
+#include <memory>
+
+#include "test_macros.h"
+
+int main() {
+  {
+    // expected-error-re@+1 {{ignoring return value of function declared with {{'nodiscard'|warn_unused_result}} attribute}}
+    std::get_temporary_buffer<int>(1);
+  }
+}

test/libcxx/diagnostics/nodiscard_extensions.pass.cpp

@@ -0,0 +1,26 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is dual licensed under the MIT and the University of Illinois Open
+// Source Licenses. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+// Test that entities declared [[nodiscard]] as at extension by libc++, are
+// only actually declared such when _LIBCPP_ENABLE_NODISCARD is specified.
+
+// All entities to which libc++ applies [[nodiscard]] as an extension should
+// be tested here and in nodiscard_extensions.fail.cpp. They should also
+// be listed in `UsingLibcxx.rst` in the documentation for the extension.
+
+#include <memory>
+
+#include "test_macros.h"
+
+int main() {
+  {
+    std::get_temporary_buffer<int>(1);
+  }
+}