YT-CPPHGL-37: HGL module API refinement

- Added generic hypergraph class aliases:
  - Directional: undirected_hypergraph, bf_directed_hypergraph
  - Implementation: list_hypergraph, flat_list_hypergraph, matrix_hypergraph, flat_matrix_hypergraph
- Renamed the order and size methods of the hypergraph class to n_vertices and n_hyperedges (Least Astonishment)
- Renamed the tail/head collection getters:
  - Descriptor collections: tail_vertices, head_vertices to tail, head
  - ID collections: tail_vertex_ids, head_vertex_ids to tail_ids, head_ids
- Removed the get_ prefixes from hypergraph class getter methods
- Added new vertex_unchecked and hyperedge_unchecked methods
- Defined the vertex_t and hyperedge_t element tag types
- Implemented convenience element accessors in the hypergraph class: at(<tag>, id) and operator[](<tag>, id)
- Extended hyperedge descriptor class with operator* and operator-> property accessors

Author: SpectraL519

include/gl/edge_descriptor.hpp

@@ -26,10 +26,6 @@ class edge_descriptor final {
     using id_type = IdType;
     using directional_tag = DirectionalTag;
     using properties_type = Properties;
-    using properties_ref_type = std::conditional_t<
-        traits::c_empty_properties<properties_type>,
-        empty_properties,
-        properties_type&>;
 
     friend directional_tag;
 
@@ -156,7 +152,7 @@ class edge_descriptor final {
         return this->_vertices.first == this->_vertices.second;
     }
 
-    [[nodiscard]] gl_attr_force_inline properties_ref_type properties() const
+    [[nodiscard]] gl_attr_force_inline properties_type& properties() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
         this->_validate();

include/gl/graph.hpp

@@ -316,6 +316,20 @@ class graph final {
         return this->successor_ids(vertex.id());
     }
 
+    [[nodiscard]] gl_attr_force_inline vertex_properties_type& vertex_properties(const id_type id
+    ) const
+    requires(traits::c_non_empty_properties<vertex_properties_type>)
+    {
+        this->_verify_vertex_id(id);
+        return *this->_vertex_properties[id];
+    }
+
+    [[nodiscard]] gl_attr_force_inline auto vertex_properties_map() const noexcept
+    requires(traits::c_non_empty_properties<vertex_properties_type>)
+    {
+        return util::deref_view(this->_vertex_properties);
+    }
+
     // --- degree getters ---
 
     [[nodiscard]] gl_attr_force_inline size_type degree(const id_type vertex_id) const {
@@ -559,6 +573,21 @@ class graph final {
         return this->out_edges(vertex.id());
     }
 
+    [[nodiscard]] edge_properties_type& edge_properties(const id_type id) const
+    requires(traits::c_non_empty_properties<edge_properties_type>)
+    {
+        if (id >= this->_n_edges)
+            throw std::out_of_range(std::format("Got invalid edge id [{}]", id));
+
+        return *this->_edge_properties[id];
+    }
+
+    [[nodiscard]] gl_attr_force_inline auto edge_properties_map() const noexcept
+    requires(traits::c_non_empty_properties<edge_properties_type>)
+    {
+        return util::deref_view(this->_edge_properties);
+    }
+
     // --- adjacency and incidence methods ---
 
     [[nodiscard]] gl_attr_force_inline bool are_adjacent(
@@ -595,37 +624,6 @@ class graph final {
         return this->are_incident(vertex, edge);
     }
 
-    // --- property getters ---
-
-    [[nodiscard]] gl_attr_force_inline auto vertex_properties_map() const noexcept
-    requires(traits::c_non_empty_properties<vertex_properties_type>)
-    {
-        return util::deref_view(this->_vertex_properties);
-    }
-
-    [[nodiscard]] gl_attr_force_inline vertex_properties_type& vertex_properties(const id_type id
-    ) const
-    requires(traits::c_non_empty_properties<vertex_properties_type>)
-    {
-        this->_verify_vertex_id(id);
-        return *this->_vertex_properties[id];
-    }
-
-    [[nodiscard]] gl_attr_force_inline auto edge_properties_map() const noexcept
-    requires(traits::c_non_empty_properties<edge_properties_type>)
-    {
-        return util::deref_view(this->_edge_properties);
-    }
-
-    [[nodiscard]] edge_properties_type& get_edge_properties(const id_type id) const
-    requires(traits::c_non_empty_properties<edge_properties_type>)
-    {
-        if (id >= this->_n_edges)
-            throw std::out_of_range(std::format("Got invalid edge id [{}]", id));
-
-        return *this->_edge_properties[id];
-    }
-
     // --- comparison ---
 
     [[nodiscard]] friend bool operator==(const graph& lhs, const graph& rhs) noexcept {

include/gl/vertex_descriptor.hpp

@@ -25,10 +25,6 @@ class vertex_descriptor final {
     using type = std::type_identity_t<vertex_descriptor<Properties, IdType>>;
     using id_type = IdType;
     using properties_type = Properties;
-    using properties_ref_type = std::conditional_t<
-        traits::c_empty_properties<properties_type>,
-        empty_properties,
-        properties_type&>;
 
     vertex_descriptor() {
         *this = vertex_descriptor::invalid();
@@ -86,7 +82,7 @@ class vertex_descriptor final {
         return this->_id;
     }
 
-    [[nodiscard]] gl_attr_force_inline properties_ref_type properties() const
+    [[nodiscard]] gl_attr_force_inline properties_type& properties() const
     requires(traits::c_non_empty_properties<properties_type>)
     {
         this->_validate();

include/hgl/algorithm/core.hpp

@@ -98,7 +98,7 @@ struct traversal_policy<H, traversal_direction::forward> {
     }
 
     static auto target_vertices(const H& h, typename H::id_type he_id) {
-        return h.head_vertex_ids(he_id);
+        return h.head_ids(he_id);
     }
 };
 
@@ -109,7 +109,7 @@ struct traversal_policy<H, traversal_direction::backward> {
     }
 
     static auto target_vertices(const H& h, typename H::id_type he_id) {
-        return h.tail_vertex_ids(he_id);
+        return h.tail_ids(he_id);
     }
 };
 

include/hgl/algorithm/traversal/backward_search.hpp

@@ -26,7 +26,7 @@ return_type<Result, search_tree<H>> backward_bfs(
 ) {
     using id_type = typename H::id_type;
 
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
     auto tail_unvisited = hypergraph.tail_size_map() | std::ranges::to<std::vector>();
 
     auto stree = init_search_tree<Result>(hypergraph);
@@ -67,7 +67,7 @@ return_type<Result, search_tree<H>> backward_dfs(
 ) {
     using id_type = typename H::id_type;
 
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
     auto tail_unvisited = hypergraph.tail_size_map() | std::ranges::to<std::vector>();
 
     auto stree = init_search_tree<Result>(hypergraph);

include/hgl/algorithm/traversal/breadth_first_search.hpp

@@ -21,8 +21,8 @@ return_type<Result, search_tree<H>> breadth_first_search(
     const PreVisitCallback& pre_visit = {},
     const PostVisitCallback& post_visit = {}
 ) {
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
-    std::vector<bool> visited_hyperedges(hypergraph.size(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
+    std::vector<bool> visited_hyperedges(hypergraph.n_hyperedges(), false);
 
     auto stree = init_search_tree<Result>(hypergraph);
 

include/hgl/algorithm/traversal/depth_first_search.hpp

@@ -21,8 +21,8 @@ return_type<Result, search_tree<H>> depth_first_search(
     const PreVisitCallback& pre_visit = {},
     const PostVisitCallback& post_visit = {}
 ) {
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
-    std::vector<bool> visited_hyperedges(hypergraph.size(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
+    std::vector<bool> visited_hyperedges(hypergraph.n_hyperedges(), false);
 
     auto stree = init_search_tree<Result>(hypergraph);
 

include/hgl/algorithm/traversal/forward_search.hpp

@@ -26,7 +26,7 @@ return_type<Result, search_tree<H>> forward_bfs(
 ) {
     using id_type = typename H::id_type;
 
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
     auto head_unvisited = hypergraph.head_size_map() | std::ranges::to<std::vector>();
 
     auto stree = init_search_tree<Result>(hypergraph);
@@ -67,7 +67,7 @@ return_type<Result, search_tree<H>> forward_dfs(
 ) {
     using id_type = typename H::id_type;
 
-    std::vector<bool> visited_vertices(hypergraph.order(), false);
+    std::vector<bool> visited_vertices(hypergraph.n_vertices(), false);
     auto head_unvisited = hypergraph.head_size_map() | std::ranges::to<std::vector>();
 
     auto stree = init_search_tree<Result>(hypergraph);

include/hgl/algorithm/util.hpp

@@ -15,7 +15,7 @@ template <result_discriminator Result, traits::c_hypergraph H>
 ) {
     using return_t = non_void_return_type<Result, search_tree<H>>;
     if constexpr (Result == ret)
-        return return_t(hypergraph.order());
+        return return_t(hypergraph.n_vertices());
     else
         return return_t();
 }

include/hgl/conversion.hpp

@@ -58,8 +58,8 @@ template <traits::c_hypergraph_impl_tag TargetImplTag, traits::c_hypergraph_impl
 struct to_impl {
     template <typename TargetHypergraph, typename SourceHypergraph>
     static void convert(TargetHypergraph& target, SourceHypergraph& source) {
-        target._impl.add_vertices(source.order());
-        target._impl.add_hyperedges(source.size());
+        target._impl.add_vertices(source.n_vertices());
+        target._impl.add_hyperedges(source.n_hyperedges());
 
         if constexpr (traits::c_undirected_hypergraph<TargetHypergraph>) {
             for (const auto eid : source.hyperedge_ids())
@@ -68,9 +68,9 @@ struct to_impl {
         }
         else {
             for (const auto eid : source.hyperedge_ids()) {
-                for (const auto vid : source.tail_vertex_ids(eid))
+                for (const auto vid : source.tail_ids(eid))
                     target._impl.bind_tail(vid, eid);
-                for (const auto vid : source.head_vertex_ids(eid))
+                for (const auto vid : source.head_ids(eid))
                     target._impl.bind_head(vid, eid);
             }
         }
@@ -248,7 +248,7 @@ template <gl::traits::c_undirected_graph G>
     const auto rem = std::ranges::unique(edges);
     edges.erase(rem.begin(), rem.end());
 
-    G g{h.order()};
+    G g{h.n_vertices()};
     for (const auto& edge : edges)
         g.add_edge(edge.first, edge.second);
     return g;
@@ -267,8 +267,8 @@ template <gl::traits::c_directed_graph G>
     std::vector<edge_vertices> edges;
 
     for (const auto eid : h.hyperedge_ids()) {
-        auto sources = h.tail_vertex_ids(eid);
-        const auto targets = h.head_vertex_ids(eid) | std::ranges::to<std::vector>();
+        auto sources = h.tail_ids(eid);
+        const auto targets = h.head_ids(eid) | std::ranges::to<std::vector>();
         for (const auto u : sources)
             for (const auto v : targets)
                 edges.emplace_back(u, v);
@@ -278,7 +278,7 @@ template <gl::traits::c_directed_graph G>
     const auto rem = std::ranges::unique(edges);
     edges.erase(rem.begin(), rem.end());
 
-    G g{h.order()};
+    G g{h.n_vertices()};
     for (const auto& [u, v] : edges)
         g.add_edge(u, v);
 
@@ -296,9 +296,9 @@ template <gl::traits::c_undirected_graph G>
 [[nodiscard]] G incidence_graph(const traits::c_undirected_hypergraph auto& h) {
     using g_id_type = typename G::id_type;
 
-    G g{h.order() + h.size()};
+    G g{h.n_vertices() + h.n_hyperedges()};
     const auto align_edge_id =
-        [shift = static_cast<g_id_type>(h.order())](const auto eid) -> g_id_type {
+        [shift = static_cast<g_id_type>(h.n_vertices())](const auto eid) -> g_id_type {
         return eid + shift;
     };
 
@@ -323,9 +323,9 @@ template <gl::traits::c_directed_graph G>
 [[nodiscard]] G incidence_graph(const traits::c_bf_directed_hypergraph auto& h) {
     using g_id_type = typename G::id_type;
 
-    G g{h.order() + h.size()};
+    G g{h.n_vertices() + h.n_hyperedges()};
     const auto align_edge_id =
-        [shift = static_cast<g_id_type>(h.order())](const auto eid) -> g_id_type {
+        [shift = static_cast<g_id_type>(h.n_vertices())](const auto eid) -> g_id_type {
         return eid + shift;
     };
 
@@ -336,7 +336,7 @@ template <gl::traits::c_directed_graph G>
         g.add_edges_from(vid, targets);
     }
     for (const auto eid : h.hyperedge_ids()) {
-        const auto targets = h.head_vertex_ids(eid) | std::ranges::to<std::vector<g_id_type>>();
+        const auto targets = h.head_ids(eid) | std::ranges::to<std::vector<g_id_type>>();
         g.add_edges_from(align_edge_id(eid), targets);
     }