BasicStringBinder.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "Core.hpp"
#include "UnicodeConverter.hpp"
 
#include <cassert>
#include <cstddef>
#include <cstring>
#include <memory>
#include <optional>
#include <ranges>
#include <utility>
 
namespace Lightweight
{
 
/// @brief Magic number, which is used to determine the optimal maximum size of a column.
///
/// Columns may be larger than this value, but this is the optimal maximum size for performance,
/// and usually also means that values are stored in the same row as the rest of the data, or not.
constexpr inline std::size_t SqlOptimalMaxColumnSize = 4000;
 
namespace detail
{
    /// Helper function to get raw column data of an array-like type.
    ///
    /// @param stmt The SQL statement handle.
    /// @param column The column number to retrieve data from.
    /// @param result The array-like type to store the data in.
    /// @param indicator The indicator to store the length of the data.
    ///
    /// @return SQLRETURN indicating the result of the operation.
    template <auto CType, typename ArrayType>
        requires requires(ArrayType& arr) {
            { arr.data() } -> std::convertible_to<typename ArrayType::value_type*>;
            { arr.size() } -> std::convertible_to<std::size_t>;
            { arr.resize(std::declval<std::size_t>()) };
        }
    SQLRETURN GetRawColumnArrayData(SQLHSTMT stmt, SQLUSMALLINT column, ArrayType* result, SQLLEN* indicator) noexcept
    {
        using CharType = ArrayType::value_type;
 
        // Character C types NUL-terminate every SQLGetData transfer, consuming the last buffer
        // slot; SQL_C_BINARY transfers raw bytes WITHOUT a terminator, so every buffer slot holds
        // data. Getting this wrong for binary loses the byte at each continuation boundary.
        constexpr size_t TrailingNulTerminators = CType == SQL_C_BINARY ? 0 : 1;
 
        *indicator = 0;
 
        // Resize the string to the size of the data
        // Get the data (take care of SQL_NULL_DATA and SQL_NO_TOTAL)
        auto sqlResult = SQLGetData(stmt,
                                    column,
                                    CType,
                                    static_cast<SQLPOINTER>(result->data()),
                                    static_cast<SQLLEN>(result->size() * sizeof(CharType)),
                                    indicator);
 
        if (sqlResult == SQL_SUCCESS || sqlResult == SQL_NO_DATA)
        {
            // Data has been read successfully on first call to SQLGetData, or there is no data to read.
            if (*indicator == SQL_NULL_DATA)
                result->clear();
            else
                result->resize(static_cast<size_t>(*indicator) / sizeof(CharType));
            return sqlResult;
        }
 
        if (sqlResult == SQL_SUCCESS_WITH_INFO && *indicator != SQL_NO_TOTAL
            && (static_cast<size_t>(*indicator) / sizeof(CharType)) + TrailingNulTerminators > result->size())
        {
            // Truncation with a known total. Note the TrailingNulTerminators term: a CHARACTER value whose
            // length exactly equals the buffer still truncates (the driver spends the last slot
            // on the NUL terminator), so the continuation must run for indicator == buffer size.
            // We have a truncation and the server knows how much data is left.
            auto const totalCharCount = static_cast<size_t>(*indicator) / sizeof(CharType);
            auto const charsWritten = result->size() - TrailingNulTerminators;
            result->resize(totalCharCount + TrailingNulTerminators);
            auto* bufferCont = result->data() + charsWritten;
            auto const bufferCharsAvailable = (totalCharCount + TrailingNulTerminators) - charsWritten;
            sqlResult = SQLGetData(
                stmt, column, CType, bufferCont, static_cast<SQLLEN>(bufferCharsAvailable * sizeof(CharType)), indicator);
            if (SQL_SUCCEEDED(sqlResult))
                result->resize(charsWritten + (static_cast<size_t>(*indicator) / sizeof(CharType)));
            return sqlResult;
        }
 
        size_t writeIndex = 0;
        while (sqlResult == SQL_SUCCESS_WITH_INFO && *indicator == SQL_NO_TOTAL)
        {
            // We have a truncation and the server does not know how much data is left.
            writeIndex += result->size() - TrailingNulTerminators;
            result->resize(result->size() * 2);
            auto* const bufferStart = result->data() + writeIndex;
            size_t const bufferCharsAvailable = result->size() - writeIndex;
            sqlResult = SQLGetData(
                stmt, column, CType, bufferStart, static_cast<SQLLEN>(bufferCharsAvailable * sizeof(CharType)), indicator);
        }
        // The unknown-total loop exits with the final transfer's char count in the indicator; trim
        // the over-allocated buffer to the bytes actually written.
        if (writeIndex > 0 && SQL_SUCCEEDED(sqlResult) && *indicator != SQL_NULL_DATA && *indicator != SQL_NO_TOTAL)
            result->resize(writeIndex + (static_cast<size_t>(*indicator) / sizeof(CharType)));
        return sqlResult;
    }
 
