YT-CPPHGL-2: Cleanup of the CPP-GL module implementation and documentation

A small cleanup required for the development of HGL
- Changed the minimum required C++ standard to C++23
- Changed the minimum required GCC version to 14 and CLang version to 18
- Replaced the usage of `std::optional<bool>` as algorithm predicate result type with a new ternary `predicate_result` type
- Removed the `no_return` and `default_return` algorithm-specific types and related concepts; Introduced a `result_discriminator` type in their place
- Aligned the documentation

Author: SpectraL519

.github/workflows/clang.yaml

@@ -19,18 +19,18 @@ jobs:
 
       - name: Prepare
         env:
-          CC: clang-17
-          CXX: clang++-17
+          CC: clang-18
+          CXX: clang++-18
         run: |
-          cmake -B build -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
+          cmake -B build_clang -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
         continue-on-error: false
 
       - name: Build test executable
         run: |
-          cd build && make -j 4
+          cmake --build build_clang/ -j5
         continue-on-error: false
 
       - name: Run tests
         run: |
-          ./build/tests/gl
-          ./build/tests/hgl
+          ./build_clang/tests/gl
+          ./build_clang/tests/hgl

.github/workflows/gpp.yaml

@@ -19,18 +19,18 @@ jobs:
 
       - name: Prepare
         env:
-          CC: gcc-13
-          CXX: g++-13
+          CC: gcc-14
+          CXX: g++-14
         run: |
-          cmake -B build -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
+          cmake -B build_gcc -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
         continue-on-error: false
 
       - name: Build test executable
         run: |
-          cd build && make -j 4
+          cmake --build build_gcc/ -j5
         continue-on-error: false
 
       - name: Run tests
         run: |
-          ./build/tests/gl
-          ./build/tests/hgl
+          ./build_gcc/tests/gl
+          ./build_gcc/tests/hgl

CMakeLists.txt

@@ -9,20 +9,21 @@ endif()
 
 project(cpp-gl
     VERSION 2.0.0
-    DESCRIPTION "General purpose header-only template graph library for C++20"
+    DESCRIPTION "General purpose header-only template graph library for C++23"
     HOMEPAGE_URL "https://github.com/SpectraL519/cpp-gl"
     LANGUAGES CXX
 )
 
+set(MIN_CXX_STANDARD 23)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 option(BUILD_TESTS "Build project tests" OFF)
 
 # Set the proper cxx standard
 if(NOT DEFINED CMAKE_CXX_STANDARD)
-    set(CMAKE_CXX_STANDARD 20)
-elseif(CMAKE_CXX_STANDARD LESS 20)
+    set(CMAKE_CXX_STANDARD ${MIN_CXX_STANDARD})
+elseif(CMAKE_CXX_STANDARD LESS ${MIN_CXX_STANDARD})
     message(WARNING "The defined C++ standard (${CMAKE_CXX_STANDARD}) is too low - overriding!")
-    set(CMAKE_CXX_STANDARD 20)
+    set(CMAKE_CXX_STANDARD ${MIN_CXX_STANDARD})
 endif()
 message(STATUS "The C++ standard is set to ${CMAKE_CXX_STANDARD}")
 

LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2024 Jakub Musiał
-Project: "CPP-GL: General purpose header-only template graph library for C++20 and newer standards."
+Project: "CPP-GL: General purpose header-only template graph library for C++23 and newer standards."
 https://github.com/SpectraL519/cpp-gl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

README.md

@@ -1,6 +1,6 @@
 # CPP-GL
 
