YT-CPPHGL-3: Define the vertex and edge descriptor types

- Added a `hgl::vertex_descriptor` generic alias for the `gl::vertex_descriptor` type.
- Defined the hyperedge directional tag types, i.e. `undirected_t` and `bf_directed_t`
- Implemented a simple `hyperedge_descriptor` generic type
- Aligned the directional-related type constraints in the `gl` module to match the new `hgl` constraints
- Removed redundant `gl` module code

Author: SpectraL519

docs/algorithms.md

@@ -286,7 +286,7 @@ This section covers the specific types and type traits used for the algorithm im
 > The `algorithm::paths_descriptor` structure is defined as follows:
 >
 > - *Template parameters*:
->   - `VertexDistanceType: type_traits::c_basic_arithmetic` - The type of the distance between vertices in the graph.
+>   - `VertexDistanceType: type_traits::c_arithmetic` - The type of the distance between vertices in the graph.
 > - *Type definitions*:
 >   - `distance_type` - An alias for `VertexDistanceType`.
 > - *Constructors*:
@@ -444,7 +444,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
 
   - *Template parameters*:
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
-    - `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.
+    - `InitQueueRangeType: type_traits::c_forward_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_id_callback<bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_optional_id_callback<bool, types::id_type>` - The vertex visting callback type (arguments: `vertex_id, pred_id`).
     - `EnqueueVertexPred: type_traits::c_id_callback<algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex_id, in_edge`)
@@ -475,7 +475,7 @@ Additionaly you can use the depth-first/breadth-first search algorithm templates
   - *Template parameters*:
     - `GraphType: type_traits::c_graph` - The type of the graph on which the search is performed.
     - `PQCompare: std::predicate<algorithm::vertex_info, algorithm::vertex_info>` - The type of the vertex priority queue comparator.
-    - `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.
+    - `InitQueueRangeType: type_traits::c_forward_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_id_callback<bool>` - The vertex visiting unary predicate type.
     - `VisitCallback: type_traits::c_optional_id_callback<bool, types::id_type>` - The vertex visting callback type (arguments: `vertex, source_id`).
     - `EnqueueVertexPred: type_traits::c_id_callback<algorithm::predicate_result, const typename GraphType::edge_type&>` - The vertex enqueue predicate type (arguments: `vertex, in_edge`)

docs/core_util_types.md

