Utils.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
// <sql.h> below is not self-contained on Windows: the SDK's <sqltypes.h> resolves a handful of
// symbols (SQLHWND/GUID/etc.) against the Windows prelude. SqlOdbcPrelude.hpp supplies minimal,
// ABI-stable shims for exactly those symbols instead of pulling in the full <Windows.h> aggregate
// — see its header comment for the rationale (#547). Every other header here that reaches an ODBC
// header opens with the same include.
#include "Api.hpp"
#include "Description.hpp"
#include "SqlError.hpp"
#include "SqlOdbcPrelude.hpp"
 
#include <reflection-cpp/reflection.hpp>
 
#include <algorithm>
#include <array>
#include <cerrno>
#include <charconv>
#include <cstddef>
#include <cstdlib>
#include <optional>
#include <ranges>
#include <source_location>
#include <span>
#include <string>
#include <string_view>
#include <system_error>
#include <type_traits>
#include <unordered_map>
#include <utility>
 
// libc++ exposes the locale-aware strtod_l / newlocale family via <xlocale.h>; glibc declares them in
// <stdlib.h>/<locale.h>. We only need them on the fallback path below (no float std::from_chars).
#if !(defined(__cpp_lib_to_chars) && __cpp_lib_to_chars >= 201611L)
    #include <clocale>
    #if defined(__APPLE__)
        #include <xlocale.h>
    #else
        #include <locale.h>
    #endif
#endif
 
#include <sql.h>
 
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
    #include <experimental/meta>
#endif
 
namespace Lightweight
{
 
namespace detail
{
 
    template <typename T, typename... Comps>
    concept OneOf = (std::same_as<T, Comps> || ...);
 
    /// Appends @p bytes to @p text as upper-case hex digits, two per byte.
    /// @param text Receives the digits.
    /// @param bytes The bytes to spell out.
    inline void AppendUpperHex(std::string& text, std::span<std::byte const> bytes)
    {
        constexpr auto Digits = std::string_view { "0123456789ABCDEF" };
        text.reserve(text.size() + (2 * bytes.size()));
        for (auto const byte: bytes)
        {
            auto const value = std::to_integer<unsigned>(byte);
            text += Digits[value >> 4U];
            text += Digits[value & 0x0FU];
        }
    }
 
    template <typename T>
    constexpr auto AlwaysFalse = std::false_type::value;
 
    constexpr auto Finally(auto&& cleanupRoutine) noexcept
    {
        // NOLINTNEXTLINE(cppcoreguidelines-special-member-functions)
        struct Finally
        {
            std::remove_cvref_t<decltype(cleanupRoutine)> cleanup;
            ~Finally()
            {
                cleanup();
            }
        };
        return Finally { std::forward<decltype(cleanupRoutine)>(cleanupRoutine) };
    }
 
