CGAL improvement backported from CDT_3 branch (#8170)

## Summary of Changes

Important various fixes and improvements, from an experimental branch of
mine about CDT_3.

- <s>remove CMake warnings about `VTK_USE_FILE`</s> (our testsuite tests
with [VTK-8.2](https://docs.vtk.org/en/latest/release_details/8.2.html),
whereas
[VTK-9.0](https://docs.vtk.org/en/latest/release_details/9.0.html) was
released four years ago).
- make `Circulator_from_container` compatible with ranges (instead of
just containers)
- `Hash_map` is move-constructible and -assignable
- add preliminary support for C++20 concepts and `<format>`
- [x] add `Compare_angle_3(Point_3, Point_3, Point_3, Point_3, Point_3,
Point_3)` (with six points) **TODO: needs doc**... will be handled later
in issue #8219
- [x] **breaking changes:** add `Compare_xy_2` to
`TriangulationTraits_2` <s>TODO: needs announcement</s>
- fix `Compact_container` time stamp feature
- [x] commits from #7410 **That is probably a problem, to be fixed.**
**fixed in #7410 and then my the merge
https://github.com/CGAL/cgal/pull/8170/commits/70464ea107dcf9e32a338ed5c307897f1cb1fcf8**
- add `CGAL::Scope_exit`, `CGAL::make_scope_exit`, for CGAL developers
(undocumented)
- add an overload of `make_sorted_pair` with only one pair-like argument
- improve `CGAL::IO::Output_ref` and `oformat`
- perf improvements in
`TDS_3/include/CGAL/Triangulation_data_structure_3.h` (`is_edge` is 7
times faster)
- <s>perf improvement in
`Triangulation_2/include/CGAL/Triangulation_2/internal/Polyline_constraint_hierarchy_2.h`
(with the use of `unordered_flat_map` from Boost>=1.80</s>
- less filter failures in `Triangulation_segment_cell_iterator_3`
- add `Triangulation_3::is_facet(u, v, w)` (without `, c, i, j, k`)

## Release Management

* Affected package(s): Installation, T_2, TDS_2, T_3, TDS_3, SMDS_3,
Kernel, STL_Extension, Stream_support
* Feature/Small Feature (if any):
* License and copyright ownership: maintenance by GeometryFactory

Circulator/include/CGAL/circulator.h

@@ -698,14 +698,18 @@ typedef Iterator_from_circulator< C, const_reference, const_pointer>
 };
 template <class Container>
 class Circulator_from_container {
+    static auto begin(Container* c) {
+        using std::begin;
+        return begin(*c);
+    }
+
+    static auto end(Container* c) {
+        using std::end;
+        return end(*c);
+    }
+
     typedef Circulator_from_container<Container>      Self;
-    typedef typename Container::iterator              container_iterator;
-    typedef typename Container::const_iterator        container_const_iterator;
-    typedef std::conditional_t<
-        std::is_const<Container>::value,
-        container_const_iterator,
-        container_iterator
-        >                                             iterator;
+    using iterator = decltype(begin(std::declval<Container*>()));
     typedef std::iterator_traits<iterator>            iterator_traits;
 public:
     typedef typename iterator_traits::value_type      value_type;
@@ -717,7 +721,7 @@ class Circulator_from_container {
         typename iterator_traits::iterator_category
         >::iterator_category                          iterator_category;
 
-    typedef typename Container::size_type size_type;
+    using size_type = decltype(std::size(std::declval<Container&>()));
 private:
     Container*     ctnr;
     iterator  i;
@@ -734,27 +738,27 @@ class Circulator_from_container {
     bool operator==( std::nullptr_t p) const {
         CGAL_USE(p);
         CGAL_assertion( p == nullptr);
-        return (ctnr == nullptr) || (ctnr->begin() == ctnr->end());
+        return (ctnr == nullptr) || (begin(ctnr) == end(ctnr));
     }
     bool operator!=( std::nullptr_t p) const { return !(*this == p); }
     bool operator==( const Self& c) const { return i == c.i; }
     bool operator!=( const Self& c) const { return !(*this == c); }
     reference  operator*() const {
         CGAL_assertion( ctnr != nullptr);
-        CGAL_assertion( i != ctnr->end());
+        CGAL_assertion( i != end(ctnr));
         return *i;
     }
     pointer  operator->() const {
         CGAL_assertion( ctnr != nullptr);
-        CGAL_assertion( i != ctnr->end());
+        CGAL_assertion( i != end(ctnr));
         return i.operator->();
     }
     Self& operator++() {
         CGAL_assertion( ctnr != nullptr);
-        CGAL_assertion( i != ctnr->end());
+        CGAL_assertion( i != end(ctnr));
         ++i;
-        if ( i == ctnr->end())
-            i = ctnr->begin();
+        if ( i == end(ctnr))
+            i = begin(ctnr);
         return *this;
     }
     Self operator++(int) {
@@ -764,9 +768,9 @@ class Circulator_from_container {
     }
     Self& operator--() {
         CGAL_assertion( ctnr != nullptr);
-        CGAL_assertion( i != ctnr->end());
-        if ( i == ctnr->begin())
-            i = ctnr->end();
+        CGAL_assertion( i != end(ctnr));
+        if ( i == begin(ctnr))
+            i = end(ctnr);
         --i;
         return *this;
     }
@@ -777,15 +781,15 @@ class Circulator_from_container {
     }
     Self& operator+=( difference_type n) {
         CGAL_assertion( ctnr != nullptr);
-        CGAL_assertion( i != ctnr->end());
-        typename Container::difference_type j    = i - ctnr->begin();
+        CGAL_assertion( i != end(ctnr));
+        typename Container::difference_type j    = i - begin(ctnr);
         typename Container::difference_type size = ctnr->size();
         CGAL_assertion( j    >= 0);
         CGAL_assertion( size >= 0);
         j = non_negative_mod( j + n, size);
         CGAL_assertion( j >= 0);
         CGAL_assertion( j < size);
-        i = ctnr->begin() + j;
+        i = begin(ctnr) + j;
         return *this;
     }
     Self operator+( difference_type n) const {

Hash_map/include/CGAL/Hash_map/internal/chained_map.h

@@ -19,6 +19,8 @@
 #include <CGAL/memory.h>
 #include <iostream>
 #include <limits>
+#include <type_traits>
+#include <utility>
 
 namespace CGAL {
 
@@ -85,6 +87,10 @@ class chained_map
    chained_map(std::size_t n = default_size, const T& d = T());
    chained_map(const chained_map<T, Allocator>& D);
    chained_map& operator=(const chained_map<T, Allocator>& D);
+   chained_map(chained_map<T, Allocator>&& D)
+     noexcept(std::is_nothrow_move_constructible_v<Allocator> && std::is_nothrow_move_constructible_v<T>);
+   chained_map& operator=(chained_map<T, Allocator>&& D)
+     noexcept(std::is_nothrow_move_assignable_v<Allocator> && std::is_nothrow_move_assignable_v<T>);
 
    void reserve(std::size_t n);
    void clear();
@@ -246,6 +252,18 @@ chained_map<T, Allocator>::chained_map(const chained_map<T, Allocator>& D)
     }
   }
 }
+template <typename T, typename Allocator>
+chained_map<T, Allocator>::chained_map(chained_map<T, Allocator>&& D)
+  noexcept(std::is_nothrow_move_constructible_v<Allocator> && std::is_nothrow_move_constructible_v<T>)
+  : table(std::exchange(D.table, nullptr))
+  , table_end(std::exchange(D.table_end, nullptr))
+  , free(std::exchange(D.free, nullptr))
+  , table_size(std::exchange(D.table_size, 0))
+  , table_size_1(std::exchange(D.table_size_1, 0))
+  , alloc(std::move(D.alloc))
+  , reserved_size(std::exchange(D.reserved_size, 0))
+  , def(std::move(D.def))
+{}
 
 template <typename T, typename Allocator>
 chained_map<T, Allocator>& chained_map<T, Allocator>::operator=(const chained_map<T, Allocator>& D)
@@ -263,6 +281,24 @@ chained_map<T, Allocator>& chained_map<T, Allocator>::operator=(const chained_ma
   return *this;
 }
 
+template <typename T, typename Allocator>
+chained_map<T, Allocator>& chained_map<T, Allocator>::operator=(chained_map<T, Allocator>&& D)
+  noexcept(std::is_nothrow_move_assignable_v<Allocator> && std::is_nothrow_move_assignable_v<T>)
+{
+  clear();
+
+  table = std::exchange(D.table, nullptr);
+  table_end = std::exchange(D.table_end, nullptr);
+  free = std::exchange(D.free, nullptr);
+  table_size = std::exchange(D.table_size, 0);
+  table_size_1 = std::exchange(D.table_size_1, 0);
+  alloc = std::move(D.alloc);
+  reserved_size = std::exchange(D.reserved_size, 0);
+  def = std::move(D.def);
+
+  return *this;
+}
+
 template <typename T, typename Allocator>
 void chained_map<T, Allocator>::reserve(std::size_t n)
 {

Hash_map/test/Hash_map/Unique_hash_map_test.cpp

@@ -1,6 +1,7 @@
 #include <list>
 #include <CGAL/Unique_hash_map.h>
 #include <CGAL/test_macros.h>
+#include <type_traits>
 
 using namespace std;
 typedef list<int>::iterator Iterator;
@@ -24,6 +25,10 @@ int main() {
     H1[it1] = 2;
     CGAL_TEST(H1[it1]==2);
     CGAL_TEST(H2[it1]==-1);
+    static_assert(std::is_nothrow_move_constructible_v<decltype(H1)>);
+    auto H1_moved = std::move(H1);
+    CGAL_TEST(H1_moved[it1]==2);
+    CGAL_TEST(H1[it1]==H1.default_value());
     H1.clear();
     H2.clear(-2);
     H2[it1] = 2;
@@ -67,6 +72,7 @@ int main() {
     CGAL_TEST(get(H4_pmap, L.begin()) == 0);
 
     typedef CGAL::Unique_hash_map<int, int, Integer_hash_function>  Int_hmap;
+    static_assert(std::is_nothrow_move_constructible_v<Int_hmap>);
     typedef boost::associative_property_map<Int_hmap>               Int_pmap;
     Int_hmap H5(-1);
     Int_pmap H5_pmap(H5);

Installation/CHANGES.md

@@ -1,8 +1,6 @@
-Release History
-===============
+# Release History
 
-[Release 6.0](https://github.com/CGAL/cgal/releases/tag/v6.0)
------------
+## [Release 6.0](https://github.com/CGAL/cgal/releases/tag/v6.0)
 
 Release date: June 2024
 
@@ -125,6 +123,9 @@ Release date: June 2024
 ### [Surface Mesh Parameterization](https://doc.cgal.org/6.0/Manual/packages.html#PkgSurfaceMeshParameterization)
 - **Breaking change**: LSCM_parameterizer_3 needs Eigen
 
+### [2D Triangulations](https://doc.cgal.org/6.0/Manual/packages.html#PkgTriangulation2)
+-   **Breaking change**: the concept [`TriangulationTraits_2`](https://doc.cgal.org/6.0/Triangulation_2/classTriangulationTraits__2.html) now requires an additional functor `Compare_xy_2`.
+
 ### [3D Triangulations](https://doc.cgal.org/6.0/Manual/packages.html#PkgTriangulation3)
 -   Added three functions `vertices()` to the class `Triangulation_3`.
     Each of them returns an array containing the vertices of the given triangulation simplex.

Installation/include/CGAL/config.h

@@ -293,7 +293,9 @@ using std::max;
 // Macros to detect features of clang. We define them for the other
 // compilers.
 // See https://clang.llvm.org/docs/LanguageExtensions.html
-// See also https://en.cppreference.com/w/cpp/experimental/feature_test
+//
+// Some of those macro have been standardized. See C++20 feature testing:
+//   https://en.cppreference.com/w/cpp/feature_test
 #ifndef __has_feature
   #define __has_feature(x) 0  // Compatibility with non-clang compilers.
 #endif
@@ -316,6 +318,10 @@ using std::max;
   #define __has_warning(x) 0  // Compatibility with non-clang compilers.
 #endif
 
+#if __has_include(<version>)
+#  include <version>
+#endif
+
 // Macro to specify a 'unused' attribute.
 #if __has_cpp_attribute(maybe_unused)
 #  define CGAL_UNUSED [[maybe_unused]]
@@ -470,6 +476,14 @@ namespace cpp11{
 }//namespace cpp11
 } //namespace CGAL
 
+#if __cpp_lib_concepts >= 201806L
+#  define CGAL_CPP20_REQUIRE_CLAUSE(x) requires x
+#  define CGAL_TYPE_CONSTRAINT(x) x
+#else
+#  define CGAL_CPP20_REQUIRE_CLAUSE(x)
+#  define CGAL_TYPE_CONSTRAINT(x) typename
+#endif
+
 // The fallthrough attribute
 // See for clang:
 //   https://clang.llvm.org/docs/AttributeReference.html#statement-attributes
@@ -487,6 +501,10 @@ namespace cpp11{
 #  define CGAL_FALLTHROUGH while(false){}
 #endif
 
+#if __cpp_lib_format >= 201907L || (__has_include(<format>) && (__cplusplus >= 202000L || _MSVC_LANG >= 202000L))
+#  define CGAL_CAN_USE_CXX20_FORMAT 1
+#endif
+
 #ifndef CGAL_NO_ASSERTIONS
 #  define CGAL_NO_ASSERTIONS_BOOL false
 #else

Interpolation/include/CGAL/Voronoi_intersection_2_traits_3.h

@@ -291,6 +291,24 @@ class Voronoi_intersection_2_traits_3
   typedef typename Rep::Less_distance_to_point_3    Less_distance_to_point_2;
   typedef typename Rep::Compute_squared_distance_3  Compute_squared_distance_2;
 
+  struct Compare_xy_2 {
+    Compare_x_2 cx_2;
+    Compare_y_2 cy_2;
+
+    Compare_xy_2(const Compare_x_2& cx_2, const Compare_y_2& cy_2)
+      : cx_2(cx_2), cy_2(cy_2)
+    {}
+
+    Comparison_result operator()(const Point_2& p, const Point_2& q) const
+    {
+       Comparison_result res = cx_2(p, q);
+       if (res == EQUAL) {
+         return cy_2(p, q);
+       }
+       return res;
+    }
+  };
+
   //instantiations and creation of functors:
   //for the triangulation:
   Orientation_2
@@ -312,6 +330,10 @@ class Voronoi_intersection_2_traits_3
   compare_y_2_object() const
   { return Compare_y_2(normal); }
 
+  Compare_xy_2
+  compare_xy_2_object() const
+  { return Compare_xy_2(compare_x_2_object(), compare_y_2_object()); }
+
   Less_x_2
   less_x_2_object() const
   { return compare_to_less(compare_x_2_object()); }

Kernel_23/include/CGAL/Kernel/function_objects.h

@@ -205,6 +205,44 @@ namespace CommonKernelFunctors {
   public:
     typedef typename K::Comparison_result  result_type;
 
+    result_type
+    operator()(const Point_3& a1, const Point_3& b1, const Point_3& c1,
+               const Point_3& a2, const Point_3& b2, const Point_3& c2) const
+    {
+      using FT = typename K::FT;
+      const Vector_3 ba1 = a1 - b1;
+      const Vector_3 bc1 = c1 - b1;
+      const Vector_3 ba2 = a2 - b2;
+      const Vector_3 bc2 = c2 - b2;
+      const FT sc_prod_1 = ba1 * bc1;
+      const FT sc_prod_2 = ba2 * bc2;
+      // Reminder: cos(angle) = scalar_product(ba, bc) / (length(ba)*length(bc))
+      // cosine is decreasing on 0, pi
+      // thus angle1 < angle2 is equivalent to cos(angle1) > cos(angle2)
+      if(sc_prod_1 >= 0) {
+        if(sc_prod_2 >= 0) {
+          // the two cosine are >= 0, we can compare the squares
+          // (square(x) is increasing when x>=0
+          return CGAL::compare(CGAL::square(sc_prod_2)*
+                               ba1.squared_length()*bc1.squared_length(),
+                               CGAL::square(sc_prod_1)*
+                               ba2.squared_length()*bc2.squared_length());
+        } else {
+          return SMALLER;
+        }
+      } else {
+        if(sc_prod_2 < 0) {
+          // the two cosine are < 0, square(x) is decreasing when x<0
+          return CGAL::compare(CGAL::square(sc_prod_1)*
+                               ba2.squared_length()*bc2.squared_length(),
+                               CGAL::square(sc_prod_2)*
+                               ba1.squared_length()*bc1.squared_length());
+        } else {
+          return LARGER;
+        }
+      }
+    }
+
     result_type
     operator()(const Point_3& a, const Point_3& b, const Point_3& c,
                const FT& cosine) const

Kernel_23/include/CGAL/Kernel_23/internal/Projection_traits_3.h

@@ -971,6 +971,7 @@ class Projection_traits_3
   typedef typename Rp::Construct_triangle_3                   Construct_triangle_2;
   typedef typename Rp::Construct_line_3                       Construct_line_2;
 
+  typedef typename Rp::Compare_xyz_3                          Compare_xy_2;
 
   struct Less_xy_2 {
     typedef typename R::Boolean result_type;
@@ -1065,6 +1066,10 @@ class Projection_traits_3
   less_x_2_object() const
     { return Less_x_2();}
 
+  Compare_xy_2
+  compare_xy_2_object() const
+    { return Compare_xy_2();}
+
   Less_xy_2
   less_xy_2_object() const
     { return Less_xy_2();}

Kernel_23/include/CGAL/Kernel_23/internal/Projection_traits_base_3.h

@@ -426,6 +426,7 @@ class Projection_traits_base_3
   typedef typename K::Line_3      Line_2;
 
   typedef typename K::Angle_3                                Angle_2;
+  typedef typename K::Compare_xyz_3                          Compare_xy_2;
 
   typedef TriangulationProjectionTraitsCartesianFunctors::
     Compare_along_axis<Self>                                 Compare_x_2;
@@ -524,6 +525,9 @@ class Projection_traits_base_3
   Angle_2  angle_2_object() const
     {return Angle_2();}
 
+  Compare_xy_2  compare_xy_2_object() const
+    {return Compare_xy_2();}
+
   Construct_point_2  construct_point_2_object() const
     {return Construct_point_2();}
 

Mesh_3/test/Mesh_3/test_meshing_utilities.h

@@ -71,6 +71,8 @@ void verify_time_stamps(const C3t3& c3t3, CGAL::Sequential_tag) {
       assert(prev->time_stamp() < cit->time_stamp());
     }
   }
+  assert(tds.vertices().check_timestamps_are_valid());
+  assert(tds.cells().check_timestamps_are_valid());
 }
 
 // Do not verify time stamps in parallel mode