From 2c463b2c0fa61c4efab563a799b9db6db73d08de Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 7 Apr 2023 14:21:14 -0600
Subject: [PATCH] Deprecate DoFTools functions returning stuff via reference
 arguments.

---
 include/deal.II/dofs/dof_tools.h | 40 +++++++++++++++++++++++++-------
 source/dofs/dof_tools.cc         | 34 +++++++++++++++++++++++++--
 source/dofs/dof_tools.inst.in    | 15 ++++++++++++
 3 files changed, 78 insertions(+), 11 deletions(-)

diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h
index ed417ed863..d6880e9aa5 100644
--- a/include/deal.II/dofs/dof_tools.h
+++ b/include/deal.II/dofs/dof_tools.h
@@ -2274,17 +2274,37 @@ namespace DoFTools
    * is of course dense, i.e., every DoF is to be found in it.
    *
    * @param[in] mapping The mapping from the reference cell to the real cell on
-   * which DoFs are defined.
+   *   which DoFs are defined.
    * @param[in] dof_handler The object that describes which DoF indices live on
-   * which cell of the triangulation.
-   * @param[in,out] support_points A map that for every locally relevant DoF
-   * index contains the corresponding location in real space coordinates.
-   * Previous content of this object is deleted in this function.
+   *   which cell of the triangulation.
    * @param[in] mask An optional component mask that restricts the
-   * components from which the support points are extracted.
+   *   components from which the support points are extracted.
+   * @return A map that for every locally relevant DoF
+   *   index contains the corresponding location in real space coordinates.
    */
   template <int dim, int spacedim>
-  void
+  std::map<types::global_dof_index, Point<spacedim>>
+  map_dofs_to_support_points(const Mapping<dim, spacedim> &   mapping,
+                             const DoFHandler<dim, spacedim> &dof_handler,
+                             const ComponentMask &mask = ComponentMask());
+
+  /**
+   * Same as the previous function but for the hp-case.
+   */
+  template <int dim, int spacedim>
+  std::map<types::global_dof_index, Point<spacedim>>
+  map_dofs_to_support_points(
+    const dealii::hp::MappingCollection<dim, spacedim> &mapping,
+    const DoFHandler<dim, spacedim> &                   dof_handler,
+    const ComponentMask &                               mask = ComponentMask());
+
+  /**
+   * A version of the function of same name that returns the map via its third
+   * argument. This function is deprecated.
+   * @deprecated Use the function that returns the `std::map` instead.
+   */
+  template <int dim, int spacedim>
+  DEAL_II_DEPRECATED_EARLY void
   map_dofs_to_support_points(
     const Mapping<dim, spacedim> &                      mapping,
     const DoFHandler<dim, spacedim> &                   dof_handler,
@@ -2292,10 +2312,12 @@ namespace DoFTools
     const ComponentMask &                               mask = ComponentMask());
 
   /**
-   * Same as the previous function but for the hp-case.
+   * A version of the function of same name that returns the map via its third
+   * argument. This function is deprecated.
+   * @deprecated Use the function that returns the `std::map` instead.
    */
   template <int dim, int spacedim>
-  void
+  DEAL_II_DEPRECATED_EARLY void
   map_dofs_to_support_points(
     const dealii::hp::MappingCollection<dim, spacedim> &mapping,
     const DoFHandler<dim, spacedim> &                   dof_handler,
diff --git a/source/dofs/dof_tools.cc b/source/dofs/dof_tools.cc
index 93470a2bff..a101c083b4 100644
--- a/source/dofs/dof_tools.cc
+++ b/source/dofs/dof_tools.cc
@@ -2293,8 +2293,9 @@ namespace DoFTools
   }
 
 
+  // This functino is deprecated:
   template <int dim, int spacedim>
-  void
+  DEAL_II_DEPRECATED_EARLY void
   map_dofs_to_support_points(
     const Mapping<dim, spacedim> &                      mapping,
     const DoFHandler<dim, spacedim> &                   dof_handler,
@@ -2313,8 +2314,9 @@ namespace DoFTools
   }
 
 