    template <typename Utf16StringType>
    SQLRETURN GetColumnUtf16(SQLHSTMT stmt,
                             SQLUSMALLINT column,
                             Utf16StringType* result,
                             SQLLEN* indicator,
                             SqlDataBinderCallback const& /*cb*/) noexcept
    {
        if constexpr (requires { Utf16StringType::Capacity; })
            result->resize(Utf16StringType::Capacity);
        else if (result->size() == 0)
            result->resize(255);
 
        return GetRawColumnArrayData<SQL_C_WCHAR>(stmt, column, result, indicator);
    }
 
    template <typename StringType>
    SQLRETURN BindOutputColumnNonUtf16Unicode(
        SQLHSTMT stmt, SQLUSMALLINT column, StringType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        using CharType = StringType::value_type;
 
        auto u16String = std::make_shared<std::u16string>();
        if (!result->empty())
            u16String->resize(result->size());
        else
            u16String->resize(255);
 
        cb.PlanPostProcessOutputColumn([stmt, column, result, indicator, u16String = u16String]() {
            if (*indicator == SQL_NULL_DATA)
                u16String->clear();
            else if (*indicator == SQL_NO_TOTAL)
                ; // We don't know the size of the data
            else if (std::cmp_less_equal(*indicator, u16String->size() * sizeof(char16_t)))
                u16String->resize(static_cast<size_t>(*indicator) / sizeof(char16_t));
            else
            {
                auto const totalCharsRequired = static_cast<size_t>(*indicator) / sizeof(char16_t);
                *indicator += sizeof(char16_t); // Add space to hold the null terminator
                u16String->resize(totalCharsRequired);
                auto const sqlResult = SQLGetData(stmt, column, SQL_C_WCHAR, u16String->data(), *indicator, indicator);
                (void) sqlResult;
                assert(SQL_SUCCEEDED(sqlResult));
                assert(std::cmp_equal(*indicator, totalCharsRequired * sizeof(char16_t)));
            }
 
            if constexpr (sizeof(typename StringType::value_type) == 1)
                *result = ToUtf8(*u16String);
            else if constexpr (sizeof(typename StringType::value_type) == 4)
            {
                // *result = ToUtf32(*u16String);
                auto const u32String = ToUtf32(*u16String);
                *result = StringType {
                    (CharType const*) u32String.data(),
                    (CharType const*) u32String.data() + u32String.size(),
                };
            }
 
            // The UTF-16 binder applies StringTraits::PostProcessOutputColumn (if present) so that
            // FIXED_SIZE_RIGHT_TRIMMED strings strip the trailing CHAR(N)/NCHAR(N) padding the server
            // returned. The UTF-32 / UTF-8 path constructs *result above, which preserves the padding,
            // so we have to invoke the same post-process here. The synthetic indicator is the
            // result's own byte count: PostProcessOutputColumn divides by sizeof(CharType) to get
            // the char count, and TrimRight then walks back over trailing whitespace/null.
            using StringTraits = SqlBasicStringOperations<StringType>;
            if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
            {
                if (*indicator != SQL_NULL_DATA && *indicator != SQL_NO_TOTAL)
                {
                    auto const syntheticIndicator = static_cast<SQLLEN>(StringTraits::Size(result) * sizeof(CharType));
                    StringTraits::PostProcessOutputColumn(result, syntheticIndicator);
                }
            }
        });
 
        return SQLBindCol(stmt,
                          column,
                          SQL_C_WCHAR,
                          static_cast<SQLPOINTER>(u16String->data()),
                          static_cast<SQLLEN>(u16String->size() * sizeof(char16_t)),
                          indicator);
    }
 
} // namespace detail
 
// SqlDataBinder<> specialization for ANSI character strings
template <typename AnsiStringType>
    requires SqlBasicStringBinderConcept<AnsiStringType, char>
struct SqlDataBinder<AnsiStringType>
{
    using ValueType = AnsiStringType;
    using CharType = char;
    using StringTraits = SqlBasicStringOperations<AnsiStringType>;
 
