YT-CPPGL-56: Replace the usage of pointers for vertex storage to a simple composite type [Part 1]

- The `graph` class does not store a list of vertices directly, only the number of vertices and optionally a vertex properties map
- Added a vertex property map getter to the `graph` class
- Vertices are compared only using IDs within the graph representation models
- Removed vertex validation within implementation types - only the `graph` class validates vertices
- The properties members of the vertex and edge classes are now private with added getter methods

Author: SpectraL519

docs/graph.md

@@ -138,14 +138,14 @@ Based on the specified traits, the `graph` class defines the following types:
 ### Vertex Operations
 
 - **`graph.vertices() const`**:
-  - *Description*: Returns an iterator range over all vertices in the graph.
+  - *Description*: Returns an view over all vertices in the graph.
   - *Returned value*: $V$
-  - *Return type*: `types::iterator_range<vertex_iterator_type>`
+  - *Return type*: A random access *view* with values of type `vertex_type`.
 
 - **`graph.vertex_ids() const`**:
   - *Description*: Returns a range of vertex IDs, starting from the initial vertex ID to the number of vertices in the grap.
   - *Returned value*: $(v_{id} : v \in V)$
-  - *Return type*: `std::ranges::iota_view<types::id_type, types::id_type>`
+  - *Return type*: A random access *view* with values of type `types::id_type` : `std::ranges::iota_view`.
 
 - **`graph.get_vertex(vertex_id) const`**:
   - *Description*: Retrieves the vertex object associated with the given vertex ID.
@@ -296,6 +296,10 @@ Based on the specified traits, the `graph` class defines the following types:
   - *Description*: Returns a vector containing the degrees of the corresponding vertices (degree at index `i` corresponds to the vertex with an ID equal `i`).
   - *Return type*: `std::vector<types::size_type>`
 
+- **`graph.vertex_properties_map() const`**:
+  - *Description*: Returns a *map-like view* the properties of the corresponding vertices (property at index `i` corresponds to the vertex with an ID equal `i`).
+  - *Return type*: A random access view with values of type `vertex_properties_type&`
+
 <br />
 
 ### Edge Operations

docs/graph_elements.md

@@ -14,17 +14,17 @@ This section provides an overview of the `vertex_descriptor` and `edge_descripto
 
 ## The vertex class
 
-The `vertex_descriptor` class represents the identity of a vertex in the graph, optionally carrying additional properties as specified by the user. This class is designed for use within the `Graph` class and serves as a lightweight identifier for vertices, providing an interface for accessing vertex properties, comparing vertex descriptors, and outputting vertex information.
+The `vertex_descriptor` class represents the vertex in the graph, optionally carrying additional properties as specified by the user. This class is designed for use within the `graph` class and serves as a lightweight identifier for vertices, providing an interface for accessing vertex properties, comparing vertex descriptors, and outputting vertex information.
 
 By default, the `vertex_descriptor` class does not carry any properties. However, properties can be associated with each vertex by passing a custom type as the template parameter `Properties`, making it highly flexible and customizable for various graph use cases.
 
-### Template parameters
+### Template Parameters
 
 - **`Properties`**: A type that defines the properties associated with each vertex.
   - *Default value*:  `types::empty_properties`
   - *Constraints*: must satisfy the **`type_traits::c_properties`** concept
 
-### Member types
+### Member Types
 
 - **`type`**: Alias for the `vertex_descriptor` itself.
 - **`properties_type`**: Type of the vertex properties as defined by the `Properties` template parameter.
@@ -37,10 +37,10 @@ By default, the `vertex_descriptor` class does not carry any properties. However
   - Constructs a `vertex_descriptor` with a unique ID and specified properties.
   - *Constraints*: the `properties_type` must be non-default.
 - **Move constructor and assignment operator**: *default*
+- **Copy constructor and assignment operator**: *default*
 
 - **Deleted**:
   - **Default constructor**: prevent creating multiple vertices with the default ID within a graph.
-  - **Copy constructor and assignment operator**: prevent copying of `vertex_descriptor` instances, as they are meant to be identificators.
 
 ### Desctructor
 
@@ -52,6 +52,10 @@ The destructor is *defaulted*, allowing proper cleanup of the `vertex_descriptor
   - *Description*: Returns the unique identifier of the vertex.
   - *Return type*: `types::id_type`
 
