SqlDynamicBinary.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../SqlColumnTypeDefinitions.hpp"
#include "BasicStringBinder.hpp"
#include "Core.hpp"
 
#include <cassert>
#include <format>
#include <span>
#include <string>
 
namespace Lightweight
{
 
/// SQL dynamic-capacity string that mimicks standard library string.
///
/// The underlying memory is allocated dynamically and the string can grow up to the maximum size of a SQL column.
///
/// @ingroup DataTypes
template <std::size_t N>
class SqlDynamicBinary final
{
    using BaseType = std::vector<uint8_t>;
 
  public:
    /// The element type of the binary data.
    using value_type = uint8_t;
 
    /// Read-only view over the stored bytes.
    ///
    /// MSVC's STL is pinned to `std::basic_string_view` here: its `std::span` reverse iterator drags
    /// the legacy `std::iter_move` into overload resolution, which is then ambiguous with
    /// `std::ranges::enumerate_view`'s own `iter_move` in any translation unit that uses both.
    /// Other standard libraries keep `std::span` because `std::basic_string_view<uint8_t>` is
    /// ill-formed there (no `std::char_traits<unsigned char>`).
#if defined(_MSVC_STL_VERSION)
    using ByteView = std::basic_string_view<value_type>;
#else
    using ByteView = std::span<value_type const>;
#endif
 
    /// The SQL column type definition for this binary type.
    static constexpr auto ColumnType = SqlColumnTypeDefinitions::VarBinary { N };
 
    /// The maximum size of the underlying data storage.
    static constexpr std::size_t DynamicCapacity = N;
 
    /// Default constructor, creates an empty object.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary() noexcept = default;
 
    /// Defaulted copy constructor.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary(SqlDynamicBinary const&) noexcept = default;
 
    /// Defaulted copy assignment operator.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary& operator=(SqlDynamicBinary const&) noexcept = default;
 
    /// Defaulted move constructor.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary(SqlDynamicBinary&&) noexcept = default;
 
    /// Defaulted move assignment operator.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary& operator=(SqlDynamicBinary&&) noexcept = default;
 
    /// Defaulted destructor.
    LIGHTWEIGHT_FORCE_INLINE constexpr ~SqlDynamicBinary() noexcept = default;
 
    /// Constructs a fixed-size string from a string literal.
    template <std::size_t SourceSize>
    constexpr LIGHTWEIGHT_FORCE_INLINE SqlDynamicBinary(value_type const (&text)[SourceSize]):
        _base { text, text + SourceSize }
    {
        static_assert(SourceSize <= N + 1, "RHS string size must not exceed target string's capacity.");
    }
 
    /// Constructs the object from an initializer list of bytes.
    template <std::size_t SourceSize>
    constexpr LIGHTWEIGHT_FORCE_INLINE SqlDynamicBinary(std::initializer_list<value_type> data):
        _base { data }
    {
        static_assert(SourceSize <= N + 1, "RHS string size must not exceed target string's capacity.");
    }
 
    /// Constructs a fixed-size string from a string pointer and end pointer.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary(value_type const* s, value_type const* e) noexcept:
        _base { s, e }
    {
    }
#if !defined(LIGHTWEIGHT_CXX26_REFLECTION)
    /// Constructs the binary payload from a contiguous view of bytes.
    LIGHTWEIGHT_FORCE_INLINE constexpr SqlDynamicBinary(ByteView s) noexcept:
        _base { s.data(), s.data() + s.size() }
    {
    }
 
    /// Retrieves a read-only view over the stored bytes.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr ByteView Bytes() const noexcept
    {
        return { _base.data(), _base.size() };
    }
 
    /// @deprecated Use @ref Bytes(). Alias kept for source compatibility; the name is a misnomer since
    /// this type holds raw bytes, not text.
    [[deprecated("use Bytes(); SqlDynamicBinary stores raw bytes, not text")]] [[nodiscard]]
    LIGHTWEIGHT_FORCE_INLINE constexpr ByteView ToStringView() const noexcept
    {
        return Bytes();
    }
#endif
 
    /// Three-way comparison operator. Compares the byte payload only — the private
    /// `_indicator` member is ODBC bookkeeping and must not influence equality.
    constexpr auto operator<=>(SqlDynamicBinary<N> const& other) const noexcept
    {
        return _base <=> other._base;
    }
 
    /// Equality operator derived from the spaceship comparison above.
    constexpr bool operator==(SqlDynamicBinary<N> const& other) const noexcept
    {
        return _base == other._base;
    }
 
    /// Retrieves the size of the string.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr std::size_t size() const noexcept
    {
        return _base.size();
    }
 
    /// Resizes the underlying data storage to the given size.
    void LIGHTWEIGHT_FORCE_INLINE resize(std::size_t newSize)
    {
        _base.resize(newSize);
    }
 
    /// Tests if the stored data is empty.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr bool empty() const noexcept
    {
        return _base.empty();
    }
 
    /// Retrieves the pointer to the string data.
    ///
    /// The non-const overload lazily grows `_base` so a null `data()` never reaches ODBC — some
    /// drivers reject a null `ParameterValuePtr` even for a zero-length bind. The const overload must
    /// not mutate `_base` (a genuinely const-qualified object's members may live in read-only memory,
    /// and writing through a `const_cast` pointer to one is undefined behavior per [dcl.type.cv]), so
    /// it returns a static empty-but-non-null sentinel instead when the buffer hasn't been
    /// materialized yet. Safe because every caller pairs this pointer with `size()` (0 in the
    /// null-buffer case) rather than dereferencing it directly, so the sentinel byte is never read.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr value_type const* data() const noexcept
    {
        if (_base.data() != nullptr)
            return _base.data();
 
        static constexpr value_type emptySentinel = 0;
        return &emptySentinel;
    }
 