    static constexpr auto ColumnType = StringTraits::ColumnType;
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN InputParameter(SQLHSTMT stmt,
                                                             SQLUSMALLINT column,
                                                             AnsiStringType const& value,
                                                             SqlDataBinderCallback& cb) noexcept
    {
        // PostgreSQL: route narrow strings through UTF-16 + SQL_C_WCHAR. Even with the
        // DBC handle in Unicode-app mode (SQLDriverConnectW), psqlODBC on Windows still
        // interprets SQL_C_CHAR data as the system codepage (cp1252), not UTF-8 — so a
        // 200-byte UTF-8 payload representing 100 supplementary-plane characters gets
        // re-encoded into 400 bytes and trips VARCHAR(100)'s character-count check.
        // Going via SQL_C_WCHAR makes the driver itself do the encoding conversion to
        // the server's encoding (UTF-8) using proper Unicode rules. We treat the
        // incoming `std::string` as UTF-8 by convention — that is what every other
        // call path in the library produces (file readers, query formatters, etc.).
        if (cb.ServerType() == SqlServerType::POSTGRESQL)
        {
            auto u16String = std::make_shared<std::u16string>(ToUtf16(std::u8string_view {
                reinterpret_cast<char8_t const*>(StringTraits::Data(&value)), StringTraits::Size(&value) }));
            cb.PlanPostExecuteCallback([u16String = u16String]() {}); // keep buffer alive
            auto const charCount = u16String->size();
            auto const byteCount = charCount * sizeof(char16_t);
            auto const sqlType =
                static_cast<SQLSMALLINT>(charCount > SqlOptimalMaxColumnSize ? SQL_WLONGVARCHAR : SQL_WVARCHAR);
 
            SQLLEN* indicator = cb.ProvideInputIndicator();
            *indicator = static_cast<SQLLEN>(byteCount);
 
            return SQLBindParameter(stmt,
                                    column,
                                    SQL_PARAM_INPUT,
                                    SQL_C_WCHAR,
                                    sqlType,
                                    charCount,
                                    0,
                                    (SQLPOINTER) u16String->data(),
                                    static_cast<SQLLEN>(byteCount),
                                    indicator);
        }
 
        auto const charCount = StringTraits::Size(&value);
        auto const sqlType = static_cast<SQLSMALLINT>(charCount > SqlOptimalMaxColumnSize ? SQL_LONGVARCHAR : SQL_VARCHAR);
 
        SQLLEN* indicator = cb.ProvideInputIndicator();
        *indicator = static_cast<SQLLEN>(charCount);
 
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                SQL_C_CHAR,
                                sqlType,
                                charCount,
                                0,
                                (SQLPOINTER) StringTraits::Data(&value),
                                0,
                                indicator);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN BatchInputParameter(SQLHSTMT stmt,
                                                                  SQLUSMALLINT column,
                                                                  AnsiStringType const* values,
                                                                  size_t rowCount,
                                                                  SqlDataBinderCallback& cb) noexcept
    {
        size_t maxLen = 0;
        SQLLEN* indicators = cb.ProvideInputIndicators(rowCount);
        for (size_t i = 0; i < rowCount; ++i)
        {
            auto const len = StringTraits::Size(&values[i]);
            indicators[i] = static_cast<SQLLEN>(len);
            if (len > maxLen)
                maxLen = len;
        }
 
        auto const sqlType = static_cast<SQLSMALLINT>(maxLen > SqlOptimalMaxColumnSize ? SQL_LONGVARCHAR : SQL_VARCHAR);
 
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                SQL_C_CHAR,
                                sqlType,
                                maxLen,
                                0,
                                (SQLPOINTER) values,
                                sizeof(AnsiStringType),
                                indicators);
    }
 
    /// Binds an inline fixed-capacity string column of a native row-wise batch zero-copy.
    ///
    /// Only available for fixed-capacity string types (those exposing @c ::Capacity, e.g.
    /// @c SqlFixedString / @c SqlAnsiString), whose character buffer is stored inline in the object —
    /// so each row's characters are addressed at @c Data(elem0) + i*rowStride and bound directly,
    /// while per-row lengths are supplied through a temporary row-strided indicator buffer. Heap-backed
    /// strings (e.g. @c std::string) do not satisfy the constraint and use the soft batch path.
    ///
    /// @note Like the column-major batch binder, this binds @c SQL_C_CHAR without the PostgreSQL
    /// UTF-16 round-trip, so it is correct for ASCII/single-byte content (matching existing batch
    /// semantics); non-ASCII payloads on PostgreSQL should use the per-row path.
    /// @note PRE (guaranteed by the caller): row-wise binding with @c SQL_ATTR_PARAM_BIND_TYPE ==
    /// @p rowStride and @c rowStride % alignof(SQLLEN) == 0.
    static SQLRETURN BatchRowWiseInputParameter(SQLHSTMT stmt,
                                                SQLUSMALLINT column,
                                                AnsiStringType const* elem0,
                                                std::size_t rowStride,
                                                std::size_t rowCount,
                                                SqlDataBinderCallback& cb) noexcept
        requires requires { AnsiStringType::Capacity; }
    {
        auto const* sourceBytes = reinterpret_cast<std::byte const*>(elem0);
        auto* const indicatorBytes = cb.ProvideBatchStagingBuffer(((rowCount - 1) * rowStride) + sizeof(SQLLEN));
        for (auto const i: std::views::iota(std::size_t { 0 }, rowCount))
        {
            auto const& str = *reinterpret_cast<AnsiStringType const*>(sourceBytes + (i * rowStride));
            *reinterpret_cast<SQLLEN*>(indicatorBytes + (i * rowStride)) = static_cast<SQLLEN>(StringTraits::Size(&str));
        }
 
        return BatchRowWiseBindInline(stmt, column, elem0, reinterpret_cast<SQLLEN*>(indicatorBytes));
    }
 
