fixedcapacityvector.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_containers of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace containers {
 
//==================================================================================================
/// This class fills the gap between standard types <c>std::array</c> and <c>std::vector</c> by
/// implementing a fixed size array, with a current filling size index.
/// With that, methods #push_back and #pop_back could be implemented, which satisfies the constraints
/// given, for example, to underlying containers of type <c>std::priority_queue</c>.
///
/// The rationale here is to use fixed size memory allocation or even stack allocation, in situations
/// where the maximum capacity needed at runtime is known upfront.
///
/// Besides aforementioned methods \c push_back and \c pop_back, a few necessary other methods
/// of parent class <c>std::array</c> have been replaced, but are not explicitly mentioned with
/// this reference documentation. Among them are \c size(), \c end(), \c rend() or \c cend().
///
/// \attention
///   While this type inherits <c>std::array</c> publicly, not all standard methods and type
///   traits have been overwritten according to the ever more complicated C++ specification.
///   Therefore, there is not only no guarantee given that this type behaves as it is supposed to in
///   each and every complex situation (e.g template meta programing).
///   However, the use in accordance with type \c std::priority_queue is certified.
///
/// @tparam T     The type to store.
/// @tparam TSize The fixed sitze of the vector.
//==================================================================================================
template<typename T, std::size_t TSize>
class FixedCapacityVector : public std::array<T, TSize>
{
  protected:
    std::size_t fillSize= 0;       ///< The current fill
 
  public:
    /// Increases the size of this vector by inserting given \p{value} at the end.<br>
    /// In debug compilations an \alib_assertion is raised if this fixed-sized vector's
    /// capacity is exceeded.
    /// @param value The value to insert.
    void push_back( const T& value ) {
        ALIB_ASSERT_ERROR( fillSize < TSize, "MONOMEM/UT",
            "FixedCapacityVector overflow: ", fillSize )
        (*this)[fillSize++]= value;
    }
 
    /// Decreases the size of this vector by destructing and removing the given \p{value} at the
    /// current end.<br>
    /// In debug compilations an \alib_assertion is raised if no elements are left.
    void pop_back() {
        ALIB_ASSERT_ERROR( fillSize > 0   , "MONOMEM/UT",
            "FixedCapacityVector underflow: ", fillSize )
        (*this)[--fillSize].~T();
    }
 
  #if !DOXYGEN
    [[nodiscard]]
    typename std::array<T, TSize>::size_type
    size()                                                                const { return fillSize; }
 
    [[nodiscard]]
    constexpr typename std::array<T, TSize>::iterator       end()                           noexcept
    { return std::array<T, TSize>::begin() + fillSize; }
 
    [[nodiscard]]
    constexpr typename std::array<T, TSize>::const_iterator end()                     const noexcept
    { return std::array<T, TSize>::begin() + fillSize; }
 
    [[nodiscard]]
    constexpr
    typename std::array<T, TSize>::const_iterator           cend()                          noexcept
    { return std::array<T, TSize>::cbegin() + fillSize; }
 
    [[nodiscard]]
    constexpr
    typename std::array<T, TSize>::const_iterator           cend()                    const noexcept
    { return std::array<T, TSize>::cbegin() + fillSize; }
  #endif // !DOXYGEN
 
}; // FixedCapacityVector
 
/// Type alias which denotes a <c>std::priority_queue</c> using
/// a \alib{containers;FixedCapacityVector} as its underlying container type.
template<typename T, std::size_t TSize, typename TCompare= std::less<T>>
using FixedSizePriorityQueue = std::priority_queue< T, FixedCapacityVector<T, TSize>, TCompare>;
 
} // namespace alib[::containers]
 
 
/// Type alias in namespace \b alib.
template<typename T, std::size_t TSize>
using     FixedCapacityVector  =   containers::FixedCapacityVector<T, TSize>;
 
 
/// Type alias in namespace \b alib, which denotes a <c>std::priority_queue</c> using
/// a \alib{containers;FixedCapacityVector} as its underlying container type.
template<typename T, std::size_t TSize, typename TCompare= std::less<T>>
using FixedSizePriorityQueue = std::priority_queue< T, FixedCapacityVector<T, TSize>, TCompare>;
 
} // namespace [alib]