ensure.h

/*********************************************************************************************************************************************/
/*  DocWire SDK: Award-winning modern data processing in C++20. SourceForge Community Choice & Microsoft support. AI-driven processing.      */
/*  Supports nearly 100 data formats, including email boxes and OCR. Boost efficiency in text extraction, web data extraction, data mining,  */
/*  document analysis. Offline processing possible for security and confidentiality                                                          */
/*                                                                                                                                           */
/*  Copyright (c) SILVERCODERS Ltd, http://silvercoders.com                                                                                  */
/*  Project homepage: https://github.com/docwire/docwire                                                                                     */
/*                                                                                                                                           */
/*  SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-DocWire-Commercial                                                                  */
/*********************************************************************************************************************************************/
 
#ifndef DOCWIRE_ENSURE_H
#define DOCWIRE_ENSURE_H
 
#include <initializer_list>
#include <cassert>
#include "source_location.h"
#include "throw_if.h"
#include <vector>
 
namespace docwire
{
 
template<typename T>
class [[nodiscard]] ensure
{
public:
    explicit ensure(const T& value, const source_location& loc = source_location::current())
        : m_value(value), m_location(loc)
#ifndef NDEBUG
        , m_comparison_performed(false)
#endif
    {}
 
    ~ensure()
    {
        // In debug builds, assert that a comparison operator was used. This prevents incorrect
        // usage like `ensure(a == b);` from silently passing. The assert macro is automatically
        // compiled out in release builds (when NDEBUG is defined), resulting in zero overhead.
        assert(m_comparison_performed && "docwire::ensure() was called without a comparison operator (e.g., ==, !=, <, etc.). "
                                         "This is a bug in the calling code, not a runtime error.");
    }
 
    template<typename U>
    void operator==(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value == other), m_location, m_value, other);
    }
 
    template<typename U>
    void operator!=(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value != other), m_location, m_value, other);
    }
 
    template<typename U>
    void operator>(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value > other), m_location, m_value, other);
    }
 
    template<typename U>
    void operator>=(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value >= other), m_location, m_value, other);
    }
 
    template<typename U>
    void operator<(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value < other), m_location, m_value, other);
    }
 
    template<typename U>
    void operator<=(const U& other) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(!(m_value <= other), m_location, m_value, other);
    }
 
    template<typename U>
    requires string_like<T> && string_like<U>
    void contains(const U& substring) const
    {
        set_comparison_performed();
        DOCWIRE_THROW_IF_AT_LOCATION(std::string_view(m_value).find(substring) == std::string_view::npos, m_location, m_value, substring);
    }
 
    void is_one_of(std::initializer_list<T> expected_values) const
    {
        set_comparison_performed();
        for (const auto& expected : expected_values)
        {
            if (m_value == expected)
            {
                return; // Match found, success.
            }
        }
        DOCWIRE_THROW_IF_AT_LOCATION(true, m_location, m_value, std::vector<T>(expected_values));
    }
private:
    void set_comparison_performed() const
    {
#ifndef NDEBUG
        m_comparison_performed = true;
#endif
    }
 
    const T& m_value;
    docwire::source_location m_location;
#ifndef NDEBUG
    mutable bool m_comparison_performed;
#endif
};
 
template<typename T>
ensure(const T&, const docwire::source_location&) -> ensure<T>;
 
} // namespace docwire
 
#endif // DOCWIRE_ENSURE_H