components.h

Go to the documentation of this file.

/**
 
    @file      components.h
    @author    Khrapov
    @date      7.03.2021
    @copyright © Nick Khrapov, 2021. All right reserved.
 
**/
#pragma once
 
#include <qx/macros/common.h>
#include <qx/priority.h>
#include <qx/rtti/rtti.h>
#include <qx/rtti/rtti_cast.h>
 
#include <atomic>
#include <map>
#include <optional>
#include <ranges>
#include <unordered_map>
 
namespace qx
{
 
enum class component_status
{
    default_value = 0,
    disabled      = 1 << 0,
};
 
/**
 
    @class   component_status_key
    @brief   A class that acts like time_ordered_priority_key but has a status field
    @author  Khrapov
    @date    10.08.2025
 
    **/
class component_status_key : public time_ordered_priority_key
{
public:
    constexpr component_status_key() noexcept = default;
 
    /**
        @brief status object constructor
        @param ePriority    - key priority
        @param eStatusFlags - object status
        **/
    component_status_key(priority ePriority, flags<component_status> eStatusFlags) noexcept;
 
    /**
        @brief  Get object status
        @retval  - object status
        **/
    constexpr flags<component_status> get_status_flags() const noexcept;
 
    /**
        @brief Set object status
        @param eStatusFlags - object status
        **/
    constexpr void set_status_flags(flags<component_status> eStatusFlags) noexcept;
 
    using time_ordered_priority_key::operator<;
    constexpr bool operator==(const component_status_key&) const noexcept = default;
 
private:
    flags<component_status> m_eStatusFlags = component_status::default_value;
};
 
/**
 
    @class   components
    @brief   Container for components system
    @details Stores components and allows them to be accessed by a template argument or a class id.
             Each component has a priority, which is used to iterate through a sequence of objects of a type (final or any super type)
             or to use getter methods, where a component with the highest priority will be given.
             You can use qx::priority::disabled to exclude the component from iteration or getters result.
    @tparam  base_component_t - base component type
    @author  Khrapov
    @date    9.03.2021
 
**/
template<std::derived_from<rtti_pure_base> base_component_t>
class components
{
public:
    using pointer_type = std::unique_ptr<base_component_t>;
 
private:
    struct class_data
    {
        std::unordered_map<class_id, std::unique_ptr<class_data>> derivedClasses;
        std::vector<pointer_type>                                 components;
        std::multimap<component_status_key, base_component_t*>    priorityCache;
 
        [[nodiscard]] class_data& get_or_add_class_data(class_id id) noexcept;
    };
 
public:
    /**
        @brief  Add a component
        @tparam component_t - component type which doesn't have to be a final class type, may be any base or super type 
        @param  pComponent  - component object
        @param  ePriority   - initial component priority
        @param  statusFlags - initial component status
        @retval             - raw component pointer which acts like a component's handle
    **/
    template<std::derived_from<base_component_t> component_t>
    [[maybe_unused]] component_t* add(
        std::unique_ptr<component_t> pComponent,
        priority                     ePriority   = priority::normal,
        flags<component_status>      statusFlags = component_status::default_value) noexcept;
 
    /**
        @brief  Remove the component from the container
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @retval               - component object
    **/
    [[maybe_unused]] std::unique_ptr<base_component_t> remove(const base_component_t* pRawComponent) noexcept;
 
    /**
        @brief  Try to get a component of the given type with the highest priority
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component pointer or nullptr
    **/
    template<std::derived_from<base_component_t> component_t>
    [[nodiscard]] component_t* try_get(bool bIncludeDisabled = false) noexcept;
 
    /**
        @brief  Try to get a component of the given type with the highest priority
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component pointer or nullptr
    **/
    template<std::derived_from<base_component_t> component_t>
    [[nodiscard]] const component_t* try_get(bool bIncludeDisabled = false) const noexcept;
 
