[array.hh] Deprecate Dune::array and helpers.

This deprecates the header `<dune/common/array.hh>` and all of its members.
- `Dune::array`: use `std::array` instead.
- `Dune::make_array()`: use `Dune::Std::make_array()` instead.
- `Dune::fill_array()`: use `Dune::filledArray()` instead.

Note that deprecation warnings for `array` and `make_array` could not be
implemented, since those were implemented by using declarations and it seems
to be impossible to deprecate those.  Users should still get a note though
since the entire header is deprecated.

For `fill_array()` there was no replacement, so this commit introduces
`filledArray()` with a slightly improved calling syntax, a better name, and
(in C++17) support for `constexpr` arrays.  To make it possible to deprecate
`array.hh`, that replacement is in its own header `filledarray.hh`.

This commit also introduces two unit tests:
- `filledarraytest.cc` to test `filledArray()`, and
- `arraydeprecationtest.cc` to make sure the deprecation syntax is supported
  for all tested compilers.  (It also has a feature to check that deprecation
  warnings are really displayed, but that is disabled for regular unit testing
  since the logs have to be checked manually for the warnings.)

dune/common/CMakeLists.txt

@@ -57,6 +57,7 @@ install(FILES
         dynvector.hh
         enumset.hh
         exceptions.hh
+        filledarray.hh
         float_cmp.cc
         float_cmp.hh
         fmatrix.hh

dune/common/array.hh

@@ -4,12 +4,22 @@
 #ifndef DUNE_ARRAY_HH
 #define DUNE_ARRAY_HH
 
+#ifndef DUNE_COMMON_ARRAY_HH_DISABLE_DEPRECATION_WARNING
+
+#warning This header is deprecated.
+#warning Instead of Dune::array, use std::array from <array>.
+#warning Instead of Dune::make_array(), use Dune::Std::make_array() from <dune/common/std/make_array.hh>.
+#warning Instead of Dune::fill_array(), use Dune::filledArray() from <dune/common/filledarray.hh>.
+
+#endif // DUNE_DISABLE_ARRAY_HH_DEPRECATION_WARNING
+
 /** \file
     \brief Fallback implementation of the std::array class (a static array)
  */
 
 #include <array>
 
+#include <dune/common/deprecated.hh>
 #include <dune/common/streamoperators.hh>
 #include <dune/common/std/make_array.hh>
 
@@ -21,16 +31,24 @@ namespace Dune
    */
 
   // pull in default implementation
+  // deprecation does not work:
+  // DUNE_DEPRECATED_MSG("Use std::array from <array>")
   using std::array;
 
+  // deprecation does not work:
+  // DUNE_DEPRECATED_MSG("Use Dune::Std::make_array from <dune/common/std/make_array.hh>")
   using Dune::Std::make_array;
 
   //! Create an array and fill it with copies of the provided value.
   /**
    * \note This method is Dune-specific and not part of any C++ standard.
+   *
+   * \deprecated Use Dune::filledArray() from <dune/common/filledarray.hh>.
+   *
    * \ingroup CxxUtilities
    */
   template<typename T, std::size_t n>
+  DUNE_DEPRECATED_MSG("Use Dune::filledArray() from <dune/common/filledarray.hh>")
   std::array<T,n> fill_array(const T& t)
   {
     std::array<T,n> r;

dune/common/filledarray.hh

+// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+// vi: set et ts=4 sw=2 sts=2:
+
+#ifndef DUNE_COMMON_FILLED_ARRAY_HH
+#define DUNE_COMMON_FILLED_ARRAY_HH
+
+/** \file
+    \brief Utility to generate an array with a certain value
+ */
+
+#include <array>
+#include <cstddef>
+
+namespace Dune
+{
+  /** @addtogroup Common
+
+     @{
+   */
+
+  //! Return an array filled with the provided value.
+  /**
+   * \note This function is `constexpr` only in C++17, or, more precisely,
+   *       when `std::array::begin()` and `std::array::end()` are `constexpr`.
+   *
+   * \tparam n     Size of the returned array.
+   * \tparam T     Value type of the returned array.  This is usually deduced
+   *               from `t`.
+   */
+  template<std::size_t n, class T>
+  constexpr std::array<T, n> filledArray(const T& t)
+  {
+    std::array<T, n> arr{};
+    // this is constexpr in c++17, `arr.fill(t)` is not
+    for(auto &el : arr)
+      el = t;
+    return arr;
+  }
+
+  /** @} */
+
+} // end namespace Dune
+
+#endif // DUNE_COMMON_FILLED_ARRAY_HH

dune/common/test/CMakeLists.txt

@@ -3,6 +3,8 @@ dune_add_test(SOURCES arithmetictestsuitetest.cc
 
 dune_add_test(SOURCES arraylisttest.cc)
 
+dune_add_test(SOURCES arraydeprecationtest.cc)
+
 dune_add_test(SOURCES arraytest.cc)
 
 dune_add_test(SOURCES assertandreturntest.cc
@@ -108,6 +110,8 @@ dune_add_test(SOURCES densevectortest.cc
 
 dune_add_test(SOURCES enumsettest.cc)
 
+dune_add_test(SOURCES filledarraytest.cc)
+
 dune_add_test(SOURCES fmatrixtest.cc
               LINK_LIBRARIES dunecommon)
 add_dune_vc_flags(fmatrixtest)

dune/common/test/arraydeprecationtest.cc

+// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+// vi: set et ts=4 sw=2 sts=2:
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+// This should be defined for regular unit test use; undefine to check that
+// the warnings are indeed displayed.
+#define NO_DEPRECATION_WARNINGS
+
+#include <array>
+#include <type_traits>
+
+#ifdef NO_DEPRECATION_WARNINGS
+#define DUNE_COMMON_ARRAY_HH_DISABLE_DEPRECATION_WARNING
+#endif // NO_DEPRECATION_WARNINGS
+#include <dune/common/array.hh>
+#include <dune/common/deprecated.hh>
+
+int main()
+{
+  // just a check to make sure we can still use array.hh's functionality while
+  // it is deprecated.
+  Dune::array<int, 2> test1;
+  (void)test1;
+
+  auto test2 = Dune::make_array(1, 2, 3);
+  static_assert(std::is_same<decltype(test2), std::array<int, 3> >::value,
+                "Unexpected result type for Dune::make_array()");
+
+#ifdef NO_DEPRECATION_WARNINGS
+  DUNE_NO_DEPRECATED_BEGIN;
+#endif // NO_DEPRECATION_WARNINGS
+  auto test3 = Dune::fill_array<int, 2>(0);
+#ifdef NO_DEPRECATION_WARNINGS
+  DUNE_NO_DEPRECATED_END;
+#endif // NO_DEPRECATION_WARNINGS
+  (void)test3;
+}

dune/common/test/filledarraytest.cc

+// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+// vi: set et ts=4 sw=2 sts=2:
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <array>
+#include <iostream>
+#include <type_traits>
+
+#include <dune/common/filledarray.hh>
+
+int main() {
+
+  int status = 0;
+
+  auto test1 = Dune::filledArray<2>(2.0);
+  static_assert(std::is_same<decltype(test1), std::array<double, 2> >::value,
+                "Wrong result type for Dune::filledArray()");
+
+  if(test1[0] != 2.0 || test1[1] != 2.0)
+  {
+    std::cerr << "Dune::filledArray() produces wrong value" << std::endl;
+    status = 1;
+  }
+
+#ifdef __cpp_lib_array_constexpr
+  std::cout << "The result of Dune::filledArray() is constexpr" << std::endl;
+  constexpr auto test2 = Dune::filledArray<2>(2);
+  (void)test2;
+#else // !__cpp_lib_array_constexpr
+  std::cout << "Not checking whether Dune::filledArray() is constexpr\n"
+            << "since the library does not declare std::array as constexpr\n"
+            << "(__cpp_lib_array_constexpr is not defined)." << std::endl;
+#endif // !__cpp_lib_array_constexpr
+
+  return status;
+}