qxLib
components.h
Go to the documentation of this file.
1 /**
2 
3  @file components.h
4  @author Khrapov
5  @date 7.03.2021
6  @copyright (c) Nick Khrapov, 2021. All right reserved.
7 
8 **/
9 #pragma once
10 
11 #include <qx/macros/common.h>
12 #include <qx/priority.h>
13 #include <qx/rtti/rtti.h>
14 #include <qx/rtti/rtti_cast.h>
15 
16 #include <atomic>
17 #include <map>
18 #include <optional>
19 #include <ranges>
20 #include <unordered_map>
21 
22 namespace qx
23 {
24 
25 enum class component_status
26 {
27  default_value = 0,
28  disabled = 1 << 0,
29 };
30 
31 /**
32 
33  @class component_status_key
34  @brief A class that acts like time_ordered_priority_key but has a status field
35  @author Khrapov
36  @date 10.08.2025
37 
38  **/
40 {
41 public:
42  constexpr component_status_key() noexcept = default;
43 
44  /**
45  @brief status object constructor
46  @param ePriority - key priority
47  @param eStatusFlags - object status
48  **/
49  component_status_key(priority ePriority, flags<component_status> eStatusFlags) noexcept;
50 
51  /**
52  @brief Get object status
53  @return - object status
54  **/
55  constexpr flags<component_status> get_status_flags() const noexcept;
56 
57  /**
58  @brief Set object status
59  @param eStatusFlags - object status
60  **/
61  constexpr void set_status_flags(flags<component_status> eStatusFlags) noexcept;
62 
63  using time_ordered_priority_key::operator<;
64  constexpr bool operator==(const component_status_key&) const noexcept = default;
65 
66 private:
67  flags<component_status> m_eStatusFlags = component_status::default_value;
68 };
69 
70 /**
71 
72  @class components
73  @brief Container for components system
74  @details Stores components and allows them to be accessed by a template argument or a class id.
75  Each component has a priority, which is used to iterate through a sequence of objects of a type (final or any super type)
76  or to use getter methods, where a component with the highest priority will be given.
77  You can use qx::priority::disabled to exclude the component from iteration or getters result.
78  @tparam base_component_t - base component type
79  @author Khrapov
80  @date 9.03.2021
81 
82 **/
83 template<std::derived_from<rtti_pure_base> base_component_t>
85 {
86 public:
87  using pointer_type = std::unique_ptr<base_component_t>;
88 
89 private:
90  struct class_data
91  {
92  std::unordered_map<class_id, std::unique_ptr<class_data>> derivedClasses;
93  std::vector<pointer_type> components;
94  std::multimap<component_status_key, base_component_t*> priorityCache;
95 
96  [[nodiscard]] class_data& get_or_add_class_data(class_id id) noexcept;
97  };
98 
99 public:
100  components() = default;
101  components(const components&) = delete;
102  components& operator=(const components&) = delete;
103  components(components&& other) noexcept = default;
104  components& operator=(components&& other) noexcept;
105  ~components();
106 
107  /**
108  @brief Add a component
109  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
110  @param pComponent - component object
111  @param ePriority - initial component priority
112  @param statusFlags - initial component status
113  @return - raw component pointer which acts like a component's handle
114  **/
115  template<std::derived_from<base_component_t> component_t>
116  [[maybe_unused]] component_t* add(
117  std::unique_ptr<component_t> pComponent,
118  priority ePriority = priority::normal,
119  flags<component_status> statusFlags = component_status::default_value) noexcept;
120 
121  /**
122  @brief Remove the component from the container
123  @param pRawComponent - raw component pointer which acts like a component's handle
124  @return - component object
125  **/
126  [[maybe_unused]] std::unique_ptr<base_component_t> remove(const base_component_t* pRawComponent) noexcept;
127 
128  /**
129  @brief Try to get a component of the given type with the highest priority
130  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
131  @param bIncludeDisabled - true if a search should include disabled components
132  @return - component pointer or nullptr
133  **/
134  template<std::derived_from<base_component_t> component_t>
135  [[nodiscard]] component_t* try_get(bool bIncludeDisabled = false) noexcept;
136 
137  /**
138  @brief Try to get a component of the given type with the highest priority
139  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
140  @param bIncludeDisabled - true if a search should include disabled components
141  @return - component pointer or nullptr
142  **/
143  template<std::derived_from<base_component_t> component_t>
144  [[nodiscard]] const component_t* try_get(bool bIncludeDisabled = false) const noexcept;
145 
146  /**
147  @brief Try to get a component of the given type id with the highest priority
148  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
149  @param id - type id
150  @param bIncludeDisabled - true if a search should include disabled components
151  @return - component pointer or nullptr
152  **/
153  template<std::derived_from<base_component_t> component_t = base_component_t>
154  [[nodiscard]] component_t* try_get(class_id id, bool bIncludeDisabled = false) noexcept;
155 
156  /**
157  @brief Try to get a component of the given type id with the highest priority
158  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
159  @param id - type id
160  @param bIncludeDisabled - true if a search should include disabled components
161  @return - component pointer or nullptr
162  **/
163  template<std::derived_from<base_component_t> component_t = base_component_t>
164  [[nodiscard]] const component_t* try_get(class_id id, bool bIncludeDisabled = false) const noexcept;
165 
166  /**
167  @brief Get a component of the given type with the highest priority (no existence checks are performed)
168  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
169  @param bIncludeDisabled - true if a search should include disabled components
170  @return - component reference
171  **/
172  template<std::derived_from<base_component_t> component_t>
173  [[nodiscard]] component_t& get(bool bIncludeDisabled = false) noexcept;
174 
175  /**
176  @brief Get a component of the given type with the highest priority (no existence checks are performed)
177  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
178  @param bIncludeDisabled - true if a search should include disabled components
179  @return - component reference
180  **/
181  template<std::derived_from<base_component_t> component_t>
182  [[nodiscard]] const component_t& get(bool bIncludeDisabled = false) const noexcept;
183 
184  /**
185  @brief Get a component of the given type with the highest priority (no existence checks are performed)
186  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
187  @param id - type id
188  @param bIncludeDisabled - true if a search should include disabled components
189  @return - component reference
190  **/
191  template<std::derived_from<base_component_t> component_t = base_component_t>
192  [[nodiscard]] base_component_t& get(class_id id, bool bIncludeDisabled = false) noexcept;
193 
194  /**
195  @brief Get a component of the given type with the highest priority (no existence checks are performed)
196  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
197  @param id - type id
198  @param bIncludeDisabled - true if a search should include disabled components
199  @return - component reference
200  **/
201  template<std::derived_from<base_component_t> component_t = base_component_t>
202  [[nodiscard]] const base_component_t& get(class_id id, bool bIncludeDisabled = false) const noexcept;
203 
204  /**
205  @brief Get a view which may be used in a ranged-based for loop and consists of components of a given type with decreasing priority
206  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
207  @param bIncludeDisabled - true if the view should include disabled components
208  @return - view of components
209  **/
210  template<std::derived_from<base_component_t> component_t = base_component_t>
211  [[nodiscard]] auto view(bool bIncludeDisabled = false) noexcept;
212 
213  /**
214  @brief Get a view which may be used in a ranged-based for loop and consists of components of a given type with decreasing priority
215  @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type
216  @param bIncludeDisabled - true if the view should include disabled components
217  @return - view of components
218  **/
219  template<std::derived_from<base_component_t> component_t = base_component_t>
220  [[nodiscard]] auto view(bool bIncludeDisabled = false) const noexcept;
221 
222  /**
223  @brief Get component status
224  @param pRawComponent - raw component pointer which acts like a component's handle
225  @return - component status
226  **/
227  [[nodiscard]] std::optional<flags<component_status>> get_component_status(
228  const base_component_t* pRawComponent) const noexcept;
229 
230  /**
231  @brief Set (override) a component status
232  @param pRawComponent - raw component pointer which acts like a component's handle
233  @param newStatus - new component status
234  @return - true if a component has been found and a new value has been set
235  **/
236  [[maybe_unused]] bool set_component_status(
237  const base_component_t* pRawComponent,
238  flags<component_status> newStatus) noexcept;
239 
240  /**
241  @brief Add new component status flags to the current ones
242  @param pRawComponent - raw component pointer which acts like a component's handle
243  @param newStatuses - new component status flags
244  @return - true if a component has been found and a new value has been set
245  **/
246  [[maybe_unused]] bool add_component_status(
247  const base_component_t* pRawComponent,
248  flags<component_status> newStatuses) noexcept;
249 
250  /**
251  @brief Add component status flags from the current ones
252  @param pRawComponent - raw component pointer which acts like a component's handle
253  @param statusesToRemove - component status flags to remove
254  @return - true if a component has been found and a new value has been set
255  **/
256  [[maybe_unused]] bool remove_component_status(
257  const base_component_t* pRawComponent,
258  flags<component_status> statusesToRemove) noexcept;
259 
260  /**
261  @brief Get component priority
262  @param pRawComponent - raw component pointer which acts like a component's handle
263  @return - component priority
264  **/
265  [[nodiscard]] std::optional<priority> get_component_priority(const base_component_t* pRawComponent) const noexcept;
266 
267  /**
268  @brief Set component priority
269  @param pRawComponent - raw component pointer which acts like a component's handle
270  @param eNewComponentPriority - new component priority
271  @return - true if a component has been found and a new value has been set
272  **/
273  [[maybe_unused]] bool set_component_priority(
274  const base_component_t* pRawComponent,
275  priority eNewComponentPriority) noexcept;
276 
277  /**
278  @brief Check if container doesn't have any components
279  @return - true if container doesn't have any components
280  **/
281  [[nodiscard]] bool empty() const noexcept;
282 
283  /**
284  @brief Clear the container and destroy its components.
285  @details Components are destroyed in reverse priority order, and in reverse addition order within a priority.
286  **/
287  void clear() noexcept;
288 
289 private:
290  /**
291  @brief Get a status of a given component
292  @param pRawComponent - raw component pointer which acts like a component's handle
293  @return - status
294  **/
295  [[nodiscard]] std::optional<component_status_key> get_status(const base_component_t* pRawComponent) const noexcept;
296 
297  /**
298  @brief Set a status of a given component
299  @warning This method may change the container, and you shall not use it while iterating over it
300  @param pRawComponent - raw component pointer which acts like a component's handle
301  @param status - new component's status
302  @return - true if the component is found and a status was set
303  **/
304  [[maybe_unused]] bool set_status(const base_component_t* pRawComponent, component_status_key status) noexcept;
305 
306  /**
307  @brief Iterate class data of a given type
308  @tparam component_t - final class type
309  @tparam callable_t - a callable that takes a class data
310  @param iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
311  @return - final class data object
312  **/
313  template<
314  std::derived_from<base_component_t> component_t,
315  callable_c<void, typename components<base_component_t>::class_data&> callable_t>
316  class_data& iterate_class_data(callable_t iterateClassDataFunction) noexcept;
317 
318  /**
319  @brief Iterate class data of a given type
320  @tparam component_t - final class type
321  @tparam callable_t - a callable that takes a class data
322  @param iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
323  @return - final class data object
324  **/
325  template<
326  std::derived_from<base_component_t> component_t,
327  callable_c<void, typename components<base_component_t>::class_data&> callable_t>
328  const class_data& iterate_class_data(callable_t iterateClassDataFunction) const noexcept;
329 
330  /**
331  @brief Get or add class data
332  @tparam component_t - final class type
333  @return - final class data object
334  **/
335  template<std::derived_from<base_component_t> component_t>
336  class_data& get_or_add_class_data() noexcept;
337 
338  /**
339  @brief Get or add class data
340  @tparam component_t - final class type
341  @return - final class data object
342  **/
343  template<std::derived_from<base_component_t> component_t>
344  const class_data& get_or_add_class_data() const noexcept;
345 
346  /**
347  @brief Iterate class data of a given type
348  @tparam callable_t - a callable that takes a class data
349  @param pRawComponent - an object used to identify a class type
350  @param iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
351  @return - final class data object
352  **/
353  template<callable_c<void, typename components<base_component_t>::class_data&> callable_t>
354  class_data& iterate_class_data(const base_component_t* pRawComponent, callable_t iterateClassDataFunction) noexcept;
355 
356  /**
357  @brief Iterate class data of a given type
358  @tparam callable_t - a callable that takes a class data
359  @param pRawComponent - an object used to identify a class type
360  @param iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
361  @return - final class data object
362  **/
363  template<callable_c<void, typename components<base_component_t>::class_data&> callable_t>
364  const class_data& iterate_class_data(const base_component_t* pRawComponent, callable_t iterateClassDataFunction)
365  const noexcept;
366 
367  /**
368  @brief Get or add class data
369  @param pRawComponent - an object used to identify a class type
370  @return - final class data object
371  **/
372  class_data& get_or_add_class_data(const base_component_t* pRawComponent) noexcept;
373 
374  /**
375  @brief Get or add class data
376  @param pRawComponent - an object used to identify a class type
377  @return - final class data object
378  **/
379  const class_data& get_or_add_class_data(const base_component_t* pRawComponent) const noexcept;
380 
381 private:
382  class_data m_RootClass;
383 };
384 
385 } // namespace qx
386 
387 template<>
388 struct std::hash<qx::component_status_key>
389 {
390  constexpr size_t operator()(const qx::component_status_key& status) const noexcept
391  {
392  size_t nHash = qx::get_hash<qx::time_ordered_priority_key>(status);
393  qx::hash_combine(nHash, status.get_status_flags());
394  return nHash;
395  }
396 };
397 
Class id, unique for each class using qx rtti system.
Definition: class_id.h:27
A class that acts like time_ordered_priority_key but has a status field.
Definition: components.h:40
constexpr void set_status_flags(flags< component_status > eStatusFlags) noexcept
Set object status.
Definition: components.inl:46
constexpr flags< component_status > get_status_flags() const noexcept
Get object status.
Definition: components.inl:40
Container for components system.
Definition: components.h:85
component_t & get(bool bIncludeDisabled=false) noexcept
Get a component of the given type with the highest priority (no existence checks are performed)
Definition: components.inl:185
std::unique_ptr< base_component_t > remove(const base_component_t *pRawComponent) noexcept
Remove the component from the container.
Definition: components.inl:105
bool add_component_status(const base_component_t *pRawComponent, flags< component_status > newStatuses) noexcept
Add new component status flags to the current ones.
Definition: components.inl:271
bool set_component_priority(const base_component_t *pRawComponent, priority eNewComponentPriority) noexcept
Set component priority.
Definition: components.inl:305
void clear() noexcept
Clear the container and destroy its components.
Definition: components.inl:324
component_t * try_get(bool bIncludeDisabled=false) noexcept
Try to get a component of the given type with the highest priority.
Definition: components.inl:139
bool set_component_status(const base_component_t *pRawComponent, flags< component_status > newStatus) noexcept
Set (override) a component status.
Definition: components.inl:258
bool empty() const noexcept
Check if container doesn't have any components.
Definition: components.inl:318
auto view(bool bIncludeDisabled=false) noexcept
Get a view which may be used in a ranged-based for loop and consists of components of a given type wi...
Definition: components.inl:213
bool remove_component_status(const base_component_t *pRawComponent, flags< component_status > statusesToRemove) noexcept
Add component status flags from the current ones.
Definition: components.inl:284
component_t * add(std::unique_ptr< component_t > pComponent, priority ePriority=priority::normal, flags< component_status > statusFlags=component_status::default_value) noexcept
Add a component.
Definition: components.inl:85
std::optional< flags< component_status > > get_component_status(const base_component_t *pRawComponent) const noexcept
Get component status.
Definition: components.inl:250
std::optional< priority > get_component_priority(const base_component_t *pRawComponent) const noexcept
Get component priority.
Definition: components.inl:297
A class that can be used as a key in ordered containers so that items are ordered in descending order...
Definition: priority.h:50
priority
User may use the predefined values or the custom ones, for ex. "normal - 1", this type is supposed to...
Definition: priority.h:30
RTTI system based on polymorphism.