[libc++][format] Make public functions nodiscard.

This is an extension and only adds the functions that are a considered a
but when called and ignoring the result.

Drive-by sort all nodiscard extensions in the documentation.

Reviewed By: #libc, philnik

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

Author: mordante

libcxx/docs/UsingLibcxx.rst

@@ -380,41 +380,63 @@ which no dialect declares as such (See the second form described above).
 * ``adjacent_find``
 * ``all_of``
 * ``any_of``
+* ``as_const``
 * ``binary_search``
+* ``bit_cast``
+* ``cbrt``
+* ``ceil``
 * ``clamp``
+* ``copysign``
 * ``count_if``
 * ``count``
 * ``equal_range``
 * ``equal``
+* ``fabs``
 * ``find_end``
 * ``find_first_of``
 * ``find_if_not``
 * ``find_if``
 * ``find``
+* ``floor``
+* ``fmax``
+* ``fmin``
+* ``forward``
+* ``fpclassify``
 * ``get_temporary_buffer``
+* ``identity::operator()``
 * ``includes``
 * ``is_heap_until``
 * ``is_heap``
 * ``is_partitioned``
 * ``is_permutation``
 * ``is_sorted_until``
 * ``is_sorted``
+* ``isfinite``
+* ``isgreater``
+* ``isgreaterequal``
+* ``isinf``
+* ``isless``
+* ``islessequal``
+* ``islessgreater``
+* ``isnan``
+* ``isnormal``
+* ``isunordered``
 * ``lexicographical_compare``
+* ``lock_guard``'s constructors
 * ``lower_bound``
+* ``make_format_args``
+* ``make_wformat_args``
 * ``max_element``
 * ``max``
 * ``min_element``
 * ``min``
 * ``minmax_element``
 * ``minmax``
 * ``mismatch``
+* ``move_if_noexcept``
+* ``move``
+* ``nearbyint``
 * ``none_of``
-* ``remove_if``
-* ``remove``
-* ``search_n``
-* ``search``
-* ``unique``
-* ``upper_bound``
 * ``ranges::adjacent_find``
 * ``ranges::all_of``
 * ``ranges::any_of``
@@ -453,38 +475,19 @@ which no dialect declares as such (See the second form described above).
 * ``ranges::search``
 * ``ranges::unique``
 * ``ranges::upper_bound``
-* ``lock_guard``'s constructors
-* ``as_const``
-* ``bit_cast``
-* ``forward``
-* ``move``
-* ``move_if_noexcept``
-* ``identity::operator()``
-* ``to_integer``
-* ``to_underlying``
-* ``signbit``
-* ``fpclassify``
-* ``isfinite``
-* ``isinf``
-* ``isnan``
-* ``isnormal``
-* ``isgreater``
-* ``isgreaterequal``
-* ``isless``
-* ``islessequal``
-* ``islessgreater``
-* ``isunordered``
-* ``ceil``
-* ``fabs``
-* ``floor``
-* ``cbrt``
-* ``copysign``
-* ``fmax``
-* ``fmin``
-* ``nearbyint``
+* ``remove_if``
+* ``remove``
 * ``rint``
 * ``round``
+* ``search_n``
+* ``search``
+* ``signbit``
+* ``to_integer``
+* ``to_underlying``
 * ``trunc``
+* ``unique``
+* ``upper_bound``
+* ``vformat``
 
 Extended integral type support
 ------------------------------

libcxx/include/__format/format_functions.h

@@ -65,16 +65,17 @@ using wformat_args = basic_format_args<wformat_context>;
 #endif
 
 template <class _Context = format_context, class... _Args>
