utl/include/utl/container/queue.h

/*!
 * \file container/queue.h
 * \brief
 *      A statically allocated queue based on deque.
 *
 * \copyright Copyright (C) 2021 Christos Choutouridis <christos@choutouridis.net>
 *
 * <dl class=\"section copyright\"><dt>License</dt><dd>
 * The MIT License (MIT)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 * </dd></dl>
 */

#ifndef utl_container_queue_h__
#define utl_container_queue_h__

#include <utl/core/impl.h>
#include <utl/container/deque.h>

namespace utl {

/*!
 * \class queue
 * \brief
 *      A statically allocated queue based on deque.
 *
 * We use the \ref deque::push_back() and \ref deque::pop_front() pair from deque's
 * functionality, so at the \c push the increment performed after the insertion.
 * Similarly at the \c pop the decrement performed before the exctraction. This way also
 * the \ref deque::front() and \ref deque::back() stay the same ;)
 *
 * We also provide stream operators.
 *
 * \tparam Data_t       The char-like queued item type. Usually \c char
 * \tparam N            The size of queue
 * \tparam SemiAtomic   True for semi-atomic operation. In that case the \c ring_iterator is also atomic.
 * \note
 *      SemiAtomic means it is safe to for one thread to  push only from front and another can pop.
 */
template <typename Data_t, size_t N, bool SemiAtomic =false>
class queue : public deque<Data_t, N, SemiAtomic> {
    public:
        // meta-identity types
        using queue_t               = queue<Data_t, N, SemiAtomic>;
        using base_type             = deque<Data_t, N, SemiAtomic>;
        using range_t               = typename base_type::range_t;

        // STL
        using value_type            = typename base_type::value_type;
        using reference             = typename base_type::reference;
        using const_reference       = typename base_type::const_reference;
        using pointer               = typename base_type::pointer;
        using const_pointer         = typename base_type::const_pointer;
        using iterator              = typename base_type::iterator;
        using const_iterator        = typename base_type::const_iterator;
        using reverse_iterator      = typename base_type::reverse_iterator;
        using const_reverse_iterator= typename base_type::const_reverse_iterator;

    //! \name Constructor / Destructor
    //! @{
    public:
        //! Default constructor
        constexpr queue () noexcept : base_type() { }

        //! fill contructor
        constexpr queue(const Data_t& value) noexcept : base_type(value) { }

        //! Initializer list contructor
        template <typename ...It>
        constexpr queue(It&& ...it) noexcept : base_type(std::forward<It>(it)...) { }

    //! @}

    //! \name Member access
    //! @{
    public:
        //! \brief      Push an item in the back of the queue
        //! \param it   The item to push
        constexpr void push (const Data_t& it) noexcept {
            base_type::push_back(it);
        }

        //! \brief      Extract an item from the front of the queue and remove it from the queue
        //! \param it   The item to push
        constexpr Data_t pop () noexcept {
            return base_type::pop_front();
        }

        //! \brief      Push an item in the back of the queue
        //! \param it   The item to push
        constexpr queue_t& operator<< (const Data_t& it) noexcept {
            push(it);
            return *this;
        }

        //! \brief      Pop an item from the front of the queue
        //! \param it   The item to write to
        constexpr queue_t& operator>> (Data_t& it) noexcept {
            it = pop();
            return *this;
        }
    //! @}
};

/*!
 * \brief
 *      Pop an item from the front of the queue.
 *
 *  This definition enables the "data << queue" syntax for pop operation
 *
 *  \tparam Data_t      The char-like queued item type. Usually \c char
 *  \tparam N           The size of queue
 *  \tparam SemiAtomic  True for semi-atomic operation. In that case the \c ring_iterator is also atomic.
 *
 *  \param it       The item to write to
 *  \param q        The queue to read from
 *  \return         Reference to the returned item
 */
template <typename Data_t, size_t N, bool SemiAtomic =false>
constexpr Data_t& operator<< (Data_t& it, queue<Data_t, N, SemiAtomic>& q) noexcept {
    it = q.pop();
    return it;
}

} // namespace utl

#endif /* utl_container_queue_h__ */