+- **`properties()`**:
+  - *Description*: Returns a mutable reference to the properties associated with the vertex.
+  - *Return type*: `properties_type&`
+
 - **`operator==(const vertex_descriptor& other) const`**:
   - *Description*: Compares two `vertex_descriptor` objects for equality based on their vertex IDs.
   - *Parameters*:
@@ -64,12 +68,6 @@ The destructor is *defaulted*, allowing proper cleanup of the `vertex_descriptor
     - `other: const vertex_descriptor&` – the vertex descriptor to compare with.
   - *Return type*: `std::strong_ordering`
 
-### Member variables
-
-- **`properties`**:
-  - *Description*: A mutable member that stores the properties associated with the vertex.
-  - *Type*: Defined by the `Properties` template parameter.
-
 ### Additional utility
 
 - **`vertex`**: A convenient alias for `vertex_descriptor` with customizable properties.
@@ -137,6 +135,11 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
   - *Returned value*: $(u, v)$
   - *Return type*: `types::homogeneous_pair<const vertex_type&>`
 
+- **`incident_vertex_ids() const`**:
+  - *Description*: Returns the unique IDs of the vertices connected by the edge.
+  - *Returned value*: $(u_{id}, v_{id})$
+  - *Return type*: `types::homogeneous_pair<types::id_type>`
+
 - **`first() const`**:
   - *Description*: Returns a reference to the first vertex of the edge.
   - *Returned value*: $u$
@@ -147,22 +150,7 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
   - *Returned value*: $v$
   - *Return type*: `const vertex_type&`
 
-- **`incident_vertex_ids() const`**:
-  - *Description*: Returns the unique IDs of the vertices connected by the edge.
-  - *Returned value*: $(u_{id}, v_{id})$
-  - *Return type*: `types::homogeneous_pair<types::id_type>`
-
-- **`first_id() const`**:
-  - *Description*: Returns the ID of the first vertex.
-  - *Returned value*: $u_{id}$
-  - *Return type*: `types::id_type`
-
-- **`second_id() const`**:
-  - *Description*: Returns the ID of the second vertex.
-  - *Returned value*: $v_{id}$
-  - *Return type*: `types::id_type`
-
-- **`incident_vertex(const vertex_type& vertex) const`**:
+- **`incident_vertex(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*:
     - $v$ if $\text{vertex} = u$
@@ -172,24 +160,31 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
     - `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.
+- **`incident_vertex(vertex_id) const`**:
+  - *Description*: Returns 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*:
-    - $v_{id}$ if $\text{vertex-id} = u_{id}$
-    - $u_{id}$ if $\text{vertex-id} = v_{id}$
+    - $v$ if $\text{vertex-id} = u_{id}$
+    - $u$ 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`
 
-- **`is_incident_with(const vertex_type& vertex) const`**:
+- **`is_incident_with(vertex) const`**:
   - *Description*: Returns `true` if the provided vertex is connected to the edge.
   - *Returned value*: $\text{vertex} \in {u, v}$
   - *Parameters*:
     - `vertex: const vertex_type&` – the vertex to check for incidence with the edge.
   - *Return type*: `bool`
 
-- **`is_incident_from(const vertex_type& vertex) const`**:
+- **`is_incident_with(vertex_id) const`**:
+  - *Description*: Returns `true` if a vertex with the given ID is connected to the edge.
+  - *Returned value*: $\text{vertex-id} \in {u_{id}, v_{id}}$
+  - *Parameters*:
+    - `vertex_id: const types::id_type` – the vertex ID to check for incidence with the edge.
+  - *Return type*: `bool`
+
+- **`is_incident_from(vertex) const`**:
   - *Description*: Returns `true` if the provided vertex is the source of the edge (for directed edges).
   - *Returned value*:
     - For directed edges: $\text{vertex} = u$
@@ -198,7 +193,16 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
     - `vertex: const vertex_type&` – the vertex to check if it is the source.
   - *Return type*: `bool`
 
-- **`is_incident_to(const vertex_type& vertex) const`**:
+- **`is_incident_from(vertex_id) const`**:
+  - *Description*: Returns `true` if a vertex with the given ID is the source of the edge.
+  - *Returned value*:
+    - For directed edges: $\text{vertex-id} = u_{id}$
+    - For undirected edges: `is_incident_with(vertex)`
+  - *Parameters*:
+    - `vertex_id: const types::id_type` – the vertex ID to check if it is the source.
+  - *Return type*: `bool`
+
+- **`is_incident_to(vertex) const`**:
   - *Description*: Returns `true` if the provided vertex is the target vertex of the edge (for directed edges).
   - *Returned value*:
     - For directed edges: $\text{vertex} = v$
@@ -207,17 +211,20 @@ The destructor is *defaulted*, allowing proper cleanup of the `edge_descriptor`
     - `vertex: const vertex_type&` – the vertex to check if it is the target.
   - *Return type*: `bool`
 
+- **`is_incident_to(vertex_id) const`**:
+  - *Description*: Returns `true` if a vertex with the given ID is the target of the edge.
+  - *Returned value*:
+    - For directed edges: $\text{vertex-id} = v_{id}$
+    - For undirected edges: `is_incident_with(vertex)`
+  - *Parameters*:
+    - `vertex_id: const types::id_type` – the vertex ID to check if it is the target.
+  - *Return type*: `bool`
+
 - **`is_loop() const`**:
   - *Description*: Returns `true` if the edge is a loop (i.e., both vertices are the same).
   - *Returned value*: $u = v$
   - *Return type*: `bool`
 
-### Member variables
-
-- **`properties`**:
-  - *Description*: A mutable member that stores the properties associated with the edge.
-  - *Type*: Defined by the `Properties` template parameter.
-
 ### Additional utility
 
 - **`edge`**: A convenient alias for `edge_descriptor`, with customizable properties and directionality.

include/gl/algorithm/coloring.hpp

@@ -28,7 +28,7 @@ template <
     coloring_opt.emplace(graph.n_vertices(), bin_color_value::unset);
     auto& coloring = coloring_opt.value();
 
-    for (const auto& root_vertex : graph.vertices()) {
+    for (const auto root_vertex : graph.vertices()) {
         const auto root_id = root_vertex.id();
         if (coloring[root_id].is_set())
             continue;
@@ -80,14 +80,14 @@ template <
     type_traits::c_sized_range_of<types::binary_color> ColorRange>
 requires(type_traits::c_binary_color_properties_type<typename GraphType::vertex_properties_type>)
 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())
         return false;
 
-    using color_type = typename GraphType::vertex_properties_type::color_type;
-    auto color_it = std::ranges::begin(color_range);
-
-    for (const auto& vertex : graph.vertices())
-        vertex.properties.color = color_type{*color_it++};
+    auto vertices = graph.vertices(); // store the view to extend its lifetime
+    for (const auto& [vertex, color] : std::views::zip(vertices, color_range))
+        vertex.properties().color = color;
 
     return true;
 }

include/gl/algorithm/dijkstra.hpp

@@ -121,8 +121,8 @@ template <
         const auto& edge = negative_edge.value().get();
         throw std::invalid_argument(std::format(
             "[alg::dijkstra_shortest_paths] Found an edge with a negative weight: [{}, {} | w={}]",
-            edge.first_id(),
-            edge.second_id(),
+            edge.first().id(),
+            edge.second().id(),
             get_weight<GraphType>(edge)
         ));
     }