    /// Issues the row-wise @c SQLBindParameter for an inline fixed-capacity string array.
    ///
    /// @p elem0 points at row 0's string; the driver strides its character buffer by the statement's
    /// @c SQL_ATTR_PARAM_BIND_TYPE. @p indicators is a caller-prepared row-strided buffer whose per-row
    /// slot already holds the string length, or @c SQL_NULL_DATA for a NULL row. Shared by the
    /// non-optional row-wise binder and the @c std::optional row-wise binder so the bind incantation
    /// (and its @c Capacity / buffer-length arithmetic) lives in exactly one place.
    static SQLRETURN BatchRowWiseBindInline(SQLHSTMT stmt,
                                            SQLUSMALLINT column,
                                            AnsiStringType const* elem0,
                                            SQLLEN* indicators) noexcept
        requires requires { AnsiStringType::Capacity; }
    {
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                SQL_C_CHAR,
                                SQL_VARCHAR,
                                AnsiStringType::Capacity,
                                0,
                                (SQLPOINTER) StringTraits::Data(elem0),
                                static_cast<SQLLEN>(AnsiStringType::Capacity) + 1,
                                indicators);
    }
 
    /// Binds an array of @c std::optional<fixed-capacity-string> in a native row-wise batch zero-copy.
    ///
    /// Mirrors @ref BatchRowWiseInputParameter but is NULL-aware: each row's indicator slot holds the
    /// contained string's length when the optional is engaged, or @c SQL_NULL_DATA when disengaged. The
    /// bind then targets row 0's contained character buffer and the driver strides by @p rowStride. Only
    /// the address of the contained string is taken — disengaged storage is never read (its indicator is
    /// @c SQL_NULL_DATA, so the driver ignores those bytes).
    ///
    /// This is the delegation target for @c SqlDataBinder<std::optional<T>>::BatchRowWiseInputParameter
    /// when @p T is a length-bearing inline type (i.e. a fixed-capacity string).
    ///
    /// @note PRE (guaranteed by the caller): row-wise binding with @c SQL_ATTR_PARAM_BIND_TYPE ==
    /// @p rowStride and @c rowStride % alignof(SQLLEN) == 0.
    static SQLRETURN BatchRowWiseInputParameterOptional(SQLHSTMT stmt,
                                                        SQLUSMALLINT column,
                                                        std::optional<AnsiStringType> const* elem0,
                                                        std::size_t rowStride,
                                                        std::size_t rowCount,
                                                        SqlDataBinderCallback& cb) noexcept
        requires requires { AnsiStringType::Capacity; }
    {
        using OptionalType = std::optional<AnsiStringType>;
 
        // Offset of the contained string within the optional (see detail::OptionalValueOffset).
        auto const valueOffset = detail::OptionalValueOffset<AnsiStringType>();
 
        auto const* sourceBytes = reinterpret_cast<std::byte const*>(elem0);
        auto* const indicatorBytes = cb.ProvideBatchStagingBuffer(((rowCount - 1) * rowStride) + sizeof(SQLLEN));
        for (auto const i: std::views::iota(std::size_t { 0 }, rowCount))
        {
            auto const& optional = *reinterpret_cast<OptionalType const*>(sourceBytes + (i * rowStride));
            *reinterpret_cast<SQLLEN*>(indicatorBytes + (i * rowStride)) =
                optional.has_value() ? static_cast<SQLLEN>(StringTraits::Size(std::addressof(*optional)))
                                     : SQLLEN { SQL_NULL_DATA };
        }
 
        // Bind at row 0's contained string buffer (address only; disengaged storage is never read).
        auto const* containedRow0 = reinterpret_cast<AnsiStringType const*>(sourceBytes + valueOffset);
        return BatchRowWiseBindInline(stmt, column, containedRow0, reinterpret_cast<SQLLEN*>(indicatorBytes));
    }
 
    static LIGHTWEIGHT_FORCE_INLINE SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, AnsiStringType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        // PostgreSQL: read narrow strings back through UTF-16 + SQL_C_WCHAR, mirroring InputParameter.
        // psqlODBC on Windows transcodes SQL_C_CHAR data to the system codepage (cp1252), which mangles
        // the UTF-8 bytes the write path stored (café -> caf? ?). Going via SQL_C_WCHAR and converting
        // UTF-16 -> UTF-8 here keeps the narrow round-trip byte-exact under the library's UTF-8 convention.
        // (Self-contained rather than reusing BindOutputColumnNonUtf16Unicode, which assumes a
        // std::basic_string result and so does not cover SqlText / fixed-capacity narrow strings.)
        if (cb.ServerType() == SqlServerType::POSTGRESQL)
        {
            auto u16String = std::make_shared<std::u16string>();
            u16String->resize(StringTraits::Size(result) != 0 ? StringTraits::Size(result) : 255);
 
            cb.PlanPostProcessOutputColumn([stmt, column, result, indicator, u16String]() {
                if (*indicator == SQL_NULL_DATA)
                    u16String->clear();
                else if (*indicator == SQL_NO_TOTAL)
                    ; // Length unknown; keep what the driver already wrote into the bound buffer.
                else if (std::cmp_less_equal(*indicator, u16String->size() * sizeof(char16_t)))
                    u16String->resize(static_cast<size_t>(*indicator) / sizeof(char16_t));
                else
                {
                    // Truncation with a known total: grow and re-fetch the whole value.
                    auto const totalChars = static_cast<size_t>(*indicator) / sizeof(char16_t);
                    u16String->resize(totalChars + 1);
                    auto const rv = SQLGetData(stmt,
                                               column,
                                               SQL_C_WCHAR,
                                               u16String->data(),
                                               static_cast<SQLLEN>((totalChars + 1) * sizeof(char16_t)),
                                               indicator);
                    (void) rv;
                    assert(SQL_SUCCEEDED(rv));
                    u16String->resize(totalChars);
                }
 
                auto const u8String = ToUtf8(*u16String);
                // Resize may clamp to a fixed-capacity string's Capacity; copy only the post-clamp
                // length so a UTF-8 expansion never overruns the inline buffer.
                StringTraits::Resize(result, static_cast<SQLLEN>(u8String.size()));
                std::memcpy(StringTraits::Data(result), u8String.data(), StringTraits::Size(result));
 
                if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
                    if (*indicator != SQL_NULL_DATA && *indicator != SQL_NO_TOTAL)
                    {
                        auto const syntheticIndicator = static_cast<SQLLEN>(StringTraits::Size(result));
                        StringTraits::PostProcessOutputColumn(result, syntheticIndicator);
                    }
            });
 
            return SQLBindCol(stmt,
                              column,
                              SQL_C_WCHAR,
                              static_cast<SQLPOINTER>(u16String->data()),
                              static_cast<SQLLEN>(u16String->size() * sizeof(char16_t)),
                              indicator);
        }
 
        if constexpr (requires { AnsiStringType::Capacity; })
            StringTraits::Resize(result, AnsiStringType::Capacity);
        else if (StringTraits::Size(result) == 0)
            StringTraits::Resize(result, 255);
 
        if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
            cb.PlanPostProcessOutputColumn(
                [indicator, result]() { StringTraits::PostProcessOutputColumn(result, *indicator); });
        else
            cb.PlanPostProcessOutputColumn(
                [stmt, column, indicator, result]() { PostProcessOutputColumn(stmt, column, result, indicator); });
 
        // Per ODBC spec, BufferLength for SQL_C_CHAR must include space for the
        // null terminator. SqlFixedString<N> backs its data with _data[N+1] for
        // exactly this reason; pass Capacity+1 to let the driver write a full
        // N-char value plus null. Dynamic strings keep the current behaviour.
        SQLLEN const bufferLength = [&]() -> SQLLEN {
            if constexpr (requires { AnsiStringType::Capacity; })
                return static_cast<SQLLEN>(AnsiStringType::Capacity) + 1;
            else
                return static_cast<SQLLEN>(StringTraits::Size(result));
        }();
 
        return SQLBindCol(stmt, column, SQL_C_CHAR, (SQLPOINTER) StringTraits::Data(result), bufferLength, indicator);
    }
 
    static void PostProcessOutputColumn(SQLHSTMT stmt, SQLUSMALLINT column, AnsiStringType* result, SQLLEN* indicator)
    {
        // Now resize the string to the actual length of the data
        // NB: If the indicator is greater than the buffer size, we have a truncation.
        if (*indicator == SQL_NO_TOTAL)
        {
            // We have a truncation and the server does not know how much data is left.
            StringTraits::Resize(result, static_cast<SQLLEN>(StringTraits::Size(result)) - 1);
        }
        else if (*indicator == SQL_NULL_DATA)
        {
            // We have a NULL value
            StringTraits::Resize(result, 0);
        }
        else if (*indicator <= static_cast<SQLLEN>(StringTraits::Size(result)))
        {
            StringTraits::Resize(result, *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;
            StringTraits::Resize(result, totalCharsRequired + 1);
            auto const sqlResult =
                SQLGetData(stmt, column, SQL_C_CHAR, StringTraits::Data(result), totalCharsRequired + 1, indicator);
            (void) sqlResult;
            assert(SQL_SUCCEEDED(sqlResult));
            assert(*indicator == totalCharsRequired);
            StringTraits::Resize(result, totalCharsRequired);
        }
    }
 
    // NOLINTNEXTLINE(readability-function-cognitive-complexity)
    static SQLRETURN GetColumn(SQLHSTMT stmt,
                               SQLUSMALLINT column,
                               AnsiStringType* result,
                               SQLLEN* indicator,
                               SqlDataBinderCallback const& cb) noexcept
    {
        // PostgreSQL: fetch narrow strings via UTF-16 + SQL_C_WCHAR and convert to UTF-8, symmetric
        // with InputParameter / OutputColumn. A raw SQL_C_CHAR fetch would come back transcoded to
        // the Windows system codepage (cp1252) by psqlODBC, mangling the stored UTF-8 bytes.
        if (cb.ServerType() == SqlServerType::POSTGRESQL)
        {
            auto u16String = std::u16string {};
            auto const sqlResult = detail::GetColumnUtf16(stmt, column, &u16String, indicator, cb);
            if (!SQL_SUCCEEDED(sqlResult))
                return sqlResult;
 
            auto const u8String = ToUtf8(u16String);
            // Resize may clamp to a fixed-capacity string's Capacity, so copy only what fits
            // (StringTraits::Size reflects the post-clamp length) to avoid overrunning the buffer.
            StringTraits::Resize(result, static_cast<SQLLEN>(u8String.size()));
            std::memcpy(StringTraits::Data(result), u8String.data(), StringTraits::Size(result));
            // Apply the type's post-processing (e.g. FIXED_SIZE_RIGHT_TRIMMED strips the CHAR(N)
            // padding the server returned), matching the non-PostgreSQL GetColumn path. The
            // synthetic indicator is the result's own byte count.
            if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
                if (*indicator != SQL_NULL_DATA && *indicator != SQL_NO_TOTAL)
                    StringTraits::PostProcessOutputColumn(result, static_cast<SQLLEN>(StringTraits::Size(result)));
            return sqlResult;
        }
 
        if constexpr (requires { AnsiStringType::Capacity; })
        {
            StringTraits::Resize(result, AnsiStringType::Capacity);
            // BufferLength for SQL_C_CHAR must include space for the null terminator;
            // _data is sized N+1 to accommodate it.
            SQLRETURN const rv =
                SQLGetData(stmt, column, SQL_C_CHAR, StringTraits::Data(result), AnsiStringType::Capacity + 1, indicator);
            if (rv == SQL_SUCCESS || rv == SQL_NO_DATA)
            {
                if (*indicator == SQL_NULL_DATA)
                    StringTraits::Resize(result, 0);
                else if (*indicator != SQL_NO_TOTAL)
                    StringTraits::Resize(
                        result, static_cast<SQLLEN>((std::min) (AnsiStringType::Capacity, static_cast<size_t>(*indicator))));
            }
            if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
                StringTraits::PostProcessOutputColumn(result, *indicator);
            return rv;
        }
        else
        {
            StringTraits::Reserve(result, 15);
            size_t writeIndex = 0;
            *indicator = 0;
            while (true)
            {
                auto* const bufferStart = StringTraits::Data(result) + writeIndex;
                size_t const bufferSize = StringTraits::Size(result) - writeIndex;
                SQLRETURN const rv =
                    SQLGetData(stmt, column, SQL_C_CHAR, bufferStart, static_cast<SQLLEN>(bufferSize), indicator);
                switch (rv)
                {
                    case SQL_SUCCESS:
                    case SQL_NO_DATA:
                        // last successive call
                        if (*indicator != SQL_NULL_DATA)
                        {
                            StringTraits::Resize(result, static_cast<SQLLEN>(writeIndex) + *indicator);
                            *indicator = static_cast<SQLLEN>(StringTraits::Size(result));
                        }
                        return SQL_SUCCESS;
                    case SQL_SUCCESS_WITH_INFO: {
                        // more data pending
                        if (*indicator == SQL_NO_TOTAL)
                        {
                            // We have a truncation and the server does not know how much data is left.
                            writeIndex += bufferSize - 1;
                            StringTraits::Resize(result, static_cast<SQLLEN>((2 * writeIndex) + 1));
                        }
                        else if (std::cmp_greater_equal(*indicator, bufferSize))
                        {
                            // We have a truncation and the server knows how much data is left.
                            writeIndex += bufferSize - 1;
                            StringTraits::Resize(result, static_cast<SQLLEN>(writeIndex) + *indicator);
                        }
                        else
                        {
                            // We have no truncation and the server knows how much data is left.
                            StringTraits::Resize(result, static_cast<SQLLEN>(writeIndex) + *indicator - 1);
                            return SQL_SUCCESS;
                        }
                        break;
                    }
                    default:
                        if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
                            StringTraits::PostProcessOutputColumn(result, *indicator);
                        return rv;
                }
            }
        }
    }
 
    static LIGHTWEIGHT_FORCE_INLINE std::string_view Inspect(AnsiStringType const& value) noexcept
    {
        return { StringTraits::Data(&value), StringTraits::Size(&value) };
    }
};
 
