From a9f95cbbb723b43cf7315ea8721356d246922943 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 19 Sep 2025 16:58:27 +0200 Subject: [PATCH 1/2] Add some documentation for the concept/model design pattern --- .../doc/Documentation/Preliminaries.txt | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index f2006d05154..5255ff04fbd 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -43,6 +43,40 @@ also avoid CMake to link with the native threads support library on your system. \cgal is based on the version C++17 of the C++ standard. +\section preliminaries_secconmod Concepts and Models + +One of the core principles of \cgal is algorithmic genericity, enabling users to call +algorithms with custom data types, and to modify their behavior. To achieve this, and following +the examples of the C++ Standard Template Library (STL) and \boost libraries, \cgal makes heavy +use of C++ templates. + +The traditional design pattern used to specify the requirements of these templates is +the concept-model pattern. In this context, a concept is an informal, +abstract set of requirements on a type. A type that satisfies these requirements is said to +model the concept. A concept's requirements are typically syntactic (the set of valid +expressions that a type must support, including member types, member functions, and operators) +and semantic (the expected behavior and invariants of the syntactic requirements) requirements. + +For example, the concept `FaceGraph` describes the requirements for a graph data structure that +explicitly maintains faces defined by halfedges. It requires specific accessors, such as a function +to get an incident halfedge from a face, and a function to get an incident face from a halfedge. +Any class that provides these operations with the expected behavior, such as `CGAL::Surface_mesh` +or `CGAL::Polyhedron_3`, can be said to model the `FaceGraph` concept. This allows these different +data structures to be used interchangeably as arguments to many mesh processing algorithms of \cgal. + +Concepts can also be refined. A refined concept builds upon an existing one by adding +further requirements. For instance, a MutableFaceGraph concept would inherit all the requirements +of FaceGraph but add new ones for operations that modify the graph structure, such as adding or +removing faces. Any type that models MutableFaceGraph also models FaceGraph. + +It is important to note that these concepts from the concept-model design pattern should not be +confused with the first-class concepts language feature introduced in C++20. +The requirements described by the concept-model pattern are more akin to the pre-existing +C++ Named Requirements +found in the C++ standard, which serve as a formal description of the interface and behavior +required of template arguments. The concept-model pattern provides the philosophical framework +for designing generic libraries like \cgal. + \section preliminaries_secchecks Checks Much of the \cgal code contains assert statements for preconditions, and postconditions of functions From 0b5958a3002f81dd18bae1ee4e5df56696109eef Mon Sep 17 00:00:00 2001 From: Sebastien Loriot Date: Fri, 17 Oct 2025 15:28:21 +0200 Subject: [PATCH 2/2] backticks --- Documentation/doc/Documentation/Preliminaries.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/doc/Documentation/Preliminaries.txt b/Documentation/doc/Documentation/Preliminaries.txt index 5255ff04fbd..50d44334d30 100644 --- a/Documentation/doc/Documentation/Preliminaries.txt +++ b/Documentation/doc/Documentation/Preliminaries.txt @@ -65,9 +65,9 @@ or `CGAL::Polyhedron_3`, can be said to model the `FaceGraph` concept. This allo data structures to be used interchangeably as arguments to many mesh processing algorithms of \cgal. Concepts can also be refined. A refined concept builds upon an existing one by adding -further requirements. For instance, a MutableFaceGraph concept would inherit all the requirements -of FaceGraph but add new ones for operations that modify the graph structure, such as adding or -removing faces. Any type that models MutableFaceGraph also models FaceGraph. +further requirements. For instance, a `MutableFaceGraph` concept would inherit all the requirements +of `FaceGraph` but add new ones for operations that modify the graph structure, such as adding or +removing faces. Any type that models `MutableFaceGraph` also models `FaceGraph`. It is important to note that these concepts from the concept-model design pattern should not be confused with the first-class concepts language feature introduced in C++20.