    /// Parses a floating-point value from the character range @c [first, last) in a locale-independent way.
    ///
    /// This is the single, shared replacement for @c std::from_chars on floating-point types, which is
    /// unavailable on libc++ before macOS 26. Unlike a bare @c std::strtod it neither depends on the active
    /// @c LC_NUMERIC locale nor silently accepts trailing garbage, so it round-trips the @c '.' decimal point
    /// the library always emits regardless of the host locale.
    ///
    /// @tparam T A floating-point type (@c float, @c double, or @c long double).
    /// @param first Pointer to the first character of the numeric text.
    /// @param last Pointer one past the last character of the numeric text.
    /// @return The parsed value, or @c std::nullopt if the text is not a complete, in-range number.
    template <typename T>
        requires std::is_floating_point_v<T>
    [[nodiscard]] inline std::optional<T> ParseFloat(char const* first, char const* last) noexcept
    {
        if (first == last)
            return std::nullopt;
#if defined(__cpp_lib_to_chars) && __cpp_lib_to_chars >= 201611L
        // std::from_chars is locale-independent, allocation-free, and reports both partial parses (ptr) and
        // range errors (ec) — the preferred path wherever the float overloads exist.
        T value {};
        auto const [ptr, ec] = std::from_chars(first, last, value);
        if (ec != std::errc {} || ptr != last)
            return std::nullopt;
        return value;
#else
        // libc++ fallback: strtod_l with a persistent "C" locale gives locale-independent parsing; from_chars
        // float overloads are unavailable here. Copy into a NUL-terminated buffer (the range need not be) and
        // require the parse to consume all of it (mirrors the from_chars ptr==last check). On-stack for the
        // common short numeric text; only the rare over-long token allocates.
        static ::locale_t const cLocale = ::newlocale(LC_NUMERIC_MASK, "C", static_cast<::locale_t>(nullptr));
        auto const length = static_cast<std::size_t>(last - first);
        std::array<char, 64> stackBuffer {};
        std::string heapBuffer;
        char const* text = nullptr;
        if (length < stackBuffer.size())
        {
            std::ranges::copy(first, last, stackBuffer.begin());
            stackBuffer[length] = '\0';
            text = stackBuffer.data();
        }
        else
        {
            heapBuffer.assign(first, last);
            text = heapBuffer.c_str();
        }
 
        char* parseEnd = nullptr;
        errno = 0;
        T value {};
        if constexpr (std::is_same_v<T, float>)
            value = ::strtof_l(text, &parseEnd, cLocale);
        else if constexpr (std::is_same_v<T, long double>)
            value = ::strtold_l(text, &parseEnd, cLocale);
        else
            value = static_cast<T>(::strtod_l(text, &parseEnd, cLocale));
 
        if (errno == ERANGE || parseEnd != text + length)
            return std::nullopt;
        return value;
#endif
    }
 
    // is_specialization_of<> is inspired by:
    // https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p2098r1.pdf
 
    template <template <typename...> class T, typename U>
    struct is_specialization_of: std::false_type
    {
    };
 
    template <template <typename...> class T, typename... Us>
    struct is_specialization_of<T, T<Us...>>: std::true_type
    {
    };
 
    template <typename T>
    struct MemberClassTypeHelper;
 
    template <typename M, typename T>
    struct MemberClassTypeHelper<M T::*>
    {
        using type = std::remove_cvref_t<T>;
    };
 
    template <typename Record>
    struct RecordTableNameImpl
    {
        static constexpr std::string_view Value = []() {
            if constexpr (requires { Record::TableName; })
                return Record::TableName;
            else
                return []() {
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
                    return std::meta::identifier_of(^^Record);
#else
                    auto const typeName = Reflection::TypeNameOf<Record>;
                    if (auto const i = typeName.rfind(':'); i != std::string_view::npos)
                        return typeName.substr(i + 1);
                    return typeName;
#endif
                }();
        }();
    };
 
    // specialization for the case when we use tuple as
    // a record, then we use the first element of the tuple
    // to get the table name
    template <typename First, typename Second>
    struct RecordTableNameImpl<std::tuple<First, Second>>
    {
        static constexpr std::string_view Value = []() {
            if constexpr (requires { First::TableName; })
                return First::TableName;
            else
                return []() {
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
                    return std::meta::identifier_of(^^First);
#else
                    auto const typeName = Reflection::TypeNameOf<First>;
                    if (auto const i = typeName.rfind(':'); i != std::string_view::npos)
                        return typeName.substr(i + 1);
                    return typeName;
#endif
                }();
        }();
    };
 
    template <typename FieldType>
    constexpr auto ColumnNameOverride = []() consteval {
        if constexpr (requires { FieldType::ColumnNameOverride; })
            return FieldType::ColumnNameOverride;
        else
            return std::string_view {};
    }();
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
    template <auto reflection>
    struct FieldNameOfImpl
    {
        using R = typename[:std::meta::type_of(reflection):];
        static constexpr std::string_view value = []() constexpr -> std::string_view {
            if constexpr (requires { R::ColumnNameOverride; })
            {
                if constexpr (!R::ColumnNameOverride.empty())
                    return R::ColumnNameOverride;
            }
            return std::meta::identifier_of(reflection);
        }();
    };
#else
    template <typename ReferencedFieldType, auto F>
    struct FieldNameOfImpl;
 