// SqlDataBinder<> specialization for UTF-16 strings
template <typename Utf16StringType>
    requires(SqlBasicStringBinderConcept<Utf16StringType, char16_t>
             || (SqlBasicStringBinderConcept<Utf16StringType, unsigned short>)
             || (SqlBasicStringBinderConcept<Utf16StringType, wchar_t> && sizeof(wchar_t) == 2))
struct SqlDataBinder<Utf16StringType>
{
    using ValueType = Utf16StringType;
    using CharType = std::remove_cvref_t<decltype(std::declval<Utf16StringType>()[0])>;
    using StringTraits = SqlBasicStringOperations<Utf16StringType>;
 
    static constexpr auto ColumnType = StringTraits::ColumnType;
 
    static constexpr auto CType = SQL_C_WCHAR;
 
    static SQLRETURN InputParameter(SQLHSTMT stmt,
                                    SQLUSMALLINT column,
                                    Utf16StringType const& value,
                                    SqlDataBinderCallback& cb) noexcept
    {
        // Bind UTF-16 input directly via SQL_C_WCHAR for every backend; the driver
        // converts to the server's encoding, including correct handling of UTF-16
        // surrogate pairs for supplementary-plane code points (emoji, CJK extension B+).
        using CharType = StringTraits::CharType;
        auto const* data = StringTraits::Data(&value);
        auto const sizeInBytes = StringTraits::Size(&value) * sizeof(CharType);
        auto const charCount = StringTraits::Size(&value);
        auto const sqlType = static_cast<SQLSMALLINT>(charCount > SqlOptimalMaxColumnSize ? SQL_WLONGVARCHAR : SQL_WVARCHAR);
 
        SQLLEN* indicator = cb.ProvideInputIndicator();
        *indicator = static_cast<SQLLEN>(sizeInBytes);
 
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                CType,
                                sqlType,
                                charCount,
                                0,
                                (SQLPOINTER) data,
                                static_cast<SQLLEN>(sizeInBytes),
                                indicator);
    }
 
    static SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, Utf16StringType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        if constexpr (requires { Utf16StringType::Capacity; })
            StringTraits::Resize(result, Utf16StringType::Capacity);
        else if (StringTraits::Size(result) == 0)
            StringTraits::Resize(result, 255);
 
        if constexpr (requires { StringTraits::PostProcessOutputColumn(result, *indicator); })
        {
            cb.PlanPostProcessOutputColumn(
                [indicator, result]() { StringTraits::PostProcessOutputColumn(result, *indicator); });
        }
        else
        {
            cb.PlanPostProcessOutputColumn([stmt, column, indicator, result]() {
                // Now resize the string to the actual length of the data
                // NB: If the indicator is greater than the buffer size, we have a truncation.
                if (*indicator == SQL_NULL_DATA)
                    StringTraits::Resize(result, 0);
                else if (*indicator == SQL_NO_TOTAL)
                    ; // We don't know the size of the data
                else if (*indicator <= static_cast<SQLLEN>(result->size() * sizeof(char16_t)))
                    result->resize(static_cast<size_t>(*indicator) / sizeof(char16_t));
                else
                {
                    auto const totalCharsRequired = static_cast<size_t>(*indicator) / sizeof(char16_t);
                    *indicator += sizeof(char16_t); // Add space to hold the null terminator
                    result->resize(totalCharsRequired);
                    auto const sqlResult = SQLGetData(stmt, column, SQL_C_WCHAR, result->data(), *indicator, indicator);
                    (void) sqlResult;
                    assert(SQL_SUCCEEDED(sqlResult));
                    assert(std::cmp_equal(*indicator, totalCharsRequired * sizeof(char16_t)));
                }
            });
        }
        return SQLBindCol(stmt,
                          column,
                          CType,
                          (SQLPOINTER) StringTraits::Data(result),
                          (SQLLEN) ((StringTraits::Size(result) + 1) * sizeof(CharType)),
                          indicator);
    }
 
    static SQLRETURN GetColumn(SQLHSTMT stmt,
                               SQLUSMALLINT column,
                               Utf16StringType* result,
                               SQLLEN* indicator,
                               SqlDataBinderCallback const& cb) noexcept
    {
        return detail::GetColumnUtf16(stmt, column, result, indicator, cb);
    }
 
    static LIGHTWEIGHT_FORCE_INLINE std::string Inspect(Utf16StringType const& value) noexcept
    {
        auto u8String = ToUtf8(detail::SqlViewHelper<Utf16StringType>::View(value));
        return std::string(reinterpret_cast<char const*>(u8String.data()), u8String.size());
    }
};
 