    /// Retrieves the pointer to the string data.
    [[nodiscard]] LIGHTWEIGHT_FORCE_INLINE constexpr value_type* data() noexcept
    {
        if (_base.data() == nullptr)
        {
            _base.resize(8);
            _base.clear();
        }
        return _base.data();
    }
 
    /// Clears the storad data.
    LIGHTWEIGHT_FORCE_INLINE void clear() noexcept
    {
        _base.clear();
    }
 
  private:
    BaseType _base;
    mutable SQLLEN _indicator = 0;
 
    friend struct SqlDataBinder<SqlDynamicBinary<N>>;
};
 
namespace detail
{
 
    template <typename>
    struct IsSqlDynamicBinaryImpl: std::false_type
    {
    };
 
    template <size_t T>
    struct IsSqlDynamicBinaryImpl<SqlDynamicBinary<T>>: std::true_type
    {
    };
 
    template <size_t T>
    struct IsSqlDynamicBinaryImpl<std::optional<SqlDynamicBinary<T>>>: std::true_type
    {
    };
 
} // namespace detail
 
template <typename T>
constexpr bool IsSqlDynamicBinary = detail::IsSqlDynamicBinaryImpl<T>::value;
 
} // namespace Lightweight
 
template <std::size_t N>
struct std::formatter<Lightweight::SqlDynamicBinary<N>>: std::formatter<std::string>
{
    auto format(Lightweight::SqlDynamicBinary<N> const& text, format_context& ctx) const
    {
        // SqlDynamicBinary<N> exposes data()/size(), not begin()/end() — it is a raw-byte buffer,
        // not an iterable range. Views it as a std::span instead of range-for'ing over the type
        // directly, keeping the loop itself range-based.
        std::string humanReadableText;
        for (auto const byte: std::span { text.data(), text.size() })
        {
            if (byte >= 0x20 && byte <= 0x7E)
                humanReadableText += static_cast<char>(byte);
            else
                humanReadableText += std::format("\\x{:02X}", byte);
        }
        return std::formatter<std::string>::format(humanReadableText.data(), ctx);
    }
};
 
namespace Lightweight
{
 
template <std::size_t N>
struct SqlDataBinder<SqlDynamicBinary<N>>
{
    using ValueType = SqlDynamicBinary<N>;
 
    static constexpr auto ColumnType = SqlColumnTypeDefinitions::VarBinary { N };
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN InputParameter(SQLHSTMT stmt,
                                                             SQLUSMALLINT column,
                                                             ValueType const& value,
                                                             SqlDataBinderCallback& /*cb*/) noexcept
    {
        value._indicator = static_cast<SQLLEN>(value.size());
 
        auto const sqlType = static_cast<SQLSMALLINT>(value.size() > 8000 ? SQL_LONGVARBINARY : SQL_VARBINARY);
        auto const bufferSize = static_cast<SQLULEN>(value.size());
        auto* const ptr = (SQLPOINTER) value.data();
 
        return SQLBindParameter(
            stmt, column, SQL_PARAM_INPUT, SQL_C_BINARY, sqlType, bufferSize, 0, ptr, 0, &value._indicator);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, ValueType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        if (result->empty())
            result->resize(255);
 
        cb.PlanPostProcessOutputColumn([stmt, column, result, indicator]() {
            if (*indicator == SQL_NULL_DATA)
                // The data is NULL.
                result->clear();
            else if (*indicator == SQL_NO_TOTAL)
                // We have a truncation and the server does not know how much data is left.
                result->resize(result->size() - 1);
            else if (*indicator <= static_cast<SQLLEN>(result->size()))
                result->resize(static_cast<size_t>(*indicator));
            else
            {
                // We have a truncation and the server knows how much data is left.
                // Extend the buffer and fetch the rest via SQLGetData.
 
                auto const totalCharsRequired = *indicator;
                result->resize(static_cast<size_t>(totalCharsRequired + 1));
                auto const sqlResult =
                    SQLGetData(stmt, column, SQL_C_BINARY, (SQLPOINTER) result->data(), totalCharsRequired + 1, indicator);
                (void) sqlResult;
                assert(SQL_SUCCEEDED(sqlResult));
                assert(*indicator == totalCharsRequired);
                result->resize(static_cast<size_t>(totalCharsRequired));
            }
        });
 
        return SQLBindCol(stmt, column, SQL_C_BINARY, (SQLPOINTER) result->data(), 255, indicator);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN GetColumn(SQLHSTMT stmt,
                                                        SQLUSMALLINT column,
                                                        ValueType* result,
                                                        SQLLEN* indicator,
                                                        SqlDataBinderCallback const& /*cb*/) noexcept
    {
        if (result->empty())
            result->resize(255);
 
        return detail::GetRawColumnArrayData<SQL_C_BINARY>(stmt, column, result, indicator);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE std::string Inspect(ValueType const& value)
    {
        return std::format("SqlBinary<{}>(size={})", N, value.size());
    }
};
 
} // namespace Lightweight