SqlGuid.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../SqlColumnTypeDefinitions.hpp"
#include "Core.hpp"
 
#include <algorithm>
#include <array>
#include <bit>
#include <charconv>
#include <format>
#include <optional>
#include <ranges>
#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 its 36-character `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` text form.
    ///
    /// Any hex value is accepted, whatever its version and variant nibbles, as SQL Server's
    /// `uniqueidentifier` does. `data[i]` receives the i-th hex pair of the text, left to right.
    ///
    /// @param text The GUID text, upper or lower case.
    /// @return The parsed GUID, or `std::nullopt` if @p text is not a well-formed GUID.
    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.
    ///
    /// Accepts the same texts as TryParse(); for any other text it returns an unspecified sentinel.
    /// @param text The GUID text.
    /// @return The parsed GUID.
    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);
    }
};
 
namespace detail
{
    /// Tests whether @p character is a hexadecimal digit.
    /// @param character The character to test.
    /// @return `true` for `0-9`, `a-f` and `A-F`.
    constexpr bool IsHexDigit(char character) noexcept
    {
        return (character >= '0' && character <= '9') || (character >= 'a' && character <= 'f')
               || (character >= 'A' && character <= 'F');
    }
 
    /// Tests whether @p text has the 8-4-4-4-12 hex-digit form of a GUID.
    /// @param text The text to test.
    /// @return `true` if @p text is 36 characters, dashes at 8, 13, 18 and 23, hex digits elsewhere.
    constexpr bool IsWellFormedGuidText(std::string_view text) noexcept
    {
        constexpr auto IsDashPosition = [](size_t position) {
            return position == 8 || position == 13 || position == 18 || position == 23;
        };
        if (text.size() != 36)
            return false;
        return std::ranges::all_of(std::views::iota(size_t { 0 }, text.size()), [&](size_t position) {
            return IsDashPosition(position) ? text[position] == '-' : IsHexDigit(text[position]);
        });
    }
 
    /// Returns the value of the hex digit @p character, which must satisfy IsHexDigit().
    /// @param character The hex digit.
    /// @return Its value, 0 to 15.
    constexpr uint8_t HexDigitValue(char character) noexcept
    {
        if (character >= '0' && character <= '9')
            return static_cast<uint8_t>(character - '0');
        if (character >= 'a' && character <= 'f')
            return static_cast<uint8_t>(character - 'a' + 10);
        return static_cast<uint8_t>(character - 'A' + 10);
    }
} // namespace detail
 
constexpr SqlGuid SqlGuid::UnsafeParse(std::string_view const& text) noexcept
{
    // Format: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx. The version (M) and variant (N) nibbles are
    // not checked: SQL Server stores any value, and older Lightweight builds wrote GUIDs with
    // byte-swapped Data1, Data2 and Data3, which leaves an arbitrary digit where the version sits.
    if (!detail::IsWellFormedGuidText(text))
        return { "\x01" };
 
    SqlGuid guid {};
    // clang-format off
    size_t i = 0;
    for (size_t const index: std::array<size_t, 16> { 0, 2, 4, 6,
                                                      9, 11,
                                                      14, 16,
                                                      19, 21,
                                                      24, 26, 28, 30, 32, 34 })
    {
        guid.data[i] = static_cast<uint8_t>((detail::HexDigitValue(text[index]) << 4)
                                            | detail::HexDigitValue(text[index + 1]));
        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