annex.hpp

// Copyright (c) 2026 Ryan P. Nicholl <rnicholl@protonmail.com>
 
#ifndef RPNXDATASTRUCTURES_ANNEX_HPP
#define RPNXDATASTRUCTURES_ANNEX_HPP
 
#include <compare>
#include <initializer_list>
#include <memory>
#include <optional>
#include <type_traits>
#include <utility>
 
namespace rpnx
{
    template < typename T, typename Alloc = std::allocator< T > >
    class annex
    {
        static_assert(!std::is_reference_v< T >, "rpnx::annex does not support reference types");
        static_assert(!std::is_void_v< T >, "rpnx::annex does not support void");
 
      public:
        using value_type = T;

        using allocator_type = typename std::allocator_traits< Alloc >::template rebind_alloc< T >;
 
      private:
        using alloc_traits = std::allocator_traits< allocator_type >;
 
        T* m_value = nullptr;
        [[no_unique_address]] allocator_type m_alloc;
 
        template < typename... Args >
        T* allocate_construct(Args&&... args)
        {
            T* ptr = alloc_traits::allocate(m_alloc, 1);
 
            try
            {
                alloc_traits::construct(m_alloc, ptr, std::forward< Args >(args)...);
            }
            catch (...)
            {
                alloc_traits::deallocate(m_alloc, ptr, 1);
                throw;
            }
 
            return ptr;
        }
 
        void destroy_deallocate() noexcept
        {
            if (m_value == nullptr)
            {
                return;
            }
 
            alloc_traits::destroy(m_alloc, m_value);
            alloc_traits::deallocate(m_alloc, m_value, 1);
            m_value = nullptr;
        }
 
        template < typename U >
        void assign_value(U&& value)
        {
            if (m_value != nullptr)
            {
                **this = std::forward< U >(value);
            }
            else
            {
                m_value = allocate_construct(std::forward< U >(value));
            }
        }
 
      public:
        constexpr annex() noexcept(std::is_nothrow_default_constructible_v< allocator_type >) = default;

        constexpr annex(std::nullopt_t) noexcept(std::is_nothrow_default_constructible_v< allocator_type >)
        {
        }

        explicit annex(allocator_type const& alloc) noexcept : m_alloc(alloc)
        {
        }

        annex(std::allocator_arg_t, allocator_type const& alloc) noexcept : m_alloc(alloc)
        {
        }

        annex(annex const& other) : m_alloc(alloc_traits::select_on_container_copy_construction(other.m_alloc))
        {
            if (other.has_value())
            {
                m_value = allocate_construct(*other);
            }
        }

        annex(annex&& other) noexcept(std::is_nothrow_move_constructible_v< allocator_type >) : m_value(other.m_value), m_alloc(std::move(other.m_alloc))
        {
            other.m_value = nullptr;
        }

        template < typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && !std::is_same_v< std::decay_t< U >, annex > && !std::is_same_v< std::decay_t< U >, std::in_place_t > && !std::is_same_v< std::decay_t< U >, std::nullopt_t > && !std::is_same_v< std::decay_t< U >, allocator_type > > >
        annex(U&& value)
        {
            m_value = allocate_construct(std::forward< U >(value));
        }

        template < typename... Args >
        explicit annex(std::in_place_t, Args&&... args)
        {
            m_value = allocate_construct(std::forward< Args >(args)...);
        }

        template < typename U, typename... Args >
        explicit annex(std::in_place_t, std::initializer_list< U > init, Args&&... args)
        {
            m_value = allocate_construct(init, std::forward< Args >(args)...);
        }

        template < typename... Args >
        annex(std::allocator_arg_t, allocator_type const& alloc, std::in_place_t, Args&&... args) : m_alloc(alloc)
        {
            m_value = allocate_construct(std::forward< Args >(args)...);
        }

        template < typename U, typename... Args >
        annex(std::allocator_arg_t, allocator_type const& alloc, std::in_place_t, std::initializer_list< U > init, Args&&... args) : m_alloc(alloc)
        {
            m_value = allocate_construct(init, std::forward< Args >(args)...);
        }

        ~annex()
        {
            destroy_deallocate();
        }

        annex& operator=(std::nullopt_t) noexcept
        {
            reset();
            return *this;
        }

        annex& operator=(annex const& other)
        {
            if (this == &other)
            {
                return *this;
            }
 
            if constexpr (alloc_traits::propagate_on_container_copy_assignment::value)
            {
                if (m_alloc != other.m_alloc)
                {
                    reset();
                }
 
                m_alloc = other.m_alloc;
            }
 
            if (other.has_value())
            {
                assign_value(*other);
            }
            else
            {
                reset();
            }
 
            return *this;
        }