-_LIBCPP_HIDE_FROM_ABI __format_arg_store<_Context, _Args...> make_format_args(_Args&&... __args) {
+_LIBCPP_NODISCARD_EXT _LIBCPP_HIDE_FROM_ABI __format_arg_store<_Context, _Args...> make_format_args(_Args&&... __args) {
   return _VSTD::__format_arg_store<_Context, _Args...>(__args...);
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#  ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 template <class... _Args>
-_LIBCPP_HIDE_FROM_ABI __format_arg_store<wformat_context, _Args...> make_wformat_args(_Args&&... __args) {
+_LIBCPP_NODISCARD_EXT _LIBCPP_HIDE_FROM_ABI __format_arg_store<wformat_context, _Args...>
+make_wformat_args(_Args&&... __args) {
   return _VSTD::__format_arg_store<wformat_context, _Args...>(__args...);
 }
-#endif
+#  endif
 
 namespace __format {
 
@@ -442,38 +443,38 @@ format_to(_OutIt __out_it, wformat_string<_Args...> __fmt, _Args&&... __args) {
 // TODO FMT This needs to be a template or std::to_chars(floating-point) availability markup
 // fires too eagerly, see http://llvm.org/PR61563.
 template <class = void>
-_LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI string
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI string
 vformat(string_view __fmt, format_args __args) {
   string __res;
   _VSTD::vformat_to(_VSTD::back_inserter(__res), __fmt, __args);
   return __res;
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#  ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 // TODO FMT This needs to be a template or std::to_chars(floating-point) availability markup
 // fires too eagerly, see http://llvm.org/PR61563.
 template <class = void>
-_LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI wstring
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI wstring
 vformat(wstring_view __fmt, wformat_args __args) {
   wstring __res;
   _VSTD::vformat_to(_VSTD::back_inserter(__res), __fmt, __args);
   return __res;
 }
-#endif
+#  endif
 
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI string format(format_string<_Args...> __fmt,
-                                                                                      _Args&&... __args) {
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI string
+format(format_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::vformat(__fmt.get(), _VSTD::make_format_args(__args...));
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#  ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI wstring
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI wstring
 format(wformat_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::vformat(__fmt.get(), _VSTD::make_wformat_args(__args...));
 }
-#endif
+#  endif
 
 template <class _Context, class _OutIt, class _CharT>
 _LIBCPP_HIDE_FROM_ABI format_to_n_result<_OutIt> __vformat_to_n(_OutIt __out_it, iter_difference_t<_OutIt> __n,
@@ -509,20 +510,20 @@ _LIBCPP_HIDE_FROM_ABI size_t __vformatted_size(basic_string_view<_CharT> __fmt,
 }
 
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
 formatted_size(format_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::__vformatted_size(__fmt.get(), basic_format_args{_VSTD::make_format_args(__args...)});
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#  ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
 formatted_size(wformat_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::__vformatted_size(__fmt.get(), basic_format_args{_VSTD::make_wformat_args(__args...)});
 }
-#endif
+#  endif
 
-#ifndef _LIBCPP_HAS_NO_LOCALIZATION
+#  ifndef _LIBCPP_HAS_NO_LOCALIZATION
 
 template <class _OutIt, class _CharT, class _FormatOutIt>
 requires(output_iterator<_OutIt, const _CharT&>) _LIBCPP_HIDE_FROM_ABI _OutIt
@@ -577,43 +578,42 @@ format_to(_OutIt __out_it, locale __loc, wformat_string<_Args...> __fmt, _Args&&
 // TODO FMT This needs to be a template or std::to_chars(floating-point) availability markup
 // fires too eagerly, see http://llvm.org/PR61563.
 template <class = void>
-_LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI string
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI string
 vformat(locale __loc, string_view __fmt, format_args __args) {
   string __res;
   _VSTD::vformat_to(_VSTD::back_inserter(__res), _VSTD::move(__loc), __fmt,
                     __args);
   return __res;
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#    ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 // TODO FMT This needs to be a template or std::to_chars(floating-point) availability markup
 // fires too eagerly, see http://llvm.org/PR61563.
 template <class = void>
-_LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI wstring
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE inline _LIBCPP_HIDE_FROM_ABI wstring
 vformat(locale __loc, wstring_view __fmt, wformat_args __args) {
   wstring __res;
   _VSTD::vformat_to(_VSTD::back_inserter(__res), _VSTD::move(__loc), __fmt,
                     __args);
   return __res;
 }
-#endif
+#    endif
 
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI string format(locale __loc,
-                                                                                      format_string<_Args...> __fmt,
-                                                                                      _Args&&... __args) {
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI string
+format(locale __loc, format_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::vformat(_VSTD::move(__loc), __fmt.get(),
                         _VSTD::make_format_args(__args...));
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#    ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI wstring
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI wstring
 format(locale __loc, wformat_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::vformat(_VSTD::move(__loc), __fmt.get(),
                         _VSTD::make_wformat_args(__args...));
 }
-#endif
+#    endif
 
 template <class _Context, class _OutIt, class _CharT>
 _LIBCPP_HIDE_FROM_ABI format_to_n_result<_OutIt> __vformat_to_n(_OutIt __out_it, iter_difference_t<_OutIt> __n,
@@ -654,21 +654,20 @@ _LIBCPP_HIDE_FROM_ABI size_t __vformatted_size(locale __loc, basic_string_view<_
 }
 
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
 formatted_size(locale __loc, format_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::__vformatted_size(_VSTD::move(__loc), __fmt.get(), basic_format_args{_VSTD::make_format_args(__args...)});
 }
 
-#ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
+#    ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 template <class... _Args>
-_LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
+_LIBCPP_NODISCARD_EXT _LIBCPP_ALWAYS_INLINE _LIBCPP_HIDE_FROM_ABI size_t
 formatted_size(locale __loc, wformat_string<_Args...> __fmt, _Args&&... __args) {
   return _VSTD::__vformatted_size(_VSTD::move(__loc), __fmt.get(), basic_format_args{_VSTD::make_wformat_args(__args...)});
 }
-#endif
-
-#endif // _LIBCPP_HAS_NO_LOCALIZATION
+#    endif
 
+#  endif // _LIBCPP_HAS_NO_LOCALIZATION
 
 #endif //_LIBCPP_STD_VER >= 20
 

libcxx/test/libcxx/diagnostics/format.nodiscard_extensions.compile.pass.cpp

@@ -0,0 +1,50 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// Check that format functions aren't marked [[nodiscard]] when
+// _LIBCPP_DISBALE_NODISCARD_EXT is defined
+
+// TODO FMT This test should not require std::to_chars(floating-point)
+// XFAIL: availability-fp_to_chars-missing
+
+// UNSUPPORTED: c++03, c++11, c++14 ,c++17
+
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_DISABLE_NODISCARD_EXT
+
+#include <format>
+
+#include "test_macros.h"
+
+#ifndef TEST_HAS_NO_LOCALIZATION
+#  include <locale>
+#endif
+
+void test() {
+  std::format("");
+  std::vformat("", std::make_format_args());
+  std::formatted_size("");
+  std::make_format_args();
+
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  std::format(L"");
+  std::vformat(L"", std::make_wformat_args());
+  std::formatted_size(L"");
+  std::make_wformat_args();
+#endif // TEST_HAS_NO_WIDE_CHARACTERS
+
+#ifndef TEST_HAS_NO_LOCALIZATION
+  std::format(std::locale::classic(), "");
+  std::vformat(std::locale::classic(), "", std::make_format_args());
+  std::formatted_size(std::locale::classic(), "");
+#  ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  std::format(std::locale::classic(), L"");
+  std::vformat(std::locale::classic(), L"", std::make_wformat_args());
+  std::formatted_size(std::locale::classic(), L"");
+#  endif // TEST_HAS_NO_WIDE_CHARACTERS
+#endif   // TEST_HAS_NO_LOCALIZATION
+}

libcxx/test/libcxx/diagnostics/format.nodiscard_extensions.verify.cpp

@@ -0,0 +1,49 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// Check that format functions are marked [[nodiscard]] as a conforming extension
+
+// TODO FMT This test should not require std::to_chars(floating-point)
+// XFAIL: availability-fp_to_chars-missing
+
+// UNSUPPORTED: c++03, c++11, c++14 ,c++17
+
+#include <format>
+
+#include "test_macros.h"
+
+#ifndef TEST_HAS_NO_LOCALIZATION
+#  include <locale>
+#endif
+
+void test() {
+  // clang-format off
+  std::format(""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::vformat("", std::make_format_args()); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::formatted_size(""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::make_format_args(); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  std::format(L""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::vformat(L"", std::make_wformat_args()); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::formatted_size(L""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::make_wformat_args(); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+#endif // TEST_HAS_NO_WIDE_CHARACTERS
+
+#ifndef TEST_HAS_NO_LOCALIZATION
+  std::format(std::locale::classic(), ""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::vformat(std::locale::classic(), "", std::make_format_args()); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::formatted_size(std::locale::classic(), ""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+#  ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  std::format(std::locale::classic(), L""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::vformat(std::locale::classic(), L"", std::make_wformat_args()); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::formatted_size(std::locale::classic(), L""); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+#  endif // TEST_HAS_NO_WIDE_CHARACTERS
+#endif   // TEST_HAS_NO_LOCALIZATION
+  // clang-format on
+}