    template <typename T, auto F, typename R>
    struct FieldNameOfImpl<R T::*, F>
    {
        static constexpr std::string_view value = []() constexpr -> std::string_view {
            if constexpr (requires { R::ColumnNameOverride; })
            {
                if constexpr (!R::ColumnNameOverride.empty())
                    return R::ColumnNameOverride;
            }
            return Reflection::NameOf<F>;
        }();
    };
#endif // LIGHTWEIGHT_CXX26_REFLECTION
 
    template <std::size_t I, typename Record>
    consteval std::string_view FieldNameAt()
    {
        // Prefer the pre-baked SQL column name from a generated descriptor (avoids the
        // expensive MangledName-based MemberNameOf evaluation); fall back to reflection.
        if constexpr (HasDescription<Record>)
        {
            return Description<Record>::FieldNames[I];
        }
        else
        {
            using FieldType = Reflection::MemberTypeOf<I, Record>;
 
            if constexpr (!std::string_view(ColumnNameOverride<FieldType>).empty())
            {
                return FieldType::ColumnNameOverride;
            }
            return Reflection::MemberNameOf<I, Record>;
        }
    }
} // namespace detail
 
/// @brief Returns the SQL field name of the given field index in the record.
///
/// @ingroup DataMapper
template <std::size_t I, typename Record>
constexpr inline std::string_view FieldNameAt = detail::FieldNameAt<I, Record>();
 
/// @brief Holds the SQL tabl ename for the given record type.
///
/// @ingroup DataMapper
template <typename Record>
constexpr std::string_view RecordTableName = detail::RecordTableNameImpl<Record>::Value;
 
template <template <typename...> class S, class T>
concept IsSpecializationOf = detail::is_specialization_of<S, T>::value;
 
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
 
/// @brief Returns the name of the field referenced by the given pointer-to-member.
///
/// This also supports custom column name overrides.
template <std::meta::info ReflectionOfField>
constexpr inline std::string_view FieldNameOf = detail::FieldNameOfImpl<ReflectionOfField>::value;
 
template <auto Member>
using MemberClassType = typename[:std::meta::parent_of(Member):];
 
template <auto Member>
constexpr size_t MemberIndexOf = []() consteval -> size_t {
    int index { -1 };
    auto members = nonstatic_data_members_of(std::meta::parent_of(Member), std::meta::access_context::current());
    if (auto it = std::ranges::find(members, Member); it != members.end())
    {
        index = std::distance(members.begin(), it);
        return static_cast<size_t>(index);
    }
    return -1;
}();
#else // not LIGHTWEIGHT_CXX26_REFLECTION
 
/// @brief Returns the name of the field referenced by the given pointer-to-member.
///
/// This also supports custom column name overrides.
template <auto ReferencedField>
constexpr inline std::string_view FieldNameOf = detail::FieldNameOfImpl<decltype(ReferencedField), ReferencedField>::value;
 
template <auto Member>
constexpr size_t MemberIndexOf = Reflection::MemberIndexOf<Member>;
 
template <typename T>
using MemberClassType = detail::MemberClassTypeHelper<T>::type;
 
#endif // LIGHTWEIGHT_CXX26_REFLECTION
 
/// @brief SqlQualifiedTableColumnName represents a column name qualified with a table name.
///
/// This is the single structural representation of a `table.column` reference used
/// throughout the query builder API. The builder is responsible for quoting; do not
/// pre-quote the values stored here.
///
/// @ingroup QueryBuilder
struct SqlQualifiedTableColumnName
{
    /// The table name.
    std::string_view tableName;
    /// The column name.
    std::string_view columnName;
 
