From b23206294e377b38ee919b645296a8eda11e681d Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 6 May 2020 10:17:54 -0600 Subject: [PATCH] Better document C++11/14/17/20. --- doc/doxygen/headers/c++.h | 138 +++++++++++++++++++ doc/doxygen/headers/c++11.h | 52 ------- include/deal.II/base/geometry_info.h | 4 + include/deal.II/base/std_cxx11/type_traits.h | 2 - include/deal.II/base/std_cxx14/algorithm.h | 3 + include/deal.II/base/std_cxx14/memory.h | 4 + include/deal.II/base/std_cxx14/utility.h | 4 + include/deal.II/fe/fe_values.h | 2 + 8 files changed, 155 insertions(+), 54 deletions(-) create mode 100644 doc/doxygen/headers/c++.h delete mode 100644 doc/doxygen/headers/c++11.h diff --git a/doc/doxygen/headers/c++.h b/doc/doxygen/headers/c++.h new file mode 100644 index 0000000000..c6dd98edc4 --- /dev/null +++ b/doc/doxygen/headers/c++.h @@ -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 C++11. + * 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 + * range-based + * for loops. deal.II-based codes often have many loops of the kind + * @code + * Triangulation triangulation; + * ... + * typename Triangulation::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 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 `std::make_unique` + * function which is arguably an oversight for not having been + * included in C++11 (given that there is `std::make_shared` + * 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 `std::optional` 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 `std::ranges::iota_view` + * 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 index 11a5317325..0000000000 --- a/doc/doxygen/headers/c++11.h +++ /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 C++11. - * 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 - * range-based - * for loops. deal.II-based codes often have many loops of the kind - * @code - * Triangulation triangulation; - * ... - * typename Triangulation::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 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. - */ diff --git a/include/deal.II/base/geometry_info.h b/include/deal.II/base/geometry_info.h index 1f15383965..d91213ed7a 100644 --- a/include/deal.II/base/geometry_info.h +++ b/include/deal.II/base/geometry_info.h @@ -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 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 vertex_indices(); diff --git a/include/deal.II/base/std_cxx11/type_traits.h b/include/deal.II/base/std_cxx11/type_traits.h index df195bc0f2..455b42be87 100644 --- a/include/deal.II/base/std_cxx11/type_traits.h +++ b/include/deal.II/base/std_cxx11/type_traits.h @@ -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; diff --git a/include/deal.II/base/std_cxx14/algorithm.h b/include/deal.II/base/std_cxx14/algorithm.h index b7d283d0cd..8cc20bfa90 100644 --- a/include/deal.II/base/std_cxx14/algorithm.h +++ b/include/deal.II/base/std_cxx14/algorithm.h @@ -22,11 +22,13 @@ #endif DEAL_II_NAMESPACE_OPEN + namespace std_cxx14 { #ifdef DEAL_II_WITH_CXX14 using std::max; using std::min; + #else template @@ -59,6 +61,7 @@ namespace std_cxx14 #endif } // namespace std_cxx14 + DEAL_II_NAMESPACE_CLOSE #endif // dealii_cxx14_algorithm_h diff --git a/include/deal.II/base/std_cxx14/memory.h b/include/deal.II/base/std_cxx14/memory.h index 489283763d..cc42a54bb1 100644 --- a/include/deal.II/base/std_cxx14/memory.h +++ b/include/deal.II/base/std_cxx14/memory.h @@ -25,11 +25,14 @@ #endif DEAL_II_NAMESPACE_OPEN + namespace std_cxx14 { #ifdef DEAL_II_WITH_CXX14 using std::make_unique; + #else + namespace internal { template @@ -66,6 +69,7 @@ namespace std_cxx14 #endif } // namespace std_cxx14 + DEAL_II_NAMESPACE_CLOSE #endif // dealii_cxx14_memory_h diff --git a/include/deal.II/base/std_cxx14/utility.h b/include/deal.II/base/std_cxx14/utility.h index efa8d0f3e0..1c77d68446 100644 --- a/include/deal.II/base/std_cxx14/utility.h +++ b/include/deal.II/base/std_cxx14/utility.h @@ -25,13 +25,16 @@ #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 struct index_sequence { @@ -74,6 +77,7 @@ namespace std_cxx14 using index_sequence_for = make_index_sequence; #endif } // namespace std_cxx14 + DEAL_II_NAMESPACE_CLOSE #endif // dealii_cxx14_memory_h diff --git a/include/deal.II/fe/fe_values.h b/include/deal.II/fe/fe_values.h index 5ddb4ca914..b8e0f12985 100644 --- a/include/deal.II/fe/fe_values.h +++ b/include/deal.II/fe/fe_values.h @@ -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 quadrature_point_indices() const; -- 2.39.5