// SqlDataBinder<> specialization for UTF-32 strings
template <typename Utf32StringType>
    requires(SqlBasicStringBinderConcept<Utf32StringType, char32_t>
             || (SqlBasicStringBinderConcept<Utf32StringType, uint32_t>)
             || (SqlBasicStringBinderConcept<Utf32StringType, wchar_t> && sizeof(wchar_t) == 4))
struct SqlDataBinder<Utf32StringType>
{
    using ValueType = Utf32StringType;
    using CharType = Utf32StringType::value_type;
    using StringTraits = SqlBasicStringOperations<Utf32StringType>;
 
    static constexpr auto ColumnType = StringTraits::ColumnType;
 
    static SQLRETURN InputParameter(SQLHSTMT stmt,
                                    SQLUSMALLINT column,
                                    Utf32StringType const& value,
                                    SqlDataBinderCallback& cb) noexcept
    {
        // Always go via UTF-16 + SQL_C_WCHAR; the driver handles encoding conversion
        // for the target server.
        auto u16String = std::make_shared<std::u16string>(ToUtf16(detail::SqlViewHelper<Utf32StringType>::View(value)));
        cb.PlanPostExecuteCallback([u16String = u16String]() {}); // Keep the string alive
        auto const* data = u16String->data();
        auto const charCount = u16String->size();
        auto const sizeInBytes = u16String->size() * sizeof(char16_t);
        auto const CType = SQLSMALLINT { SQL_C_WCHAR };
        auto const sqlType = static_cast<SQLSMALLINT>(charCount > SqlOptimalMaxColumnSize ? SQL_WLONGVARCHAR : SQL_WVARCHAR);
 
        SQLLEN* indicator = cb.ProvideInputIndicator();
        *indicator = static_cast<SQLLEN>(sizeInBytes);
 
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                CType,
                                sqlType,
                                charCount,
                                0,
                                (SQLPOINTER) data,
                                static_cast<SQLLEN>(sizeInBytes),
                                indicator);
    }
 
    static SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, Utf32StringType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        return detail::BindOutputColumnNonUtf16Unicode<Utf32StringType>(stmt, column, result, indicator, cb);
    }
 
    static SQLRETURN GetColumn(SQLHSTMT stmt,
                               SQLUSMALLINT column,
                               Utf32StringType* result,
                               SQLLEN* indicator,
                               SqlDataBinderCallback const& cb) noexcept
    {
        auto u16String = std::u16string {};
        auto const sqlResult = detail::GetColumnUtf16(stmt, column, &u16String, indicator, cb);
        if (!SQL_SUCCEEDED(sqlResult))
            return sqlResult;
 
        auto const u32String = ToUtf32(u16String);
        StringTraits::Resize(result, static_cast<SQLLEN>(u32String.size()));
        std::copy_n((CharType const*) u32String.data(), u32String.size(), StringTraits::Data(result));
 
        return sqlResult;
    }
 
    static LIGHTWEIGHT_FORCE_INLINE std::string Inspect(Utf32StringType const& value) noexcept
    {
        auto u8String = ToUtf8(detail::SqlViewHelper<Utf32StringType>::View(value));
        return std::string(reinterpret_cast<char const*>(u8String.data()), u8String.size());
    }
};
 