+  // This functino is deprecated:
   template <int dim, int spacedim>
-  void
+  DEAL_II_DEPRECATED_EARLY void
   map_dofs_to_support_points(
     const hp::MappingCollection<dim, spacedim> &        mapping,
     const DoFHandler<dim, spacedim> &                   dof_handler,
@@ -2329,6 +2331,34 @@ namespace DoFTools
       internal::map_dofs_to_support_points(mapping, dof_handler, mask);
   }
 
+
+  template <int dim, int spacedim>
+  std::map<types::global_dof_index, Point<spacedim>>
+  map_dofs_to_support_points(const Mapping<dim, spacedim> &   mapping,
+                             const DoFHandler<dim, spacedim> &dof_handler,
+                             const ComponentMask &            mask)
+  {
+    // Let the internal function do all the work, just make sure that it
+    // gets a MappingCollection
+    const hp::MappingCollection<dim, spacedim> mapping_collection(mapping);
+
+    return internal::map_dofs_to_support_points(mapping_collection,
+                                                dof_handler,
+                                                mask);
+  }
+
+
+  template <int dim, int spacedim>
+  std::map<types::global_dof_index, Point<spacedim>>
+  map_dofs_to_support_points(
+    const hp::MappingCollection<dim, spacedim> &mapping,
+    const DoFHandler<dim, spacedim> &           dof_handler,
+    const ComponentMask &                       mask)
+  {
+    return internal::map_dofs_to_support_points(mapping, dof_handler, mask);
+  }
+
+
   template <int spacedim>
   void
   write_gnuplot_dof_support_point_info(
diff --git a/source/dofs/dof_tools.inst.in b/source/dofs/dof_tools.inst.in
index eca45afde1..9239bd2424 100644
--- a/source/dofs/dof_tools.inst.in
+++ b/source/dofs/dof_tools.inst.in
@@ -404,6 +404,7 @@ for (deal_II_dimension : DIMENSIONS; deal_II_space_dimension : DIMENSIONS)
         std::vector<Point<deal_II_space_dimension>> &,
         const ComponentMask &);
 
+      // This function is deprecated:
       template void
       map_dofs_to_support_points<deal_II_dimension, deal_II_space_dimension>(
         const Mapping<deal_II_dimension, deal_II_space_dimension> &,
@@ -411,6 +412,7 @@ for (deal_II_dimension : DIMENSIONS; deal_II_space_dimension : DIMENSIONS)
         std::map<types::global_dof_index, Point<deal_II_space_dimension>> &,
         const ComponentMask &);
 
+      // This function is deprecated:
       template void
       map_dofs_to_support_points<deal_II_dimension, deal_II_space_dimension>(
         const hp::MappingCollection<deal_II_dimension, deal_II_space_dimension>
@@ -418,6 +420,19 @@ for (deal_II_dimension : DIMENSIONS; deal_II_space_dimension : DIMENSIONS)
         const DoFHandler<deal_II_dimension, deal_II_space_dimension> &,
         std::map<types::global_dof_index, Point<deal_II_space_dimension>> &,
         const ComponentMask &);
+
+      template std::map<types::global_dof_index, Point<deal_II_space_dimension>>
+      map_dofs_to_support_points<deal_II_dimension, deal_II_space_dimension>(
+        const Mapping<deal_II_dimension, deal_II_space_dimension> &,
+        const DoFHandler<deal_II_dimension, deal_II_space_dimension> &,
+        const ComponentMask &);
+
+      template std::map<types::global_dof_index, Point<deal_II_space_dimension>>
+      map_dofs_to_support_points<deal_II_dimension, deal_II_space_dimension>(
+        const hp::MappingCollection<deal_II_dimension, deal_II_space_dimension>
+          &,
+        const DoFHandler<deal_II_dimension, deal_II_space_dimension> &,
+        const ComponentMask &);
     \}
 #endif
   }
-- 
2.39.5