|
2 | 2 | // This file is part of the CPP-GL project (https://github.com/SpectraL519/cpp-gl). |
3 | 3 | // Licensed under the MIT License. See the LICENSE file in the project root for full license information. |
4 | 4 |
|
| 5 | +/// @file vertex_descriptor.hpp |
| 6 | +/// @brief Defines the vertex_descriptor class, a lightweight wrapper for vertex representations in graphs. |
| 7 | + |
5 | 8 | #pragma once |
6 | 9 |
|
7 | 10 | #include "gl/attributes/force_inline.hpp" |
|
17 | 20 |
|
18 | 21 | namespace gl { |
19 | 22 |
|
| 23 | +/// @ingroup GL GL-Core |
| 24 | +/// @brief A lightweight wrapper around a vertex identifier with optional properties. |
| 25 | +/// |
| 26 | +/// **Module:** Part of the @ref GL-Core "Core Graph Components" group. |
| 27 | +/// |
| 28 | +/// The vertex_descriptor class provides a type-safe and efficient way to represent |
| 29 | +/// vertices in graph structures. It acts as a lightweight wrapper that combines |
| 30 | +/// a unique identifier with optional property data, ensuring safe access and |
| 31 | +/// comparison operations. |
20 | 32 | template < |
21 | 33 | traits::c_properties Properties = empty_properties, |
22 | 34 | traits::c_id_type IdType = default_id_type> |
23 | 35 | class vertex_descriptor final { |
24 | 36 | public: |
| 37 | + /// @brief Type alias for the vertex_descriptor itself. |
25 | 38 | using type = std:: type_identity_t<vertex_descriptor<Properties, IdType>>; |
| 39 | + /// @brief The type used for vertex identifiers. |
26 | 40 | using id_type = IdType; |
| 41 | + /// @brief The type of properties associated with the vertex. |
27 | 42 | using properties_type = Properties; |
28 | 43 |
|
| 44 | + /// @brief Default constructor, initializes to an invalid vertex. |
29 | 45 | vertex_descriptor() { |
30 | 46 | *this = vertex_descriptor::invalid(); |
31 | 47 | } |
32 | 48 |
|
| 49 | + /// @brief Constructs a vertex descriptor with the given ID (for empty properties). |
33 | 50 | explicit vertex_descriptor(const id_type id) |
34 | 51 | requires(traits::c_empty_properties<properties_type>) |
35 | 52 | : _id(id) {} |
36 | 53 |
|
| 54 | + /// @brief Constructs a vertex descriptor with the given ID and properties. |
37 | 55 | explicit vertex_descriptor(const id_type id, properties_type& properties) |
38 | 56 | requires(traits::c_non_empty_properties<properties_type>) |
39 | 57 | : _id(id), _properties(properties) {} |
40 | 58 |
|
| 59 | + /// @brief Returns an invalid vertex descriptor (for empty properties). |
41 | 60 | [[nodiscard]] gl_attr_force_inline static vertex_descriptor invalid() noexcept |
42 | 61 | requires(traits::c_empty_properties<properties_type>) |
43 | 62 | { |
44 | 63 | return vertex_descriptor(invalid_id); |
45 | 64 | } |
46 | 65 |
|
| 66 | + /// @brief Returns an invalid vertex descriptor (for non-empty properties). |
47 | 67 | [[nodiscard]] gl_attr_force_inline static vertex_descriptor invalid() noexcept |
48 | 68 | requires(traits::c_non_empty_properties<properties_type>) |
49 | 69 | { |
50 | 70 | static properties_type invalid_properties{}; |
51 | 71 | return vertex_descriptor(invalid_id, invalid_properties); |
52 | 72 | } |
53 | 73 |
|
| 74 | + /// @brief Copy constructor. |
54 | 75 | vertex_descriptor(const vertex_descriptor&) = default; |
| 76 | + /// @brief Copy assignment operator. |
55 | 77 | vertex_descriptor& operator=(const vertex_descriptor&) = default; |
56 | 78 |
|
| 79 | + /// @brief Move constructor. |
57 | 80 | vertex_descriptor(vertex_descriptor&&) noexcept = default; |
| 81 | + /// @brief Move assignment operator. |
58 | 82 | vertex_descriptor& operator=(vertex_descriptor&&) noexcept = default; |
59 | 83 |
|
| 84 | + /// @brief Destructor. |
60 | 85 | ~vertex_descriptor() = default; |
61 | 86 |
|
| 87 | + /// @brief Equality comparison operator. |
62 | 88 | [[nodiscard]] gl_attr_force_inline bool operator==(const vertex_descriptor& other |
63 | 89 | ) const noexcept { |
64 | 90 | return this->_id == other._id; |
65 | 91 | } |
66 | 92 |
|
| 93 | + /// @brief Three-way comparison operator. |
67 | 94 | [[nodiscard]] gl_attr_force_inline std::strong_ordering operator<=>( |
68 | 95 | const vertex_descriptor& other |
69 | 96 | ) const noexcept { |
70 | 97 | return this->_id <=> other._id; |
71 | 98 | } |
72 | 99 |
|
| 100 | + /// @brief Boolean conversion operator, returns true if the vertex is valid. |
73 | 101 | [[nodiscard]] gl_attr_force_inline operator bool() const noexcept { |
74 | 102 | return this->is_valid(); |
75 | 103 | } |
76 | 104 |
|
| 105 | + /// @brief Checks if the vertex descriptor is valid. |
77 | 106 | [[nodiscard]] gl_attr_force_inline bool is_valid() const noexcept { |
78 | 107 | return this->_id != invalid_id; |
79 | 108 | } |
80 | 109 |
|
| 110 | + /// @brief Returns the vertex ID. |
81 | 111 | [[nodiscard]] gl_attr_force_inline id_type id() const noexcept { |
82 | 112 | return this->_id; |
83 | 113 | } |
84 | 114 |
|
| 115 | + /// @brief Returns a reference to the vertex properties. |
85 | 116 | [[nodiscard]] gl_attr_force_inline properties_type& properties() const |
86 | 117 | requires(traits::c_non_empty_properties<properties_type>) |
87 | 118 | { |
88 | 119 | this->_validate(); |
89 | 120 | return this->_properties.get(); |
90 | 121 | } |
91 | 122 |
|
| 123 | + /// @brief Arrow operator for accessing properties. |
92 | 124 | [[nodiscard]] gl_attr_force_inline properties_type* operator->() const |
93 | 125 | requires(traits::c_non_empty_properties<properties_type>) |
94 | 126 | { |
95 | 127 | this->_validate(); |
96 | 128 | return &this->_properties.get(); |
97 | 129 | } |
98 | 130 |
|
| 131 | + /// @brief Dereference operator for accessing properties. |
99 | 132 | [[nodiscard]] gl_attr_force_inline properties_type& operator*() const |
100 | 133 | requires(traits::c_non_empty_properties<properties_type>) |
101 | 134 | { |
102 | 135 | this->_validate(); |
103 | 136 | return this->_properties.get(); |
104 | 137 | } |
105 | 138 |
|
| 139 | + /// @brief Output stream operator for vertex descriptors. |
106 | 140 | friend std::ostream& operator<<(std::ostream& os, const vertex_descriptor& vertex) { |
107 | 141 | using enum io::detail::option_bit; |
108 | 142 |
|
|
0 commit comments