    /// Three-way comparison operator.
    constexpr std::weak_ordering operator<=>(SqlQualifiedTableColumnName const&) const noexcept = default;
};
 
/// @brief Holds the fully qualified column reference (table + column) for the given field.
/// @tparam ReferencedField A pointer-to-member identifying the field.
///
/// @code
/// constexpr auto ref = FullyQualifiedNameOf<&Person::id>;
/// static_assert(ref.tableName == "Person");
/// static_assert(ref.columnName == "id");
/// @endcode
///
/// The result is an `SqlQualifiedTableColumnName` accepted by every column-name
/// entry point in the builder (`Field`, `Fields`, `Where`, `OrderBy`, `GroupBy`,
/// `Aggregate::*`, joins). The builder applies the quoting.
///
/// @ingroup DataMapper
template <auto ReferencedField>
constexpr inline auto FullyQualifiedNameOf = SqlQualifiedTableColumnName {
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
    .tableName = RecordTableName<typename[:std::meta::parent_of(ReferencedField):]>,
#else
    .tableName = RecordTableName<MemberClassType<decltype(ReferencedField)>>,
#endif
    .columnName = FieldNameOf<ReferencedField>,
};
 
namespace detail
{
    template <auto ReferencedField>
    struct FullyQualifiedQuotedNameOfImpl
    {
#if defined(LIGHTWEIGHT_CXX26_REFLECTION)
        static constexpr auto ClassName = RecordTableName<typename[:std::meta::parent_of(ReferencedField):]>;
#else
        static constexpr auto ClassName = RecordTableName<MemberClassType<decltype(ReferencedField)>>;
#endif
        static constexpr auto FieldName = FieldNameOf<ReferencedField>;
        static constexpr auto StorageSize = ClassName.size() + FieldName.size() + 6;
 
        // Holds the full field name in the format "ClassName"."FieldName"
        static constexpr auto Storage = []() constexpr -> std::array<char, StorageSize> {
            // clang-format off
            auto storage = std::array<char, StorageSize> {};
            std::ranges::copy("\"",      storage.begin());
            std::ranges::copy(ClassName, storage.begin() + 1);
            std::ranges::copy("\".\"",   storage.begin() + 1 + ClassName.size());
            std::ranges::copy(FieldName, storage.begin() + 1 + ClassName.size() + 3);
            std::ranges::copy("\"",      storage.begin() + 1 + ClassName.size() + 3 + FieldName.size());
            storage.back() = '\0';
            // clang-format on
            return storage;
        }();
        static constexpr auto value = std::string_view(Storage.data(), Storage.size() - 1);
    };
 
    template <auto ReferencedField>
    constexpr inline auto FullyQualifiedQuotedNameOf = FullyQualifiedQuotedNameOfImpl<ReferencedField>::value;
 
    template <auto... ReferencedFields>
    struct FullyQualifiedNamesOfImpl
    {
        static constexpr auto StorageSize =
            1 + (2 * (sizeof...(ReferencedFields) - 1)) + (0 + ... + FullyQualifiedQuotedNameOf<ReferencedFields>.size());
 
        static constexpr std::array<char, StorageSize> Storage = []() consteval {
            auto result = std::array<char, StorageSize> {};
            size_t offset = 0;
            (
                [&] {
                    if (offset > 0)
                    {
                        constexpr auto Delimiter = std::string_view(", ");
                        std::ranges::copy(Delimiter, result.begin() + offset);
                        offset += Delimiter.size();
                    }
                    std::ranges::copy(FullyQualifiedQuotedNameOf<ReferencedFields>, result.begin() + offset);
                    offset += FullyQualifiedQuotedNameOf<ReferencedFields>.size();
                }(),
                ...);
            result.back() = '\0';
            return result;
        }();
 
        static constexpr auto value = std::string_view(Storage.data(), Storage.size() - 1);
    };
 
    /// Pre-quoted, comma-joined fully qualified field names of the given fields.
    /// Internal helper used by DataMapper to embed column lists into SQL text directly.
    template <auto... ReferencedFields>
    constexpr inline auto FullyQualifiedNamesOf = FullyQualifiedNamesOfImpl<ReferencedFields...>::value;
 
} // namespace detail
 
// SqlFaultSource::NextFailure returns std::optional<SqlErrorInfo> by value, and instantiating
// std::optional<T> with an incomplete T is undefined ([optional.optional]/3) - so a forward
// declaration is not enough here and this header must carry the full definition.
 
/// @brief How a failed ODBC return code should surface to the caller.
///
/// @see ClassifyOdbcResult
enum class SqlFailureAction : uint8_t
{
    /// The call succeeded; the caller should carry on.
    None,
 
    /// Throw @c std::invalid_argument - a soft failure the caller is expected to recover from.
    ThrowInvalidArgument,
 