        annex& operator=(annex&& other) noexcept(alloc_traits::propagate_on_container_move_assignment::value && std::is_nothrow_move_assignable_v< allocator_type >)
        {
            if (this == &other)
            {
                return *this;
            }
 
            if constexpr (alloc_traits::propagate_on_container_move_assignment::value)
            {
                reset();
                m_alloc = std::move(other.m_alloc);
                m_value = other.m_value;
                other.m_value = nullptr;
            }
            else
            {
                if (m_alloc == other.m_alloc)
                {
                    reset();
                    m_value = other.m_value;
                    other.m_value = nullptr;
                }
                else if (other.has_value())
                {
                    assign_value(std::move(*other));
                }
                else
                {
                    reset();
                }
            }
 
            return *this;
        }

        template < typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && std::is_assignable_v< T&, U&& > && !std::is_same_v< std::decay_t< U >, annex > && !std::is_same_v< std::decay_t< U >, std::nullopt_t > > >
        annex& operator=(U&& value)
        {
            assign_value(std::forward< U >(value));
            return *this;
        }

        constexpr T const* operator->() const noexcept
        {
            return m_value;
        }

        constexpr T* operator->() noexcept
        {
            return m_value;
        }

        constexpr T const& operator*() const& noexcept
        {
            return *m_value;
        }

        constexpr T& operator*() & noexcept
        {
            return *m_value;
        }

        constexpr T const&& operator*() const&& noexcept
        {
            return std::move(*m_value);
        }

        constexpr T&& operator*() && noexcept
        {
            return std::move(*m_value);
        }

        constexpr explicit operator bool() const noexcept
        {
            return has_value();
        }

        constexpr bool has_value() const noexcept
        {
            return m_value != nullptr;
        }

        T& value() &
        {
            if (!has_value())
            {
                throw std::bad_optional_access();
            }
 
            return **this;
        }

        T const& value() const&
        {
            if (!has_value())
            {
                throw std::bad_optional_access();
            }
 
            return **this;
        }

        T&& value() &&
        {
            if (!has_value())
            {
                throw std::bad_optional_access();
            }
 
            return std::move(**this);
        }

        T const&& value() const&&
        {
            if (!has_value())
            {
                throw std::bad_optional_access();
            }
 
            return std::move(**this);
        }

        template < typename U >
        constexpr T value_or(U&& default_value) const&
        {
            static_assert(std::is_copy_constructible_v< T >);
            static_assert(std::is_convertible_v< U&&, T >);
            return has_value() ? **this : static_cast< T >(std::forward< U >(default_value));
        }

        template < typename U >
        constexpr T value_or(U&& default_value) &&
        {
            static_assert(std::is_move_constructible_v< T >);
            static_assert(std::is_convertible_v< U&&, T >);
            return has_value() ? std::move(**this) : static_cast< T >(std::forward< U >(default_value));
        }

        void swap(annex& other) noexcept(alloc_traits::propagate_on_container_swap::value && std::is_nothrow_swappable_v< allocator_type > && std::is_nothrow_swappable_v< T >)
        {
            using std::swap;
 
            if constexpr (alloc_traits::propagate_on_container_swap::value)
            {
                swap(m_alloc, other.m_alloc);
                swap(m_value, other.m_value);
            }
            else if (has_value() && other.has_value())
            {
                swap(**this, *other);
            }
            else if (has_value())
            {
                other.m_value = other.allocate_construct(std::move(**this));
                reset();
            }
            else if (other.has_value())
            {
                m_value = allocate_construct(std::move(*other));
                other.reset();
            }
        }

        void reset() noexcept
        {
            destroy_deallocate();
        }

        template < typename... Args >
        T& emplace(Args&&... args)
        {
            reset();
            m_value = allocate_construct(std::forward< Args >(args)...);
            return **this;
        }

        template < typename U, typename... Args >
        T& emplace(std::initializer_list< U > init, Args&&... args)
        {
            reset();
            m_value = allocate_construct(init, std::forward< Args >(args)...);
            return **this;
        }

        allocator_type get_allocator() const
        {
            return m_alloc;
        }
    };

    template < typename T, typename Alloc >
    void swap(annex< T, Alloc >& lhs, annex< T, Alloc >& rhs) noexcept(noexcept(lhs.swap(rhs)))
    {
        lhs.swap(rhs);
    }


    template < typename T, typename Alloc >
    bool operator==(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        if (lhs.has_value() != rhs.has_value())
        {
            return false;
        }
 
        return !lhs.has_value() || *lhs == *rhs;
    }

    template < typename T, typename Alloc >
    bool operator!=(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        return !(lhs == rhs);
    }

    template < typename T, typename Alloc >
    bool operator<(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() && (!lhs.has_value() || *lhs < *rhs);
    }

    template < typename T, typename Alloc >
    bool operator>(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs < lhs;
    }

    template < typename T, typename Alloc >
    bool operator<=(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        return !(rhs < lhs);
    }

    template < typename T, typename Alloc >
    bool operator>=(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs)
    {
        return !(lhs < rhs);
    }