-General purpose header-only template graph library for C++20 and newer standards.
+General purpose header-only template graph library for C++23 and newer standards.
 
 [![g++](https://github.com/SpectraL519/cpp-gl/actions/workflows/gpp.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/g++)
 [![clang++](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang.yaml/badge.svg)](https://github.com/SpectraL519/cpp-gl/actions/workflows/clang++)
@@ -65,7 +65,7 @@ FetchContent_MakeAvailable(cpp-gl)
 add_executable(my_project main.cpp)
 
 set_target_properties(my_project PROPERTIES
-    CXX_STANDARD 20 # or newer
+    CXX_STANDARD 23 # or newer
     CXX_STANDARD_REQUIRED YES
 )
 
@@ -128,13 +128,14 @@ The instructions and requirements of working on the `CPP-GL` project can be foun
 
 ## Compiler support
 
+<!--TODO: verify whether the min compiler version is correct for C++23-->
 | Compiler | Min version |
 | :-: | :-: |
-| GNU G++ | 13 |
-| Clang | 17 |
+| GNU G++ | 14 |
+| Clang | 18 |
 
 > [!NOTE]
-> Although currently the project has been properly verified using only the G++ and Clang compilers it should work fine with other compilers with C++20 support like MSVC.
+> Although currently the project has been properly verified using only the G++ and Clang compilers it should work fine with other compilers with C++23 support like MSVC.
 
 <br />
 

docs/algoithms.md

@@ -1,6 +1,6 @@
 # Algorithms
 
-The `CPP-GL` library provides a set of customizable graph algorithms, which are defined in the [gl/algorithms.hpp](/include/gl/algorithms.hpp) header file or in the specific header files in the [gl/algorithm/](/include/gl/algorithm/) directory.
+The `CPP-GL` library provides a set of customizable graph algorithms, which are defined in the [gl/algorithm.hpp](/include/gl/algorithm.hpp) header file or in the specific header files in the [gl/algorithm/](/include/gl/algorithm/) directory.
 
 <br />
 
@@ -31,7 +31,12 @@ This section covers the specific types and type traits used for the algorithm im
 > [!NOTE]
 > All types listed below are defined in the `gl::algorithm` namespace
 
-- `no_return` - A placeholder type to represent algorithms that do not return a value. It is primarily used in type traits to conditionally handle return types.
+- `result_discriminator` - An enumeration type used to discriminate whether the algorithm should return a result value or not.
+  - **Members:**
+    - `ret` - Indicates that the algorithm returns a value.
+    - `noret` - Indicates that the algorithm does not return a value.
+  - The `gl::algorithm` namespace [uses](https://en.cppreference.com/w/cpp/language/enum.html#using_enum_declaration) the `result_discriminator` enum, which allows for the usage of it's members directly from the `gl::algorithm` namespace, e.g. `gl::algorithm::noret`.
+
 - `empty_callback` - Represents an empty callback, used as a default value where no callback functionality is needed.
 
 - `vertex_callback`
@@ -68,6 +73,25 @@ This section covers the specific types and type traits used for the algorithm im
     - `edge: types::const_ref_wrap<EdgeType>` - a constant reference wrapper for the edge.
     - `source_id: types::id_type` - the ID of the source vertex of the held edge.
 
+- `predicate_result`
+  - *Description*: Represents the result of a predicate evaluation.
+  - *Type definitions*:
+    - `eval` - an enumeration type representing the result value.
+      - `ok` - equivalent to `true`.
+      - `not_ok` - equivalent to `false`.
+      - `unknown` - represents an unknown result.
+  - *Constructors*:
+    - `predicate_result(const eval value)` - initializes the object with the given evaluation result.
+    - `predicate_result(const bool value)` - initializes the object with the given boolean value.
+      - If the value is `true`, initializes the object with `eval::ok`.
+      - If the value is `false`, initializes the object with `eval::not_ok`.
+  - *Member variables*:
+    - `value: eval` - the evaluation result.
+  - *Operators*:
+    - `operator bool()` - returns `true` if the result is `eval::ok`, `false` otherwise.
+    - `operator==(const eval& value) const` - returns `true` if the result's value is equal to the given value.
+    - `operator=(const bool value)` - initializes the object with the given boolean value similarly to the boolean constructor.
+
 - `predecessors_descriptor`
   - *Description*: A structure that holds a collection of predecessors for a set of vertices.
   - *Type definitions*:
@@ -93,18 +117,6 @@ This section covers the specific types and type traits used for the algorithm im
 > [!NOTE]
 > All concepts listed below are defined in the `gl::type_traits` namespace
 
-- `c_alg_no_return_type`
-  - *Description*: Checks if the type `T` is `algorithm::no_return`. Used to identify algorithms that do not return a value.
-  - *Template parameters*:
-    - `T` - the type to check.
-  - *Equivalent to*: `std::same_as<T, algorithm::no_return>`
-
-- `c_alg_return_graph_type`
-  - *Description*: Checks if the type `T` is a valid return type for graph algorithms, i.e., either a graph type or `no_return`.
-  - *Template parameters*:
-    - `T` - the type to check.
-  - *Equivalent to*: `c_graph<T> or c_alg_no_return_type<T>`
-
 - `c_empty_callback`
   - *Description*: Checks if a callback type is `algorithm::empty_callback`. Used to determine when no callback is needed for an algorithm.
   - *Template parameters*:
@@ -169,7 +181,7 @@ This section covers the specific types and type traits used for the algorithm im
   - *Description*: Performs an iterative depth-first search (DFS) on the specified graph and conditionally returns a `predecessors_descriptor` instance.
 
   - *Template parameters*:
-    - `AlgReturnType: type_traits::c_alg_return_type` (default = `algorithm::default_return`) - Specifies whether the algorrithm should return the predecessors descriptor or not (can be eigher `algorithm::default_return` or `algorithm::no_return`).
+    - `ResultDiscriminator: result_discriminator` (default = `algorithm::ret`) - Specifies whether the algorrithm should return the predecessors descriptor or not (can be eigher `algorithm::ret` or `algorithm::no_return`).
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
     - `PreVisitCallback: type_traits::c_optional_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_optional_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
@@ -181,24 +193,24 @@ This section covers the specific types and type traits used for the algorithm im
     - `post_visit: const PostVisitCallback&` (default = `{}`) - The callback function to be called after visiting a vertex.
 
   - *Return type*:
-    - `impl::alg_return_type<AlgReturnType, predecessors_descriptor>` - If `AlgReturnType` is `algorithm::no_return` - nothing will be returned (`void`). Otherwise the algorithm will return an instance of `predecessors_descriptor`.
+    - `impl::alg_return_type<ResultDiscriminator, predecessors_descriptor>` - If `ResultDiscriminator` is `algorithm::noret` - nothing will be returned (`void`). Otherwise the algorithm will return an instance of `predecessors_descriptor`.
 
-  - *Defined in*: [gl/algorithm/depth_first_search.hpp](/include/gl/algorithm/deapth_first_search.hpp)
+  - *Defined in*: [gl/algorithm/depth_first_search.hpp](/include/gl/algorithm/depth_first_search.hpp)
 
 - `recursive_depth_first_search(graph, root_vertex_id_opt, pre_visit, post_visit)`
   - *Description*: Performs a recursive depth-first search (DFS) on the specified graph and conditionally returns a `predecessors_descriptor` instance.
 
     **NOTE:** This algoithm has the same template parameters, parameters and return type as the iterative version (`depth_first_search`)
 
-  - *Defined in*: [gl/algorithm/depth_first_search.hpp](/include/gl/algorithm/deapth_first_search.hpp)
+  - *Defined in*: [gl/algorithm/depth_first_search.hpp](/include/gl/algorithm/depth_first_search.hpp)
 
 ### Breadth-first search
 
 - `breadth_first_search(graph, root_vertex_id_opt, pre_visit, post_visit)`
   - *Description*: Performs an breadth-first search (BFS) on the specified graph and conditionally returns a `predecessors_descriptor` instance.
 
   - *Template parameters*:
-    - `AlgReturnType: type_traits::c_alg_return_type` (default = `algorithm::default_return`) - Specifies whether the algorrithm should return the predecessors descriptor or not (can be eigher `algorithm::default_return` or `algorithm::no_return`).
+    - `ResultDiscriminator: result_discriminator` (default = `algorithm::ret`) - Specifies whether the algorrithm should return the predecessors descriptor or not (can be eigher `algorithm::ret` or `algorithm::no_return`).
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
     - `PreVisitCallback: type_traits::c_optional_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_optional_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
@@ -210,7 +222,7 @@ This section covers the specific types and type traits used for the algorithm im
     - `post_visit: const PostVisitCallback&` (default = `{}`) - The callback function to be called after visiting a vertex.
 
   - *Return type*:
-    - `impl::alg_return_type<AlgReturnType, predecessors_descriptor>` - If `AlgReturnType` is `algorithm::no_return` - nothing will be returned (`void`). Otherwise the algorithm will return an instance of `predecessors_descriptor`.
+    - `impl::alg_return_type<ResultDiscriminator, predecessors_descriptor>` - If `ResultDiscriminator` is `algorithm::noret` - nothing will be returned (`void`). Otherwise the algorithm will return an instance of `predecessors_descriptor`.
 
   - *Defined in*: [gl/algorithm/breadth_first_search.hpp](/include/gl/algorithm/breadth_first_search.hpp)
 
@@ -401,7 +413,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
     - `VisitVertexPredicate: type_traits::c_optional_vertex_callback<GraphType, bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_vertex_callback<GraphType, bool, types::id_type>` - The vertex visting callback type (arguments: `vertex, source_id`).
-    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, std::optional<bool>, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
+    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
     - `PreVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
 
@@ -423,7 +435,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
     - `VisitVertexPredicate: type_traits::c_optional_vertex_callback<GraphType, bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_vertex_callback<GraphType, bool, types::id_type>` - The vertex visting callback type (arguments: `vertex, source_id`).
-    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, std::optional<bool>, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
+    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
     - `PreVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
 
@@ -452,7 +464,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
     - `InitQueueRangeType: type_traits::c_sized_range_of<algorithm::vertex_info>` (default = `std::vector<algorithm::vertex_info>`) - The type of the `vertex_info` range which will be inserted into the queue at the beginning of the algorithm.
     - `VisitVertexPredicate: type_traits::c_optional_vertex_callback<GraphType, bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_vertex_callback<GraphType, bool, types::id_type>` - The vertex visting callback type (arguments: `vertex, source_id`).
-    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, std::optional<bool>, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
+    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
     - `PreVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
 
@@ -483,7 +495,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
     - `InitQueueRangeType: type_traits::c_sized_range_of<algorithm::vertex_info>` (default = `std::vector<algorithm::vertex_info>`) - The type of the `vertex_info` range which will be inserted into the queue at the beginning of the algorithm.
     - `VisitVertexPredicate: type_traits::c_optional_vertex_callback<GraphType, bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_vertex_callback<GraphType, bool, types::id_type>` - The vertex visting callback type (arguments: `vertex, source_id`).
-    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, std::optional<bool>, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
+    - `EnqueueVertexPred: type_traits::c_vertex_callback<GraphType, algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)
     - `PreVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called before visiting a vertex.
     - `PostVisitCallback: type_traits::c_vertex_callback<GraphType, void>` (default = `algorithm::empty_callback`) - The type of the callback function called after visiting a vertex.
 

docs/graph_elements.md

@@ -164,14 +164,20 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
 
 - **`incident_vertex(const vertex_type& vertex) const`**:
   - *Description*: Returns the vertex on the other end of the edge relative to the provided vertex. Throws an error if the provided vertex is not incident with the edge.
-  - *Returned value*: $\begin{cases} v & \text{: vertex} = u \\ u & \text{: vertex} = v  \\ \text{error} & \text{: otherwise} \end{cases}$
+  - *Returned value*:
+    - $v$ if $\text{vertex} = u$
+    - $u$ if $\text{vertex} = v$
+    - error otherwise
   - *Parameters*:
     - `vertex: const vertex_type&` – the vertex for which the opposite vertex is requested.
   - *Return type*: `const vertex_type&`
 
 - **`incident_vertex_id(const types::id_type vertex_id) const`**:
   - *Description*: Returns the ID of the vertex on the other end of the edge relative to the provided vertex ID. Throws an error if the provided vertex ID is invalid.
-  - *Returned value*: $\begin{cases} v_{id} & \text{: vertex-id} = u_{id} \\ u_{id} & \text{: vertex-id} = v_{id} \\ \text{error} & \text{: otherwise} \end{cases}$
+  - *Returned value*:
+    - $v_{id}$ if $\text{vertex-id} = u_{id}$
+    - $u_{id}$ if $\text{vertex-id} = v_{id}$
+    - error otherwise
   - *Parameters*:
     - `vertex_id: const types::id_type` – the vertex ID for which the opposite vertex ID is requested.
   - *Return type*: `types::id_type`

include/gl/algorithms.hpp include/gl/algorithm.hppinclude/gl/algorithms.hpp renamed to include/gl/algorithm.hpp

@@ -6,7 +6,7 @@
 
 #include "algorithm/breadth_first_search.hpp"
 #include "algorithm/coloring.hpp"
-#include "algorithm/deapth_first_search.hpp"
+#include "algorithm/depth_first_search.hpp"
 #include "algorithm/dijkstra.hpp"
 #include "algorithm/mst.hpp"
 #include "algorithm/topological_sort.hpp"