    /// Throw @c SqlException - a genuine SQL error.
    ThrowSqlException,
};
 
/// @brief Decides how a failed ODBC return code should surface, given the diagnostics already
///        retrieved from the driver.
///
/// This is the error-handling *policy* of the library, split out from @ref RequireSuccess so it can
/// be exercised without a database: it performs no I/O and touches no ODBC handle, so a test drives
/// it by constructing a @ref SqlErrorInfo - the approach `SqlErrorDetectionTests.cpp` already uses
/// for the error-classification helpers.
///
/// @param result    The ODBC return code being classified.
/// @param errorInfo The diagnostics corresponding to @p result.
/// @return The action the caller should take.
///
/// @note Deliberately not @c constexpr: @ref SqlErrorInfo holds @c std::string members, so a call
///       can never be a constant expression, and the keyword would only mislead.
[[nodiscard]] LIGHTWEIGHT_API SqlFailureAction ClassifyOdbcResult(SQLRETURN result, SqlErrorInfo const& errorInfo) noexcept;
 
LIGHTWEIGHT_API void LogIfFailed(SQLHSTMT hStmt, SQLRETURN error, std::source_location sourceLocation);
 
/// @brief Substitutes a scripted failure for an ODBC call that actually succeeded.
///
/// Exists so error-recovery paths can be driven from a test. Some failures cannot be provoked
/// through a real driver at all: a backup worker's transient-error retry arm needs a class-08 or
/// HYT00 SQLSTATE, but every fault reachable from a test file (unreachable driver, unwritable path,
/// dropped table) surfaces as HY000, which the retry policy classifies as non-transient. Without a
/// seam those arms are unreachable rather than merely untested.
///
/// Production code never installs one: with no source configured, @c RequireSuccess consults
/// nothing and returns on success exactly as before. This mirrors @c SqlDiagnosticSource and
/// @c SqlLogger::SetLogger, injection mechanisms the project already uses.
///
/// @see SetFaultSource
class SqlFaultSource
{
  public:
    SqlFaultSource() = default;
    SqlFaultSource(SqlFaultSource const&) = delete;
    SqlFaultSource& operator=(SqlFaultSource const&) = delete;
    SqlFaultSource(SqlFaultSource&&) = delete;
    SqlFaultSource& operator=(SqlFaultSource&&) = delete;
    virtual ~SqlFaultSource() = default;
 
    /// @brief Decides whether the next statement-handle check should fail.
    ///
    /// Called by @c RequireSuccess for a call that the driver reported as successful. Returning
    /// an engaged optional makes @c RequireSuccess throw @c SqlException carrying that
    /// diagnostic, as though the driver had failed.
    ///
    /// @note Never called for a null statement handle. @c RequireSuccess also guards
    ///       @c SQLAllocHandle during statement construction, where failing would leave a
    ///       half-constructed @c SqlStatement whose destructor cannot release the handle; it
    ///       therefore skips injection entirely while @p hStmt is still @c SQL_NULL_HSTMT. A fake
    ///       may narrow further via @p sourceLocation — the function name of a real execution is
    ///       @c ExecuteDirect / @c Execute / @c Prepare — but does not have to in order to be safe.
    ///
    /// @param hStmt The statement handle being checked, never @c SQL_NULL_HSTMT. A fake may ignore it.
    /// @param sourceLocation Where in the library the check is happening.
    /// @return The error to inject, or @c std::nullopt to let the successful call through.
    [[nodiscard]] virtual std::optional<SqlErrorInfo> NextFailure(SQLHSTMT hStmt,
                                                                  std::source_location const& sourceLocation) = 0;
 