    template < typename T, typename Alloc >
        requires requires(T const& lhs, T const& rhs) { lhs <=> rhs; }
    auto operator<=>(annex< T, Alloc > const& lhs, annex< T, Alloc > const& rhs) -> decltype(*lhs <=> *rhs)
    {
        if (lhs.has_value() && rhs.has_value())
        {
            return *lhs <=> *rhs;
        }
 
        if (lhs.has_value())
        {
            return std::strong_ordering::greater;
        }
 
        if (rhs.has_value())
        {
            return std::strong_ordering::less;
        }
 
        return std::strong_ordering::equal;
    }



    template < typename T, typename Alloc >
    bool operator==(annex< T, Alloc > const& lhs, std::nullopt_t) noexcept
    {
        return !lhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator==(std::nullopt_t, annex< T, Alloc > const& rhs) noexcept
    {
        return !rhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator!=(annex< T, Alloc > const& lhs, std::nullopt_t) noexcept
    {
        return lhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator!=(std::nullopt_t, annex< T, Alloc > const& rhs) noexcept
    {
        return rhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator<(annex< T, Alloc > const&, std::nullopt_t) noexcept
    {
        return false;
    }

    template < typename T, typename Alloc >
    bool operator<(std::nullopt_t, annex< T, Alloc > const& rhs) noexcept
    {
        return rhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator<=(annex< T, Alloc > const& lhs, std::nullopt_t) noexcept
    {
        return !lhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator<=(std::nullopt_t, annex< T, Alloc > const&) noexcept
    {
        return true;
    }

    template < typename T, typename Alloc >
    bool operator>(annex< T, Alloc > const& lhs, std::nullopt_t) noexcept
    {
        return lhs.has_value();
    }

    template < typename T, typename Alloc >
    bool operator>(std::nullopt_t, annex< T, Alloc > const&) noexcept
    {
        return false;
    }

    template < typename T, typename Alloc >
    bool operator>=(annex< T, Alloc > const&, std::nullopt_t) noexcept
    {
        return true;
    }

    template < typename T, typename Alloc >
    bool operator>=(std::nullopt_t, annex< T, Alloc > const& rhs) noexcept
    {
        return !rhs.has_value();
    }

    template < typename T, typename Alloc >
    std::strong_ordering operator<=>(annex< T, Alloc > const& lhs, std::nullopt_t) noexcept
    {
        return lhs.has_value() ? std::strong_ordering::greater : std::strong_ordering::equal;
    }

    template < typename T, typename Alloc >
    std::strong_ordering operator<=>(std::nullopt_t, annex< T, Alloc > const& rhs) noexcept
    {
        return rhs.has_value() ? std::strong_ordering::less : std::strong_ordering::equal;
    }



    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator==(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return lhs.has_value() ? *lhs == rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator==(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() ? lhs == *rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator!=(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return !(lhs == rhs);
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator!=(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return !(lhs == rhs);
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator<(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return lhs.has_value() ? *lhs < rhs : true;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator<(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() ? lhs < *rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator<=(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return lhs.has_value() ? *lhs <= rhs : true;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator<=(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() ? lhs <= *rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator>(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return lhs.has_value() ? *lhs > rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator>(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() ? lhs > *rhs : true;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator>=(annex< T, Alloc > const& lhs, U const& rhs)
    {
        return lhs.has_value() ? *lhs >= rhs : false;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >)
    bool operator>=(U const& lhs, annex< T, Alloc > const& rhs)
    {
        return rhs.has_value() ? lhs >= *rhs : true;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >) && requires(T const& lhs, U const& rhs) { lhs <=> rhs; }
    auto operator<=>(annex< T, Alloc > const& lhs, U const& rhs) -> decltype(*lhs <=> rhs)
    {
        if (lhs.has_value())
        {
            return *lhs <=> rhs;
        }
 
        return std::strong_ordering::less;
    }

    template < typename T, typename Alloc, typename U >
        requires(!requires { typename U::value_type; typename U::allocator_type; } || !std::is_same_v< U, annex< typename U::value_type, typename U::allocator_type > >) && requires(U const& lhs, T const& rhs) { lhs <=> rhs; }
    auto operator<=>(U const& lhs, annex< T, Alloc > const& rhs) -> decltype(lhs <=> *rhs)
    {
        if (rhs.has_value())
        {
            return lhs <=> *rhs;
        }
 
        return std::strong_ordering::greater;
    }


    template < typename T >
    annex< std::decay_t< T > > make_annex(T&& value)
    {
        return annex< std::decay_t< T > >(std::forward< T >(value));
    }

    template < typename T, typename... Args >
    annex< T > make_annex(Args&&... args)
    {
        return annex< T >(std::in_place, std::forward< Args >(args)...);
    }

    template < typename T, typename U, typename... Args >
    annex< T > make_annex(std::initializer_list< U > init, Args&&... args)
    {
        return annex< T >(std::in_place, init, std::forward< Args >(args)...);
    }
} // namespace rpnx
 
#endif // RPNXDATASTRUCTURES_ANNEX_HPP