    /**
        @brief  Try to get a component of the given type id with the highest priority
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  id               - type id
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component pointer or nullptr
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] component_t* try_get(class_id id, bool bIncludeDisabled = false) noexcept;
 
    /**
        @brief  Try to get a component of the given type id with the highest priority
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  id               - type id
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component pointer or nullptr
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] const component_t* try_get(class_id id, bool bIncludeDisabled = false) const noexcept;
 
    /**
        @brief  Get a component of the given type with the highest priority (no existence checks are performed)
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component reference
    **/
    template<std::derived_from<base_component_t> component_t>
    [[nodiscard]] component_t& get(bool bIncludeDisabled = false) noexcept;
 
    /**
        @brief  Get a component of the given type with the highest priority (no existence checks are performed)
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component reference
    **/
    template<std::derived_from<base_component_t> component_t>
    [[nodiscard]] const component_t& get(bool bIncludeDisabled = false) const noexcept;
 
    /**
        @brief  Get a component of the given type with the highest priority (no existence checks are performed)
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  id               - type id
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component reference
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] base_component_t& get(class_id id, bool bIncludeDisabled = false) noexcept;
 
    /**
        @brief  Get a component of the given type with the highest priority (no existence checks are performed)
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  id               - type id
        @param  bIncludeDisabled - true if a search should include disabled components
        @retval                  - component reference
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] const base_component_t& get(class_id id, bool bIncludeDisabled = false) const noexcept;
 
    /**
        @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
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if the view should include disabled components
        @retval                  - view of components
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] auto view(bool bIncludeDisabled = false) noexcept;
 
    /**
        @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
        @tparam component_t      - component type which doesn't have to be a final class type, may be any base or super type
        @param  bIncludeDisabled - true if the view should include disabled components
        @retval                  - view of components
    **/
    template<std::derived_from<base_component_t> component_t = base_component_t>
    [[nodiscard]] auto view(bool bIncludeDisabled = false) const noexcept;
 
    /**
        @brief  Get component status
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @retval               - component status
    **/
    [[nodiscard]] std::optional<flags<component_status>> get_component_status(
        const base_component_t* pRawComponent) const noexcept;
 
    /**
        @brief  Set (override) a component status
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @param  newStatus     - new component status
        @retval               - true if a component has been found and a new value has been set
    **/
    [[maybe_unused]] bool set_component_status(
        const base_component_t* pRawComponent,
        flags<component_status> newStatus) noexcept;
 
    /**
        @brief  Add new component status flags to the current ones
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @param  newStatuses   - new component status flags 
        @retval               - true if a component has been found and a new value has been set
    **/
    [[maybe_unused]] bool add_component_status(
        const base_component_t* pRawComponent,
        flags<component_status> newStatuses) noexcept;
 
    /**
        @brief  Add component status flags from the current ones
        @param  pRawComponent    - raw component pointer which acts like a component's handle
        @param  statusesToRemove - component status flags to remove
        @retval                  - true if a component has been found and a new value has been set
    **/
    [[maybe_unused]] bool remove_component_status(
        const base_component_t* pRawComponent,
        flags<component_status> statusesToRemove) noexcept;
 
    /**
        @brief  Get component priority
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @retval               - component priority
    **/
    [[nodiscard]] std::optional<priority> get_component_priority(const base_component_t* pRawComponent) const noexcept;
 
    /**
        @brief  Set component priority
        @param  pRawComponent         - raw component pointer which acts like a component's handle
        @param  eNewComponentPriority - new component priority
        @retval                       - true if a component has been found and a new value has been set
    **/
    [[maybe_unused]] bool set_component_priority(
        const base_component_t* pRawComponent,
        priority                eNewComponentPriority) noexcept;
 
    /**
        @brief  Check if container doesn't have any components 
        @retval  - true if container doesn't have any components
    **/
    [[nodiscard]] bool empty() const noexcept;
 