    /// @brief Decides whether the next connection-handle check should fail.
    ///
    /// The connection-side counterpart of @ref NextFailure, consulted by
    /// @c detail::CheckOdbcConnectionCall for a call that the driver reported as successful on a
    /// @c SQLHDBC rather than a @c SQLHSTMT (e.g. a pre-connect attribute set). Returning an engaged
    /// optional makes the caller treat the call as failed, exactly as an injected @ref NextFailure
    /// does for a statement check.
    ///
    /// Defaults to never injecting, so a fake that predates connection-handle support and overrides
    /// only @ref NextFailure keeps compiling and behaving exactly as before.
    ///
    /// @note Never called for a null connection handle, for the same reason @ref NextFailure is never
    ///       called for a null statement handle: a fault injected while a @c SqlConnection is still
    ///       being constructed or is in the middle of tearing down its handle could leave the handle
    ///       leaked or double-released.
    ///
    /// @param hDbc The connection handle being checked, never @c SQL_NULL_HDBC. A fake may ignore it.
    /// @param sourceLocation Where in the library the check is happening.
    /// @return The error to inject, or @c std::nullopt to let the successful call through.
    [[nodiscard]] virtual std::optional<SqlErrorInfo> NextConnectionFailure(
        [[maybe_unused]] SQLHDBC hDbc, [[maybe_unused]] std::source_location const& sourceLocation)
    {
        return std::nullopt;
    }
};
 
/// @brief Installs a fault source process-wide.
///
/// Intended for tests. Ownership is not transferred and remains with the caller, which must keep
/// @p source alive until it is cleared. Pass @c nullptr to disable fault injection.
///
/// @param source The source to install, or @c nullptr to disable.
LIGHTWEIGHT_API void SetFaultSource(SqlFaultSource* source) noexcept;
 
/// @brief Returns the currently installed fault source, or @c nullptr if none is installed.
[[nodiscard]] LIGHTWEIGHT_API SqlFaultSource* GetFaultSource() noexcept;
 
/// @brief Throws unless the given ODBC return code indicates success.
///
/// Retrieves the diagnostics for @p hStmt and applies @ref ClassifyOdbcResult to decide how the
/// failure surfaces: @c std::invalid_argument for a soft failure the caller is expected to recover
/// from, @c SqlException otherwise.
///
/// @param hStmt The statement handle @p error came from.
/// @param error The ODBC return code to check.
/// @param sourceLocation Where the check originated; reported in the exception message. Defaults to
///                       the caller's location.
LIGHTWEIGHT_API void RequireSuccess(SQLHSTMT hStmt,
                                    SQLRETURN error,
                                    std::source_location sourceLocation = std::source_location::current());
 
namespace detail
{
    /// @brief Verdict of a non-throwing checked ODBC call, carrying the diagnostic that justifies a
    ///        failure verdict whenever that failure was injected rather than real.
    ///
    /// A bare @c bool is not enough here. When an installed @ref SqlFaultSource overrides a real
    /// success into a failure, the underlying ODBC call genuinely succeeded, so the handle holds no
    /// diagnostic records at all: a caller that recovers by *inspecting* the error (rather than
    /// merely branching on it) would read an empty or stale diagnostic off the handle and take the
    /// wrong recovery arm. Carrying the injected error alongside the verdict is what makes such an
    /// arm reachable from a test, which is the whole point of the seam.
    ///
    /// @see CheckOdbcCall, CheckOdbcConnectionCall
    struct OdbcCallOutcome
    {
        /// Whether the checked call should be treated as having succeeded.
        bool succeeded {};
 
        /// The injected diagnostic, engaged only when a @ref SqlFaultSource turned a real success
        /// into a failure. Never engaged for a genuine failure — that one's diagnostic is on the
        /// handle, where the caller can read it. Prefer @ref EffectiveError over branching on this
        /// directly.
        std::optional<SqlErrorInfo> injectedError {};
 
        /// @return @ref succeeded, so an outcome can be tested directly in an `if`.
        [[nodiscard]] explicit constexpr operator bool() const noexcept
        {
            return succeeded;
        }
 
        /// @brief The diagnostic describing this failure, from whichever source actually has one.
        ///
        /// @param readFromHandle Invoked only when the failure was not injected, to read the real
        ///                       handle's diagnostic (e.g. @c SqlErrorInfo::FromStatementHandle or
        ///                       @c SqlConnection::LastError). Deliberately lazy: reading
        ///                       diagnostics off a handle is an ODBC round-trip, and there is
        ///                       nothing to read when the failure was injected.
        /// @return The injected diagnostic when there is one, otherwise @p readFromHandle's result.
        template <typename ReadFromHandle>
            requires std::is_invocable_r_v<SqlErrorInfo, ReadFromHandle const&>
        [[nodiscard]] SqlErrorInfo EffectiveError(ReadFromHandle const& readFromHandle) const
        {
            return injectedError.has_value() ? *injectedError : readFromHandle();
        }
    };
 
