]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Better document C++11/14/17/20. 10047/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Wed, 6 May 2020 16:17:54 +0000 (10:17 -0600)
committerWolfgang Bangerth <bangerth@colostate.edu>
Wed, 6 May 2020 22:08:02 +0000 (16:08 -0600)
doc/doxygen/headers/c++.h [new file with mode: 0644]
doc/doxygen/headers/c++11.h [deleted file]
include/deal.II/base/geometry_info.h
include/deal.II/base/std_cxx11/type_traits.h
include/deal.II/base/std_cxx14/algorithm.h
include/deal.II/base/std_cxx14/memory.h
include/deal.II/base/std_cxx14/utility.h
include/deal.II/fe/fe_values.h

diff --git a/doc/doxygen/headers/c++.h b/doc/doxygen/headers/c++.h
new file mode 100644 (file)
index 0000000..c6dd98e
--- /dev/null
@@ -0,0 +1,138 @@
+// ---------------------------------------------------------------------
+//
+// Copyright (C) 2014 - 2017 by the deal.II authors
+//
+// This file is part of the deal.II library.
+//
+// The deal.II library is free software; you can use it, redistribute
+// it, and/or modify it under the terms of the GNU Lesser General
+// Public License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+// The full text of the license can be found in the file LICENSE.md at
+// the top level directory of deal.II.
+//
+// ---------------------------------------------------------------------
+
+
+/**
+ * @defgroup CPP11 deal.II and the C++11 standard
+ *
+ * Since version 9.0, deal.II requires a compiler that supports at
+ * least <a href="http://en.wikipedia.org/wiki/C%2B%2B11">C++11</a>.
+ * As part of this, many places in the internal implementation of
+ * deal.II are now using features that were only introduced in C++11.
+ * That said, deal.II also has functions and classes that make using
+ * it with C++11 features easier.
+ *
+ * One example is support for C++11
+ * <a href="http://en.wikipedia.org/wiki/C++11#Range-based_for_loop">range-based
+ * for loops</a>. deal.II-based codes often have many loops of the kind
+ * @code
+ *   Triangulation<dim> triangulation;
+ *   ...
+ *   typename Triangulation<dim>::active_cell_iterator
+ *     cell = triangulation.begin_active(),
+ *     endc = triangulation.end();
+ *   for (; cell!=endc; ++cell)
+ *     cell->set_refine_flag();
+ * @endcode
+ * Using C++11's range-based for loops, you can now write this as follows:
+ * @code
+ *   Triangulation<dim> triangulation;
+ *   ...
+ *   for (auto &cell : triangulation.active_cell_iterators())
+ *     cell->set_refine_flag();
+ * @endcode
+ * This relies on functions such as Triangulation::active_cell_iterators(),
+ * and equivalents in the DoF handler classes,
+ * DoFHandler::active_cell_iterators(), hp::DoFHandler::active_cell_iterators().
+ * There are variants of these functions that provide iterator ranges
+ * for all cells (not just the active ones) and for cells on individual
+ * levels.
+ *
+ * There are numerous other functions in the library that allow for
+ * the idiomatic use of range-based for loops. Examples are
+ * GeometryInfo::face_indices(), GeometryInfo::vertex_indices(),
+ * FEValuesBase::quadrature_point_indices(), among many others.
+ */
+
+
+
+/**
+ * deal.II currently only requires a C++11-conforming compiler, but there are a
+ * number of functions and classes from the C++14 standard that are easy to
+ * provide also in case the compiler only supports C++11. These are collected
+ * in the current namespace.
+ *
+ * The most notable example is the <a
+ * href="https://en.cppreference.com/w/cpp/memory/unique_ptr/make_unique">`std::make_unique`</a>
+ * function which is arguably an oversight for not having been
+ * included in C++11 (given that there is <a
+ * href="https://en.cppreference.com/w/cpp/memory/shared_ptr/make_shared">`std::make_shared`</a>
+ * in C++11).
+ *
+ * There are other small additions in this namespace that allow us to
+ * use C++14 features at this point already, even though we don't
+ * require a C++14-compliant compiler.
+ *
+ * @note If the compiler in use actually does support C++14, then the
+ *   contents of this namespace are simply imported classes and
+ *   functions from namespace `std`. That is, we fall back to what the
+ *   compiler provides, rather than our own implementations.
+ */
+namespace std_cxx14
+{}
+
+
+
+/**
+ * deal.II currently only requires a C++11-conforming compiler, but there are a
+ * number of functions and classes from the C++17 standard that are easy to
+ * provide also in case the compiler only supports C++11. These are collected
+ * in the current namespace.
+ *
+ * The most notable example is the <a
+ * href="https://en.cppreference.com/w/cpp/utility/optional">`std::optional`</a> class
+ * that was introduced to C++ starting with the C++17 standard.
+ *
+ * There are other small additions in this namespace that allow us to
+ * use C++17 features at this point already, even though we don't
+ * require a C++17-compliant compiler.
+ *
+ * @note If the compiler in use actually does support C++17, then the
+ *   contents of this namespace are simply imported classes and
+ *   functions from namespace `std`. That is, we fall back to what the
+ *   compiler provides, rather than our own implementations.
+ */
+namespace std_cxx17
+{}
+
+
+
+/**
+ * deal.II currently only requires a C++11-conforming compiler, but there are a
+ * number of functions and classes from the C++20 standard that are easy to
+ * provide also in case the compiler only supports C++11. These are collected
+ * in the current namespace.
+ *
+ * One example is the <a
+ * href="https://en.cppreference.com/w/cpp/ranges/iota_view">`std::ranges::iota_view`</a>
+ * class that was introduced to C++ starting with the C++20
+ * standard. It is used as the return type for the
+ * GeometryInfo::face_indices(), GeometryInfo::vertex_indices(), and
+ * FEValuesBase::quadrature_point_indices() functions, among others,
+ * to support range-based for loops (see @ref CPP11 for examples of
+ * range-based for loops, as well as the documentation of the
+ * functions mentioned above).
+ *
+ * There are other small additions in this namespace that allow us to
+ * use C++20 features at this point already, even though we don't
+ * require a C++20-compliant compiler.
+ *
+ * @note If the compiler in use actually does support C++20, then the
+ *   contents of this namespace are simply imported classes and
+ *   functions from namespace `std`. That is, we fall back to what the
+ *   compiler provides, rather than our own implementations.
+ */
+namespace std_cxx20
+{}
diff --git a/doc/doxygen/headers/c++11.h b/doc/doxygen/headers/c++11.h
deleted file mode 100644 (file)
index 11a5317..0000000
+++ /dev/null
@@ -1,52 +0,0 @@
-// ---------------------------------------------------------------------
-//
-// Copyright (C) 2014 - 2017 by the deal.II authors
-//
-// This file is part of the deal.II library.
-//
-// The deal.II library is free software; you can use it, redistribute
-// it, and/or modify it under the terms of the GNU Lesser General
-// Public License as published by the Free Software Foundation; either
-// version 2.1 of the License, or (at your option) any later version.
-// The full text of the license can be found in the file LICENSE.md at
-// the top level directory of deal.II.
-//
-// ---------------------------------------------------------------------
-
-
-/**
- * @defgroup CPP11 deal.II and the C++11 standard
- *
- * Since version 9.0, deal.II requires a compiler that supports at
- * least <a href="http://en.wikipedia.org/wiki/C%2B%2B11">C++11</a>.
- * As part of this, many places in the internal implementation of
- * deal.II are now using features that were only introduced in C++11.
- * That said, deal.II also has functions and classes that make using
- * it with C++11 features easier.
- *
- * One example is support for C++11
- * <a href="http://en.wikipedia.org/wiki/C++11#Range-based_for_loop">range-based
- * for loops</a>. deal.II-based codes often have many loops of the kind
- * @code
- *   Triangulation<dim> triangulation;
- *   ...
- *   typename Triangulation<dim>::active_cell_iterator
- *     cell = triangulation.begin_active(),
- *     endc = triangulation.end();
- *   for (; cell!=endc; ++cell)
- *     cell->set_refine_flag();
- * @endcode
- * Using C++11's range-based for loops, you can now write this as follows:
- * @code
- *   Triangulation<dim> triangulation;
- *   ...
- *   for (auto &cell : triangulation.active_cell_iterators())
- *     cell->set_refine_flag();
- * @endcode
- * This relies on functions such as Triangulation::active_cell_iterators(),
- * and equivalents in the DoF handler classes,
- * DoFHandler::active_cell_iterators(), hp::DoFHandler::active_cell_iterators().
- * There are variants of these functions that provide iterator ranges
- * for all cells (not just the active ones) and for cells on individual
- * levels.
- */
index 1f15383965ffbe746fe7780bb48f893d4b1c6a05..d91213ed7af400e8881d2d36deec9312c6101aab 100644 (file)
@@ -1946,6 +1946,8 @@ struct GeometryInfo
    * Here, we are looping over all faces of all cells, with `face_index`
    * taking on all valid indices for faces (zero and one in 1d, zero
    * through three in 2d, and zero through 5 in 3d).