    /**
        @brief Clear the container, e.g. remove all the components
    **/
    void clear() noexcept;
 
private:
    /**
        @brief  Get a status of a given component
        @param  pRawComponent - raw component pointer which acts like a component's handle
        @retval               - status
    **/
    [[nodiscard]] std::optional<component_status_key> get_status(const base_component_t* pRawComponent) const noexcept;
 
    /**
        @brief   Set a status of a given component
        @warning This method may change the container, and you shall not use it while iterating over it
        @param   pRawComponent - raw component pointer which acts like a component's handle
        @param   status        - new component's status
        @retval                - true if the component is found and a status was set
    **/
    [[maybe_unused]] bool set_status(const base_component_t* pRawComponent, component_status_key status) noexcept;
 
    /**
        @brief  Iterate class data of a given type
        @tparam component_t              - final class type
        @tparam callable_t               - a callable that takes a class data
        @param  iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
        @retval                          - final class data object
    **/
    template<
        std::derived_from<base_component_t>                                  component_t,
        callable_c<void, typename components<base_component_t>::class_data&> callable_t>
    class_data& iterate_class_data(callable_t iterateClassDataFunction) noexcept;
 
    /**
        @brief  Iterate class data of a given type
        @tparam component_t              - final class type
        @tparam callable_t               - a callable that takes a class data
        @param  iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
        @retval                          - final class data object
    **/
    template<
        std::derived_from<base_component_t>                                  component_t,
        callable_c<void, typename components<base_component_t>::class_data&> callable_t>
    const class_data& iterate_class_data(callable_t iterateClassDataFunction) const noexcept;
 
    /**
        @brief  Get or add class data
        @tparam component_t - final class type
        @retval             - final class data object
    **/
    template<std::derived_from<base_component_t> component_t>
    class_data& get_or_add_class_data() noexcept;
 
    /**
        @brief  Get or add class data
        @tparam component_t - final class type
        @retval             - final class data object
    **/
    template<std::derived_from<base_component_t> component_t>
    const class_data& get_or_add_class_data() const noexcept;
 
    /**
        @brief  Iterate class data of a given type
        @tparam callable_t               - a callable that takes a class data
        @param  pRawComponent            - an object used to identify a class type
        @param  iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
        @retval                          - final class data object
    **/
    template<callable_c<void, typename components<base_component_t>::class_data&> callable_t>
    class_data& iterate_class_data(const base_component_t* pRawComponent, callable_t iterateClassDataFunction) noexcept;
 
    /**
        @brief  Iterate class data of a given type
        @tparam callable_t               - a callable that takes a class data
        @param  pRawComponent            - an object used to identify a class type
        @param  iterateClassDataFunction - a function that iterates over a class data from base_component_t + 1 to component_t
        @retval                          - final class data object
    **/
    template<callable_c<void, typename components<base_component_t>::class_data&> callable_t>
    const class_data& iterate_class_data(const base_component_t* pRawComponent, callable_t iterateClassDataFunction)
        const noexcept;
 
    /**
        @brief  Get or add class data
        @param  pRawComponent - an object used to identify a class type
        @retval               - final class data object
    **/
    class_data& get_or_add_class_data(const base_component_t* pRawComponent) noexcept;
 
    /**
        @brief  Get or add class data
        @param  pRawComponent - an object used to identify a class type
        @retval               - final class data object
    **/
    const class_data& get_or_add_class_data(const base_component_t* pRawComponent) const noexcept;
 
private:
    class_data m_RootClass;
};
 
} // namespace qx
 
template<>
struct std::hash<qx::component_status_key>
{
    constexpr size_t operator()(const qx::component_status_key& status) const noexcept
    {
        size_t nHash = qx::get_hash<qx::time_ordered_priority_key>(status);
        qx::hash_combine(nHash, status.get_status_flags());
        return nHash;
    }
};
 
#include <qx/containers/components.inl>