SqlGuid.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../SqlColumnTypeDefinitions.hpp"
#include "Core.hpp"
 
#include <algorithm>
#include <bit>
#include <charconv>
#include <format>
#include <optional>
#include <span>
#include <string>
 
namespace Lightweight
{
 
/// Represents a GUID (Globally Unique Identifier).
///
/// @ingroup DataTypes
struct LIGHTWEIGHT_API SqlGuid
{
    /// The raw GUID data bytes.
    uint8_t data[16] {};
 
    /// Creates a new non-empty GUID.
    static SqlGuid Create() noexcept;
 
    /// Parses a GUID from a string.
    static std::optional<SqlGuid> TryParse(std::string_view const& text) noexcept;
 
    /// Parses a GUID from a string. Use with caution and always prefer TryParse at all cost.
    static SqlGuid constexpr UnsafeParse(std::string_view const& text) noexcept;
 
    /// Three-way comparison operator.
    constexpr std::weak_ordering operator<=>(SqlGuid const& other) const noexcept = default;
 
    /// Equality comparison operator.
    constexpr bool operator==(SqlGuid const& other) const noexcept
    {
        return (*this <=> other) == std::weak_ordering::equivalent;
    }
 
    /// Inequality comparison operator.
    constexpr bool operator!=(SqlGuid const& other) const noexcept
    {
        return !(*this == other);
    }
 
    /// Tests if the GUID is non-empty.
    constexpr explicit operator bool() const noexcept
    {
        return *this != SqlGuid {};
    }
 
    /// Tests if the GUID is empty.
    constexpr bool operator!() const noexcept
    {
        return !static_cast<bool>(*this);
    }
};
 
constexpr SqlGuid SqlGuid::UnsafeParse(std::string_view const& text) noexcept
{
    SqlGuid guid {};
 
    // UUID format: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
    // M is the version and N is the variant
 
    // Check for length
    if (text.size() != 36)
        return { "\x01" };
 
    // Check for dashes
    if (text[8] != '-' || text[13] != '-' || text[18] != '-' || text[23] != '-')
        return { "\x02" };
 
    // Version must be 1, 2, 3, 4, or 5
    auto const version = text[14];
    if (!('1' <= version && version <= '5'))
        return { "\x03" };
 
    // Variant nibble at position 19 must be a valid hex digit
    // We accept all variants (RFC 4122: 8-B, Microsoft: C-D, etc.)
    auto const variant = text[19];
    auto const isHexDigit =
        (variant >= '0' && variant <= '9') || (variant >= 'A' && variant <= 'F') || (variant >= 'a' && variant <= 'f');
    if (!isHexDigit)
        return { "\x04" };
 
    // clang-format off
    size_t i = 0;
    for (auto const index: { 0, 2, 4, 6,
                             9, 11,
                             14, 16,
                             19, 21,
                             24, 26, 28, 30, 32, 34 })
    {
        if (std::from_chars(text.data() + index, text.data() + index + 2, guid.data[i], 16).ec != std::errc())
            return { "\x05" };
        i++;
    }
    // clang-format on
 
    return guid;
}
 
} // namespace Lightweight
 
template <>
struct std::formatter<Lightweight::SqlGuid>: std::formatter<std::string>
{
    LIGHTWEIGHT_FORCE_INLINE auto format(Lightweight::SqlGuid const& guid, format_context& ctx) const
        -> format_context::iterator
    {
        // clang-format off
        return formatter<std::string>::format(std::format(
                "{:08X}-{:04X}-{:04X}-{:04X}-{:012X}",
                (uint32_t) guid.data[3] | (uint32_t) guid.data[2] << 8 |
                    (uint32_t) guid.data[1] << 16 | (uint32_t) guid.data[0] << 24,
                (uint16_t) guid.data[5] | (uint16_t) guid.data[4] << 8,
                (uint16_t) guid.data[7] | (uint16_t) guid.data[6] << 8,
                (uint16_t) guid.data[9] | (uint16_t) guid.data[8] << 8,
                (uint64_t) guid.data[15] | (uint64_t) guid.data[14] << 8 |
                    (uint64_t) guid.data[13] << 16 | (uint64_t) guid.data[12] << 24 |
                    (uint64_t) guid.data[11] << 32 | (uint64_t) guid.data[10] << 40
            ),
            ctx
        );
        // clang-format on
    }
};
 
namespace Lightweight
{
 
inline LIGHTWEIGHT_FORCE_INLINE std::string to_string(SqlGuid const& guid)
{
    return std::format("{}", guid);
}
 
namespace detail
{
    /// Swaps `data[0..7]` between `SqlGuid`'s canonical byte order (the order `TryParse()`,
    /// `UnsafeParse()`, and the `std::formatter` specialization agree on: `data[i]` is the i-th
    /// hex-pair of the textual representation, left to right) and the physical `SQL_C_GUID` /
    /// Win32 `GUID` wire layout that ODBC drivers expect for `Data1`/`Data2`/`Data3` (those three
    /// fields are transmitted in native/little-endian byte order, not textual order). `data[8..15]`
    /// (`Data4`) is a plain byte array in both representations and is left untouched.
    ///
    /// Self-inverse: applying this twice restores the original bytes. Every call site that binds
    /// or fetches raw `SQL_C_GUID` bytes (bypassing `SqlDataBinder<SqlGuid>`'s own conversion) must
    /// apply this exactly once when crossing that boundary, in either direction.
    ///
    /// @param data The 16-byte GUID payload to convert in place.
    inline void SwapGuidWireByteOrder(std::span<uint8_t, 16> data) noexcept
    {
        // The reversal below undoes exactly the byte-order change a little-endian host applies
        // when it stores Data1/Data2/Data3 as native integers; on a big-endian host those fields
        // are already in textual order and reversing them would corrupt the GUID instead. Assume
        // little-endian, matching the project-wide precedent in SqlNumeric.hpp.
        static_assert(std::endian::native == std::endian::little);
 
        // Data1 (4 bytes), Data2 (2) and Data3 (2) differ between the two representations;
        // Data4 (the trailing 8) is a plain byte array in both and is left untouched.
        std::ranges::reverse(data.first<4>());
        std::ranges::reverse(data.subspan<4, 2>());
        std::ranges::reverse(data.subspan<6, 2>());
    }
} // namespace detail
 
template <>
struct LIGHTWEIGHT_API SqlDataBinder<SqlGuid>
{
    static constexpr auto ColumnType = SqlColumnTypeDefinitions::Guid {};
 
    static SQLRETURN InputParameter(SQLHSTMT stmt,
                                    SQLUSMALLINT column,
                                    SqlGuid const& value,
                                    SqlDataBinderCallback& cb) noexcept;
 
    static SQLRETURN OutputColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, SqlGuid* result, SQLLEN* indicator, SqlDataBinderCallback& cb) noexcept;
 
    static SQLRETURN GetColumn(
        SQLHSTMT stmt, SQLUSMALLINT column, SqlGuid* result, SQLLEN* indicator, SqlDataBinderCallback const& cb) noexcept;
 
    static LIGHTWEIGHT_FORCE_INLINE std::string Inspect(SqlGuid const& value) noexcept
    {
        return std::format("{}", value);
    }
};
 
} // namespace Lightweight