@@ -240,7 +240,7 @@ This section describes the type traits that are associated with the property typ
   concept c_weight_properties_type = c_properties<Properties> && requires(Properties p) {
       typename Properties::weight_type;
       { p.weight } -> std::same_as<typename Properties::weight_type&>;
-      requires c_basic_arithmetic<typename Properties::weight_type>;
+      requires c_arithmetic<typename Properties::weight_type>;
   };
   ```
 

docs/graph.md

@@ -90,11 +90,11 @@ Based on the specified traits, the `graph` class defines the following types:
 | `implementation_type` | The underlying data structure used to store the graph's edges and the adjacency information |
 | `vertex_type` | The type of the vertex element (an instantiation of `vertex_descriptor`) |
 | `vertex_properties_type` | The type of the properties element associated with each vertex |
-| `vertex_iterator_type` | The iterator type used for vertex traversal in the graph |
+| `vertex_properties_map_type` | The type of the properties map element associated with each vertex |
 | `edge_type` | The type of the edge element (an instantiation of `edge_descriptor`) |
 | `edge_directional_tag` | The `EdgeDirectionalTag` parameter of the `graph_traits` structure |
 | `edge_properties_type` | The type of the properties element associated with each edge |
-| `edge_iterator_type` | The iterator type used for edge traversal in the graph |
+| `edge_properties_map_type` | The type of the properties map element associated with each edge |
 
 <br />
 <br />
@@ -106,7 +106,7 @@ Based on the specified traits, the `graph` class defines the following types:
 - **`graph()`**:
   - Default constructor. Creates an empty graph with no vertices or edges.
 
-- **`graph(n_vertices)`**:
+- **`explicit graph(n_vertices)`**:
   - Constructs a graph with the specified number of vertices. Each vertex is initialized with default properties and no adjacent edges.
 
 > [!IMPORTANT]
@@ -195,6 +195,9 @@ Based on the specified traits, the `graph` class defines the following types:
 > [!IMPORTANT]
 > Simliarily to the graph constructors using the `add_vertices*` methods is more efficient than calling `add_vertex` multiple times which might cause more vector reallocations.
 
+> [!WARNING]
+> Removing vertices may invalidate previously created vertex and edge descriptor objects.
+
 - **`graph.remove_vertex(vertex_id)`**:
   - *Description*: Removes the vertex with the given ID from the graph.
   - *Parameters*:
@@ -210,15 +213,15 @@ Based on the specified traits, the `graph` class defines the following types:
 - **`graph.remove_vertices_from(vertex_id_range)`**:
   - *Description*: Removes multiple vertices from the graph based on a range of vertex IDs. The IDs are sorted in descending order and duplicate IDs are removed before deletion.
   - *Template parameters*:
-    - `IdRange: type_traits::c_sized_range_of<types::id_type>` – A range of vertex IDs, which must satisfy the size and type constraints.
+    - `IdRange: type_traits::c_forward_range_of<types::id_type>` – A range of vertex IDs, which must satisfy the size and type constraints.
   - *Parameters*:
     - `vertex_id_range: const IdRange&` – A range of vertex IDs to be removed.
   - *Return type*: `void`
 
-- **`graph.remove_vertices_from(vertex_ref_range)`**:
+- **`graph.remove_vertices_from(vertex_range)`**:
   - *Description*: Removes multiple vertices from the graph based on a range of vertex references. The references are sorted in descending order and duplicates are removed before deletion.
   - *Parameters*:
-    - `vertex_ref_range: const type_traits::c_sized_range_of<types::id_type> auto&` – A range of vertex references to be removed.
+    - `vertex_range: const type_traits::c_forward_range_of<types::id_type> auto&` – A range of vertex references to be removed.
   - *Return type*: `void`
 
 - **`graph.in_degree(vertex) const`**:
@@ -434,6 +437,9 @@ Based on the specified traits, the `graph` class defines the following types:
     - `target: const vertex_type&` – the target vertex.
   - *Return type*: `std::vector<edge_type>`
 
+> [!WARNING]
+> Removing edges may invalidate previously created edge descriptor objects.
+
 - **`graph.remove_edge(edge)`**:
   - *Description*: Removes the specified edge from the graph.
   - *Parameters*:
@@ -524,10 +530,6 @@ Based on the specified traits, the `graph` class defines the following types:
 <br />
 <br />
 
-## Additional utility
-
-In addition to the core functionality of the `graph` class, the [gl/graph_utility.hpp](/include/gl/graph_utility.hpp) file provides a set of utility functions and type traits that offer extended support for graph manipulation and property handling. Below is an overview of the key utilities provided.
-
 ### Type traits
 
 To write safe and more expressive graph utility of your own, you can use the defined concepts and type traits:
@@ -537,9 +539,9 @@ To write safe and more expressive graph utility of your own, you can use the def
 
 | **Trait** | **Description** |
 | :- | :- |
-| `c_graph<T>` | Ensures that the template parameter `T` is a specialization of the `graph` class |
-| `c_directed_graph<T>` | Equivalent to `c_graph<T> and is_directed_v<T>`<br/>Ensures that the template parameter `T` is a *directed* specialization of the `graph` class |
-| `c_undirected_graph<T>` | Equivalent to `c_graph<T> and is_undirected_v<T>`<br/>Ensures that the template parameter `T` is an *undirected* specialization of the `graph` class |
+| `c_graph<G>` | Ensures that the template parameter `G` is a specialization of the `graph` class |
+| `c_directed_graph<G>` | Equivalent to `c_graph<G> and c_directed_edge<typename G::edge_type>`<br/>Ensures that the template parameter `G` is a *directed* specialization of the `graph` class |
+| `c_undirected_graph<G>` | Equivalent to `c_graph<G> and c_undirected_edge<typename G::edge_type>`<br/>Ensures that the template parameter `G` is an *undirected* specialization of the `graph` class |
 
 > [!TIP]
 > More (not graph class specific) type traits and concepts are defined in the [gl/types/traits/](/include/gl/types/traits/) directory.

docs/graph_elements.md

@@ -262,6 +262,24 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
   template <type_traits::c_properties Properties = types::empty_properties>
   using undirected_edge = edge_descriptor<undirected_t, Properties>;
   ```
+  
+- `type_traits::c_directed_edge`: A type constraint that accepts only directed edges.
+
+  ```cpp
+  template <typename E>
+  concept c_directed_edge =
+      c_instantiation_of<E, edge_descriptor>
+      and std::same_as<typename E::directional_tag, gl::directed_t>;
+  ```
+  
+- `type_traits::c_undirected_edge`: A type constraint that accepts only undirected edges.
+
+  ```cpp
+  template <typename E>
+  concept c_undirected_edge =
+      c_instantiation_of<E, edge_descriptor>
+      and std::same_as<typename E::directional_tag, gl::undirected_t>;
+  ```
 
 <br />
 <br />

include/gl/algorithm/coloring.hpp