include/gl/algorithm/mst.hpp

@@ -80,7 +80,7 @@ template <
         const auto& min_edge = min_edge_info.edge.get();
         const auto min_weight = get_weight<GraphType>(min_edge);
 
-        const auto& target_id = min_edge.incident_vertex_id(min_edge_info.source_id);
+        const auto& target_id = min_edge.incident_vertex(min_edge_info.source_id).id();
         if (visited[target_id])
             continue;
 
@@ -93,7 +93,7 @@ template <
 
         // enqueue all edges adjacent to the `target` vertex if they lead to unvisited verties
         for (const auto& edge : graph.adjacent_edges(target_id))
-            if (not visited[edge.incident_vertex_id(target_id)])
+            if (not visited[edge.incident_vertex(target_id).id()])
                 edge_queue.emplace(edge, target_id);
     }
 
@@ -157,7 +157,7 @@ requires type_traits::c_has_numeric_limits_max<types::vertex_distance_type<Graph
         // Update adjacent vertices
         for (const auto& edge : graph.adjacent_edges(vertex_id)) {
             const auto edge_weight = get_weight<GraphType>(edge);
-            const auto incident_vertex_id = edge.incident_vertex_id(vertex_id);
+            const auto incident_vertex_id = edge.incident_vertex(vertex_id).id();
 
             if (not in_mst[incident_vertex_id] && edge_weight < min_cost[incident_vertex_id]) {
                 min_cost[incident_vertex_id] = edge_weight;