// SqlDataBinder<> specialization for UTF-8 strings
template <typename Utf8StringType>
    requires SqlBasicStringBinderConcept<Utf8StringType, char8_t>
struct SqlDataBinder<Utf8StringType>
{
    using ValueType = Utf8StringType;
    using CharType = char8_t;
    using StringTraits = SqlBasicStringOperations<Utf8StringType>;
 
    static constexpr auto ColumnType = StringTraits::ColumnType;
 
    static SQLRETURN InputParameter(SQLHSTMT stmt,
                                    SQLUSMALLINT column,
                                    Utf8StringType const& value,
                                    SqlDataBinderCallback& cb) noexcept
    {
        // Always go via UTF-16 + SQL_C_WCHAR; the driver handles encoding conversion
        // for the target server.
        auto u16String = std::make_shared<std::u16string>(ToUtf16(detail::SqlViewHelper<Utf8StringType>::View(value)));
        cb.PlanPostExecuteCallback([u16String = u16String]() {}); // Keep the string alive
 
        auto const CType = SQL_C_WCHAR;
        auto const charCount = u16String->size();
        auto const byteCount = u16String->size() * sizeof(char16_t);
        auto const sqlType = static_cast<SQLSMALLINT>(charCount > SqlOptimalMaxColumnSize ? SQL_WLONGVARCHAR : SQL_WVARCHAR);
 
        SQLLEN* indicator = cb.ProvideInputIndicator();
        *indicator = static_cast<SQLLEN>(byteCount);
 
        return SQLBindParameter(stmt,
                                column,
                                SQL_PARAM_INPUT,
                                CType,
                                sqlType,
                                charCount,
                                0,
                                (SQLPOINTER) u16String->data(),
                                static_cast<SQLLEN>(byteCount),
                                indicator);
    }
 
    static SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, Utf8StringType* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept
    {
        return detail::BindOutputColumnNonUtf16Unicode<Utf8StringType>(stmt, column, result, indicator, cb);
    }
 
    static SQLRETURN GetColumn(SQLHSTMT stmt,
                               SQLUSMALLINT column,
                               Utf8StringType* result,
                               SQLLEN* indicator,
                               SqlDataBinderCallback const& cb) noexcept
    {
        auto u16String = std::u16string {};
        u16String.resize(result->size());
        auto const sqlReturn = detail::GetColumnUtf16(stmt, column, &u16String, indicator, cb);
        if (SQL_SUCCEEDED(sqlReturn))
            *result = ToUtf8(u16String);
        return sqlReturn;
    }
 
    static LIGHTWEIGHT_FORCE_INLINE std::string Inspect(Utf8StringType const& value) noexcept
    {
        // Pass data as-is
        return std::string(reinterpret_cast<char const*>(value.data()), value.size());
    }
};
 
} // namespace Lightweight