@@ -78,7 +78,7 @@ requires(type_traits::c_binary_color_properties_type<typename GraphType::vertex_
 bool apply_coloring(GraphType& graph, const ColorRange& color_range) {
     using color_type = typename GraphType::vertex_properties_type::color_type;
 
-    if (color_range.size() != graph.n_vertices())
+    if (std::ranges::size(color_range) != graph.n_vertices())
         return false;
 
     auto vertices = graph.vertices(); // store the view to extend its lifetime

include/gl/algorithm/dijkstra.hpp

@@ -4,14 +4,13 @@
 
 #pragma once
 
-#include "gl/graph_utility.hpp"
 #include "impl/pfs.hpp"
 
 #include <deque>
 
 namespace gl::algorithm {
 
-template <type_traits::c_basic_arithmetic VertexDistanceType>
+template <type_traits::c_arithmetic VertexDistanceType>
 struct paths_descriptor : public predecessors_descriptor {
     using predecessor_type = typename predecessors_descriptor::predecessor_type;
     using distance_type = VertexDistanceType;
@@ -97,7 +96,7 @@ template <
             const auto pred_id = in_edge.incident_vertex(vertex_id);
 
             const auto edge_weight = get_weight<GraphType>(in_edge);
-            if (edge_weight < constants::zero) {
+            if (edge_weight < 0) {
                 negative_edge.emplace(in_edge);
                 return predicate_result::unknown;
             }

include/gl/algorithm/impl/bfs.hpp

@@ -12,7 +12,7 @@ namespace gl::algorithm::impl {
 
 template <
     type_traits::c_graph GraphType,
-    type_traits::c_sized_range_of<algorithm::vertex_info> InitQueueRangeType =
+    type_traits::c_forward_range_of<algorithm::vertex_info> InitQueueRangeType =
         std::vector<algorithm::vertex_info>,
     type_traits::c_optional_id_callback<bool> VisitVertexPredicate,
     type_traits::c_optional_id_callback<bool, types::id_type> VisitCallback,
@@ -29,7 +29,7 @@ bool bfs(
     const PreVisitCallback& pre_visit = {},
     const PostVisitCallback& post_visit = {}
 ) {
-    if (initial_queue_content.size() == constants::default_size)
+    if (std::ranges::empty(initial_queue_content))
         return false;
 
     // prepare the vertex queue

include/gl/algorithm/impl/common.hpp

@@ -24,7 +24,7 @@ init_return_value(const GraphType& graph) {
 }
 
 template <
-    type_traits::c_sized_range_of<algorithm::vertex_info> InitRangeType =
+    type_traits::c_forward_range_of<algorithm::vertex_info> InitRangeType =
         std::vector<algorithm::vertex_info>>
 [[nodiscard]] gl_attr_force_inline InitRangeType init_range(types::id_type root_vertex_id) {
     return InitRangeType{algorithm::vertex_info{root_vertex_id}};

include/gl/algorithm/impl/pfs.hpp

@@ -13,7 +13,7 @@ namespace gl::algorithm::impl {
 template <
     type_traits::c_graph GraphType,
     std::predicate<algorithm::vertex_info, algorithm::vertex_info> PQCompare,
-    type_traits::c_sized_range_of<algorithm::vertex_info> InitQueueRangeType =
+    type_traits::c_forward_range_of<algorithm::vertex_info> InitQueueRangeType =
         std::vector<algorithm::vertex_info>,
     type_traits::c_optional_id_callback<GraphType, bool> VisitVertexPredicate,
     type_traits::c_optional_id_callback<bool, types::id_type> VisitCallback,
@@ -31,7 +31,7 @@ bool pfs(
     const PreVisitCallback& pre_visit = {},
     const PostVisitCallback& post_visit = {}
 ) {
-    if (initial_queue_content.size() == constants::default_size)
+    if (std::ranges::empty(initial_queue_content))
         return false;
 
     // prepare the vertex queue

include/gl/algorithm/mst.hpp

@@ -19,11 +19,11 @@ struct mst_descriptor {
     using weight_type = types::vertex_distance_type<graph_type>;
 
     mst_descriptor(const types::size_type n_vertices) {
-        edges.reserve(n_vertices - constants::one);
+        edges.reserve(n_vertices - 1uz);
     }
 
     std::vector<edge_type> edges;
-    weight_type weight = static_cast<weight_type>(constants::zero);
+    weight_type weight = static_cast<weight_type>(0);
 };
 
 template <type_traits::c_undirected_graph GraphType>
@@ -53,14 +53,14 @@ template <type_traits::c_undirected_graph GraphType>
     queue_type edge_queue;
 
     // insert the edges adjacent to the root vertex to the queue
-    const types::id_type root_id = root_id_opt.value_or(constants::zero);
+    const types::id_type root_id = root_id_opt.value_or(constants::initial_id);
 
     for (const auto& edge : graph.adjacent_edges(root_id))
         edge_queue.emplace(edge);
 
     // mark the root vertex as visited
     visited[root_id] = true;
-    types::size_type n_vertices_in_mst = constants::one;
+    types::size_type n_vertices_in_mst = 1uz;
 
     // find the mst
     while (n_vertices_in_mst < n_vertices) {
@@ -104,7 +104,7 @@ requires type_traits::c_has_numeric_limits_max<types::vertex_distance_type<Graph
     std::vector<std::optional<edge_type>> min_cost_edges(n_vertices, std::nullopt);
 
     // set the distance to the root vertex to 0
-    min_cost.at(root_id_opt.value_or(constants::zero)) = constants::zero;
+    min_cost.at(root_id_opt.value_or(constants::initial_id)) = static_cast<distance_type>(0);
 
     auto heap_comparator = [&min_cost](const types::id_type lhs, const types::id_type rhs) {
         return min_cost[lhs] > min_cost[rhs]; // min-heap based on min_cost