    /// @brief Non-throwing checked-call helper for inline `SQL_SUCCEEDED` recovery checks against a
    ///        statement handle.
    ///
    /// Some recovery arms cannot go through @ref RequireSuccess because they must not throw: the
    /// caller recovers by branching (e.g. declining to retry, or declining to pool a handle), and
    /// that recovery is the whole point of being able to drive the call to its failure branch from a
    /// test. This helper gives such a call site the same fault-injection seam @ref RequireSuccess
    /// already offers, without the throw: the returned outcome carries the @c SQL_SUCCEEDED verdict
    /// for @p result, unless an installed @ref SqlFaultSource overrides a real success into an
    /// injected failure via @ref SqlFaultSource::NextFailure — in which case it also carries that
    /// injected diagnostic, since the handle has none to offer.
    ///
    /// Mirrors @ref RequireSuccess's safety property: never consults the fault source while @p hStmt
    /// is @c SQL_NULL_HSTMT, so a call made before a statement handle is fully valid cannot be
    /// disturbed by injection.
    ///
    /// @param result The ODBC return code to check.
    /// @param hStmt The statement handle @p result came from.
    /// @param sourceLocation Where the check originated; forwarded to the fault source. Defaults to
    ///                       the caller's location.
    /// @return The verdict for @p result, plus the injected diagnostic when one was injected.
    [[nodiscard]] LIGHTWEIGHT_API OdbcCallOutcome
    CheckOdbcCall(SQLRETURN result, SQLHSTMT hStmt, std::source_location sourceLocation = std::source_location::current());
 
    /// @brief Non-throwing checked-call helper for inline `SQL_SUCCEEDED` recovery checks against a
    ///        connection handle.
    ///
    /// The connection-handle counterpart of @ref CheckOdbcCall(SQLRETURN, SQLHSTMT,
    /// std::source_location): same contract, keyed on a @c SQLHDBC via
    /// @ref SqlFaultSource::NextConnectionFailure instead of @ref SqlFaultSource::NextFailure. Never
    /// consults the fault source while @p hDbc is @c SQL_NULL_HDBC, for the same reason the
    /// statement-handle overload skips a null @c SQLHSTMT.
    ///
    /// @param result The ODBC return code to check.
    /// @param hDbc The connection handle @p result came from.
    /// @param sourceLocation Where the check originated; forwarded to the fault source. Defaults to
    ///                       the caller's location.
    /// @return The verdict for @p result, plus the injected diagnostic when one was injected.
    [[nodiscard]] LIGHTWEIGHT_API OdbcCallOutcome CheckOdbcConnectionCall(
        SQLRETURN result, SQLHDBC hDbc, std::source_location sourceLocation = std::source_location::current());
} // namespace detail
 
/// Defines the naming convention for use (e.g. for C++ column names or table names in C++ struct names).
enum class FormatType : uint8_t
{
    /// Preserve the original naming convention.
    preserve,
 
    /// Ensure the name is formatted in snake_case naming convention.
    snakeCase,
 
    /// Ensure the name is formatted in CamelCase naming convention.
    camelCase,
};
 
/// @brief Converts a string to a format that is more suitable for C++ code.
LIGHTWEIGHT_API std::string FormatName(std::string const& name, FormatType formatType);
 
/// @brief Converts a string to a format that is more suitable for C++ code.
LIGHTWEIGHT_API std::string FormatName(std::string_view name, FormatType formatType);
 
/// Maintains collisions to create unique names
class UniqueNameBuilder
{
  public:
    /// Tests if the given name is already registered.
    [[nodiscard]] LIGHTWEIGHT_API bool IsColliding(std::string const& name) const noexcept;
 
    /// Tries to declare a name and returns it, otherwise returns std::nullopt.
    [[nodiscard]] LIGHTWEIGHT_API std::optional<std::string> TryDeclareName(std::string name);
 
    /// Creates a name that is definitely not colliding.
    [[nodiscard]] LIGHTWEIGHT_API std::string DeclareName(std::string name);
 
  private:
    std::unordered_map<std::string, size_t> _collisionMap;
};
 
} // namespace Lightweight