+   *
+   * @see CPP11
    */
   static boost::integer_range<unsigned int>
   face_indices();
@@ -1977,6 +1979,8 @@ struct GeometryInfo
    * @endcode
    * Here, we are looping over all vertices of all cells, with `vertex_index`
    * taking on all valid indices.
+   *
+   * @see CPP11
    */
   static boost::integer_range<unsigned int>
   vertex_indices();
index df195bc0f295c7bc5343333022bcb64dbc236f30..455b42be8717296c5e11ed2a90e0ed8f3e782a19 100644 (file)
@@ -26,8 +26,6 @@ DEAL_II_WARNING(
 DEAL_II_NAMESPACE_OPEN
 namespace std_cxx11
 {
-  // TODO: could fill up with more types from
-  // C++11 type traits
   using std::enable_if;
   using std::false_type;
   using std::is_fundamental;
index b7d283d0cd3168c7c55bb4301f695c1fdc3875f0..8cc20bfa90550fd416db5348a0d487cb7e635462 100644 (file)
 #endif
 
 DEAL_II_NAMESPACE_OPEN
+
 namespace std_cxx14
 {
 #ifdef DEAL_II_WITH_CXX14
   using std::max;
   using std::min;
+
 #else
 
   template <class T>
@@ -59,6 +61,7 @@ namespace std_cxx14
 
 #endif
 } // namespace std_cxx14
+
 DEAL_II_NAMESPACE_CLOSE
 
 #endif // dealii_cxx14_algorithm_h
index 489283763d13f3e7852b681088cea50a99a7a409..cc42a54bb11e3d915a2a720bc40fb677aadffc3d 100644 (file)
 #endif
 
 DEAL_II_NAMESPACE_OPEN
+
 namespace std_cxx14
 {
 #ifdef DEAL_II_WITH_CXX14
   using std::make_unique;
+
 #else
+
   namespace internal
   {
     template <typename T>
@@ -66,6 +69,7 @@ namespace std_cxx14
 
 #endif
 } // namespace std_cxx14
+
 DEAL_II_NAMESPACE_CLOSE
 
 #endif // dealii_cxx14_memory_h
index efa8d0f3e0f4f55a6b187680495c95438ebaed43..1c77d684461543f489c01bd1800647cc15fae59b 100644 (file)
 #endif
 
 DEAL_II_NAMESPACE_OPEN
+
 namespace std_cxx14
 {
 #ifdef DEAL_II_WITH_CXX14
   using std::index_sequence;
   using std::index_sequence_for;
   using std::make_index_sequence;
+
 #else
+
   template <size_t... Ints>
   struct index_sequence
   {
@@ -74,6 +77,7 @@ namespace std_cxx14
   using index_sequence_for = make_index_sequence<sizeof...(T)>;
 #endif
 } // namespace std_cxx14
+
 DEAL_II_NAMESPACE_CLOSE
 
 #endif // dealii_cxx14_memory_h
index 5ddb4ca9147babcb36763d1d1cb034595818787a..b8e0f12985f9380a64510e89d33f0979da13c505 100644 (file)
@@ -2931,6 +2931,8 @@ public:
    * Here, we are looping over all quadrature points on all cells, with
    * `q_point` taking on all valid indices for quadrature points, as defined
    * by the quadrature rule passed to `fe_values`.
+   *
+   * @see CPP11
    */
   boost::integer_range<unsigned int>
   quadrature_point_indices() const;

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.